Structural elements

Use structural elements to organize a topic into a hierarchy of chapters, subchapters, and procedures. This helps readers to 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.

The <chapter> element has the following attributes:

title

Every chapter must have a heading defined by the title attribute.

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.

collapsible

Make the chapter collapsible by setting collapsible="true".

Possible values: true or false (default).

default-state

Specify the default state for a collapsible chapter. You can set the default state only if the chapter is collapsible.

Possible values: expanded or collapsed (default).

caps

Specify the case to use for the chapter title.

Possible values: title, sentence, upper, lower, or aswritten (default).

id

Specify a unique identifier to use as a link anchor and generate a meaningful URL for this chapter. You can reference and reuse any element that has an ID.

filter

Define a set of custom filters for conditionally including this chapter.

instance

Define a set of instances for conditionally filtering this chapter.

switcher-key

Make this chapter switchable depending on the selected key.

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>
            
        

The <procedure> element has the following attributes:

title

Specify a title for the procedure: usually a user's task in the imperative form. You can leave it empty if the parent element (topic or chapter) already has a title that clearly describes the task.

type

Specify the type of procedure. Most procedures are a sequence of actions defined by the default type="steps" attribute that renders the steps as an ordered list. Sometimes, however, the steps are alternative ways of performing a task, in which case, set type="choices" to render the steps as an unordered list with bullet points.

Procedure with numbered steps

Step 1.
Step 2.
Step 3.

Procedure with choices

Option 1.
Option 2.
Option 3.

collapsible

Make the procedure collapsible by setting collapsible="true".

Possible values: true or false (default).

default-state

Specify the default state for a collapsible procedure. You can set the default state only if the procedure is collapsible.

Possible values: expanded or collapsed (default).

caps

Specify the case to use for the procedure title.

Possible values: title, sentence, upper, lower, or aswritten (default).

id

Specify a unique identifier to use as a link anchor and generate a meaningful URL for this procedure. You can reference and reuse any element that has an ID.

filter

Define a set of custom filters for conditionally including this procedure.

instance

Define a set of instances for conditionally filtering this procedure.

switcher-key

Make this procedure switchable depending on the selected key.

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 topic navigation component for a topic. For example, to include chapter and procedure titles up to level 2:

<show-structure for="chapter,procedure" depth="2"/>

The <show-structure> element has the following attributes:

for

Specify a comma-separated list of elements to include in the topic navigation.

Default value is for="chapter".

depth

Specify the maximum depth of elements to include in the topic navigation.

Default value is depth="1".

To disable the topic navigation block, set depth="0".

Last modified: 05 October 2023