Structural elements

Use structural elements to organize a topic into a hierarchy of chapters, subchapters, and procedures. This helps readers navigate a long document.

Chapters

Use chapters to split a long subject into smaller chunks of content.

In semantic markup, define chapters with the <chapter> element. In Markdown, define chapters with headings. For example, here is how you can add a collapsible chapter with a subchapter:

                    
                     <chapter title="Example chapter" id="example-chapter-id">
                        <p>Some text.</p>
                        <chapter title="Subchapter" id="subchapter">
                            <p>Some more text.</p>
                        </chapter>
                     </chapter>
                     
                

                    
                    ## Example chapter {id="example-chapter-id"}

                    Some text.

                    ### Subchapter

                    Some more text.

In Markdown, the chapter heading automatically becomes its title, unless you specify the title attribute explicitly:

# Title becomes the topic title H1.
## Title for top-level chapters H2.
### Title for subchapters H3, and so on.

By default, the topic navigation on the right contains links to all first-level chapters. You can change this using the <show-structure> element. For more information, see Topic navigation.

Procedures

Use procedures to describe instructions for performing a specific task. This is usually a sequence of actions, but it can be only one or a choice of several actions.

Use the <procedure> element to add a procedure block. Describe each action in a <step> element:

            
                <procedure title="Add something" id="procedure-id">
                   <p>Before adding something, create it.</p>
                   <step>Do this.</step>
                   <step>Do that.</step>
                   <p>Congratulation! You've added something.</p>
                </procedure>
            
        

By default, the topic navigation on the right doesn't contain links to procedures. You can change this using the <show-structure> element. For more information, see Topic navigation.

Unlike generic ordered and unordered lists, procedures stand out visually, making it easier for readers to find instructions related to the subject as they skim over an article, which is likely what they're looking for. Writerside has an action for converting lists to procedures.

Convert list to procedure

Put the caret inside a list element, press Alt+Enter, and select the Convert list element to procedure.

This action converts an ordered list into a procedure with a sequence of steps and an unordered list into a procedure with choices.

Titles

Chapters and procedures divide your topics into logical pieces of content. Providing good headings for those pieces helps readers find the necessary information.

In most cases, you define the heading using the title attribute of an element. You can override the title attribute using the <title> element inside the element. This can be useful, for example, if you need a different chapter title for a specific help instance:

                    <chapter title="Default chapter title" id="default-chapter-id">
                        <title instance="foo">Chapter title for Foo</title>
                        <p>Some text.</p>
                    </chapter>
                

                    ## Default chapter title {id="default-chapter-id"}
                    <title instance="foo">Chapter title for Foo</title>

                    Some text.
                

By default, Writerside renders links to first-level chapters on the right side of the topic page. This helps your readers navigate between different parts of the topic.

Add <show-structure> as a direct child of the <topic> element to configure the navigation component for a topic. Here are some examples:

<show-structure/>: Show all elements with titles at all levels.
<show-structure for="none"/>: Do not show the topic navigation block.
<show-structure for="chapter,procedure"/>: Show all chapter and procedure titles at all levels.
Besides chapter and procedure, you can specify tab to show titles of tabs and def to show titles of items in definition lists.
<show-structure depth="2"/>: Show all elements with titles up to level 2.
<show-structure for="chapter,procedure" depth="2"/>: Show all chapter and procedure titles up to level 2.

Last modified: 13 June 2024