Writerside Help

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:

  1. First item.

    1. First indented item.

    2. Second indented item.

  2. Second item.

  3. Third item.

  4. Fourth item.

  • Some list item

  • Another list item

  • Yet another list item

    • Some indented item

    • Another indented item

  • One more item

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: 16 May 2024