Ordered Lists

Basic ordered list

Sometimes, we need to number the items in a list. Instinct might tell you to prefix each item with a number, like in this next list:

1. Protons
2. Electrons
3. Neutrons

The above works, but since the numbering is obvious, the AsciiDoc processor will insert the numbers for you if you omit them:

. Protons
. Electrons
. Neutrons
  1. Protons

  2. Electrons

  3. Neutrons

If you manually number your ordered list, you have to keep the items sequential. This differs from other lightweight markup languages. It’s one way to adjust the numbering offset of a list. For instance, you can type:

4. Step four
5. Step five
6. Step six

In general, though, rather than typing numbers, if you need to interrupt the default sequence, use the start attribute:

[start=4]
. Step four
. Step five
. Step six

When your ordered-list items include multiple block elements—images, captions, code, tables, paragraphs, source blocks, etc., as is often the case when you document steps in a procedure—your steps may reset to 1 when you don’t want them to. In these cases, don’t use the start attribute to continue the numbering. You don’t want to have to manually update start numbers or risk having the start numbers become wrong every time you add or remove a step. Instead, use a list continuation—a + symbol on its own line—between block elements. The list continuation glues the elements together within a given step. If a step includes any blank lines between elements, the next step goes back to 1. (A blank line directly before a step has no effect on step numbering.) The list continuation also keeps the elements aligned at the same level of indent, as shown here:

Example of continuous step numbering with complex content
  • For how-to details, see the List Continuation section of this documentation.

  • For an example of the list continuation used in a complex ordered list, see the launch steps in this .adoc file in GitHub.

  • To see how those launch steps look in the final output, see the Launch the Quick Start section of the generated deployment guide. The list continuations prevent step 2 from resetting to 1. They also prevent step 5, which is pulled in from a separate .adoc file, from resetting to 1.

To present list items in reverse order, add the reversed option:

[%reversed]
.Parts of an atom
. Protons
. Electrons
. Neutrons
Parts of an atom
  1. Protons

  2. Electrons

  3. Neutrons

You can give a list a title by prefixing the line with a dot immediately followed by the text (without leaving any space after the dot).

Here’s an example of a list with a title:

.Parts of an atom
. Protons
. Electrons
. Neutrons
Parts of an atom
  1. Protons

  2. Electrons

  3. Neutrons

Nested ordered list

You create a nested item by using one or more dots in front of each the item.

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

AsciiDoc selects a different number scheme for each level of nesting. Here’s how the previous list renders:

A nested ordered list
  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

Like with the asterisks in an unordered list, the number of dots in an ordered list doesn’t represent the nesting level. However, it’s much more intuitive to follow this convention:

# of dots = level of nesting

Again, we are shooting for plain text markup that is readable as is.

You can mix and match the three list types, ordered, unordered, and description, within a single hybrid list. Asciidoctor works hard to infer the relationships between the items that are most intuitive to us humans.

Here’s an example of nesting an unordered list inside of an ordered list:

. Linux
* Fedora
* Ubuntu
* Slackware
. BSD
* FreeBSD
* NetBSD
  1. Linux

    • Fedora

    • Ubuntu

    • Slackware

  2. BSD

    • FreeBSD

    • NetBSD

You can spread the items out and indent the nested lists if that makes it more readable for you:

. Linux

  * Fedora
  * Ubuntu
  * Slackware

. BSD

  * FreeBSD
  * NetBSD

The description list page demonstrates how to combine all three list types.

Number styles

For ordered lists, Asciidoctor supports the numeration styles such as lowergreek and decimal-leading-zero. The full list of numeration styles that can be applied to an ordered list are as follows:

Block style CSS list-style-type

arabic

decimal

decimal [1]

decimal-leading-zero

loweralpha

lower-alpha

upperalpha

upper-alpha

lowerroman

lower-roman

upperroman

upper-roman

lowergreek [1]

lower-greek

[1] These styles are only supported by the HTML converters.

Here are a few examples showing various numeration styles as defined by the block style shown in the header row:

[arabic] [2] [decimal] [loweralpha] [lowergreek]
  1. one

  2. two

  3. three

  1. one

  2. two

  3. three

  1. one

  2. two

  3. three

  1. one

  2. two

  3. three

[2] Default numeration if block style is not specified

Custom numeration styles can be implemented using a custom role. Define a new class selector (e.g., .custom) in your stylesheet that sets the list-style-type property to the value of your choice. Then, assign the name of that class as a role on any list to which you want that numeration applied.

When the role shorthand (.custom) is used on an ordered list, the numeration style is no longer omitted.

You can override the number scheme for any level by setting its style (the first positional entry in a block attribute list). You can also set the starting number using the start attribute:

["lowerroman", start=5]
. Five
. Six
[loweralpha]
.. a
.. b
.. c
. Seven
  1. Five

  2. Six

    1. a

    2. b

    3. c

  3. Seven

The start attribute must be a number, even when using a different numeration style. For instance, to start an alphabetic list at letter "c", set the numeration style to loweralpha and the start attribute to 3.