Structural elements
Last modified: 13 June 2024Use 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 AltEnter, 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.
Topic navigation
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 for="chapter,procedure"/>
Show all chapter and procedure titles at all levels.
tip
Besides
chapter
andprocedure
, you can specifytab
to show titles of tabs anddef
to show titles of items in definition lists.
Thanks for your feedback!