Lists

Organize items into ordered and unordered lists when documenting supported features or numbered annotations in a screenshot. Lists help emphasize important ideas and add visual structure similar to tables, admonitions, and tabs.

To add a list, use the <list> element and <li> sub-elements for each list item. By default, Writerside renders an unordered list with bullet points. Use the type attribute to change the list markers:

type="decimal": decimal digits (1, 2, 3, and so on) when the order or total number of items in a list is important
type="alpha-lower": letters (a, b, c, and so on) for an ordered nested list
type="none": for a list without markers

In Markdown, to create an ordered list, use numbers followed by periods. To create an unordered list, use dashes -, asterisks *, or plus characters +. Indent items to create a nested list. You can add list attributes in curly braces after an empty line.

                <list type="decimal" start="2">
                    <li>First item.
                        <list type="alpha-lower">
                            <li>First indented item.</li>
                            <li>Second indented item.</li>
                        </list>
                    </li>
                    <li>Second item.</li>
                    <li>Third item.</li>
                    <li>Fourth item.</li>
                </list>

                <list type="bullet">
                    <li>Some list item</li>
                    <li>Another list item</li>
                    <li>Yet another list item
                        <list type="bullet">
                            <li>Indented item</li>
                            <li>Indented item</li>
                        </list>
                    </li>
                    <li>One more item</li>
                </list>
            

                1. First item.
                    1. First indented item.
                    2. Second indented item.

                    {type="alpha-lower"}
                2. Second item.
                3. Third item
                4. Fourth item

                {start="2"}

                - Some list item
                - Another list item
                - Yet another list item
                    - Some indented item
                    - Another indented item
                - One more item
            

Here is the list produced from the previous example:

First item.
1. First indented item.
2. Second indented item.
Second item.
Third item.
Fourth item.

Some list item
Another list item
Yet another list item
- Some indented item
- Another indented item
One more item

These are not strict rules, but it is better to keep the following in mind when adding lists:

Write a paragraph before a list to introduce it. A list without an introduction can be unclear.
Include between 2 and 8 items in a list. Having too many items can be overwhelming and you will emphasize nothing. If you need a long list of short items, consider using multiple columns.
Limit the size of each item as much as possible. Do not expand a list item beyond its most basic idea. If you need to provide a lot of details for each item, consider using a definition list or splitting the content into chapters.
Avoid overusing lists. Lists are a good way to add structure between paragraphs, but having all content as lists does not provide the necessary context. Also, consider other elements, such as tables and tabs.

Multiple columns

If you have a long list of very short items, such as product names or commands, render the list in multiple columns, so it does not take a lot of vertical space.

                    <list columns="3">
                        <li>this</li>
                        <li>is</li>
                        <li>a</li>
                        <li>long</li>
                        <li>list</li>
                        <li>rendered</li>
                        <li>in</li>
                        <li>three</li>
                        <li>columns</li>
                    </list>
                

                    - this
                    - is
                    - a
                    - long
                    - list
                    - rendered
                    - in
                    - multiple
                    - columns

                    {columns="3"}
                

Here is the list produced from the previous example:

this
is
a
long
list
rendered
in
three
columns

Definition lists

Definition lists are a great way to document references of commands, options, methods, API endpoints, parameters, and UI controls. You can also use them for documenting frequently asked questions (FAQ) and troubleshooting guides.

To add a definition list, use the <deflist> element and <def> sub-elements for each definition item.

In Markdown specify the term on the first line, then on the next line, type a colon : followed by a space and the definition. You can specify definition list attributes in curly braces before the first term.

                    <deflist>
                        <def title="First Term">
                            This is the definition of the first term.
                        </def>
                        <def title="Second Term">
                            This is the definition of the second term.
                        </def>
                    </deflist>
                

                    First Term
                    : This is the definition of the first term.

                    Second Term
                    : This is the definition of the second term.
                

Here is the definition list produced from the previous example:

First Term: This is the definition of the first term.
Second Term: This is the definition of the second term.

By default, Writerside renders the title of every definition element on a separate line, which is suitable for FAQs or troubleshooting problems. For shorter definition items, specify the type attribute:

type="full" is the default type of definition lists suitable for FAQs and troubleshooting guides. Use it when definition list item titles are long.

Can I use definition lists to document frequently asked questions (FAQs)?: Sure, you can.
somePeculiarMethodWithReallyLongName(): This name probably will not fit if you use any other type of definition list.

Set type="wide" to render the definition title and its description side-by-side at a 1:1 ratio. This can be a good choice for a reference of REST API endpoints.

/customers: Get customers.
/customers/{customerId}: Get customer by ID.
/customers/{customerId}/accounts: Get the accounts of the specified customer.

Set type="medium" to render the definition title and its description side-by-side at a 1:2 ratio. This can be a good choice for a reference of methods or functions.

getFoo(): Returns the current value of Foo.
setBar(String): Assigns the provided string to Bar.
multiply(int, int): Returns the product of two integers.

Set type="narrow" to render the definition title and its description side-by-side at a 2:7 ratio. This can be a good choice for a reference of command-line options.

--output: Specify where to save the output.
--print: Print something
--version: Show version.

Set type="compact" to render the definition title and its description side-by-side at a 1:8 ratio. This can be a good choice for a reference of abbreviations or single-letter options.

-o: Specify where to save the output.
-p: Print something.
-v: Show version.

For information about making the definition list collapsible, see Collapsible elements.

Last modified: 05 June 2024