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 decide to manually number your ordered list, you have to keep them 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

However, in general the best practice is to use the start attribute to configure this sort of thing:

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

To present the 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.