Starting pages

It is good for your readers and for SEO to provide an overview of you documentation and separate sections. These overviews group the most useful and popular topics or those dedicated to a specific subject. You can also use it to provide a learning path for readers: where to begin, which topics are generic and which are more advanced or cover some specific subsystem.

To convert a topic to a starting page, add the <section-starting-page> element to the root <topic> element.

To create a new starting page topic, select the Section starting page template when creating a topic.

Here is an example of a starting page topic markup:

<section-starting-page> <title>Section starting page title</title> <description> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed condimentum feugiat sagittis. </description> <spotlight> <a href="Topic1.topic" summary="Sed condimentum feugiat sagittis" type="start"/> <a href="Topic2.topic" summary="Sed condimentum feugiat sagittis" type="search"/> ... </spotlight> <primary> <title>Main group</title> <a href="Topic.topic" summary="Sed condimentum feugiat sagittis"/> ... </primary> <secondary> <title>Highlighted group</title> <a href="Topic.topic" summary="Sed condimentum feugiat sagittis"/> ... </secondary> <misc> <cards> <title>Custom cards</title> <a href="Topic.topic" summary="Sed condimentum feugiat sagittis"/> ... </cards> <links narrow="true"> <group> <title>Custom links</title> <a href="Topic.topic" summary="Sed condimentum feugiat sagittis"/> ... </group> ... </links> </misc> </section-starting-page>

The <section-starting-page> element has some predefined structure:

Use the <spotlight> element to provide links for two of the most important topics. Set the type to define what icon the spotlight card should have.
Use the <primary> and <secondary> elements to provide links for other important and useful topics.
If necessary, use the <misc> element to provide links or cards to additional relevant topics.
Add groups of <links> and <cards>. For links, use the <group> element to split them into groups of links.
By default, additional miscellaneous groups are rendered in two columns. Add narrow="true" to a group if you want to render it in three narrow columns instead

Last modified: 21 June 2024