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 number the ordered list explicitly, you have to manually keep the list numerals sequential. Otherwise, you will get a warning. This differs from other lightweight markup languages. But there’s a reason for it.

Using explicit numbering is 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, there’s a simpler way to accomplish the same result without the manual effort. You can use the start attribute on the list to define the number at which you want the numerals to start.

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

The start value is always a positive integer value even when using a different numeration style such as loweralpha.

When not to use the start attribute

When an ordered list item contains block content—​such as an image, source block, or table—​you may observe that the number of the next item in the list resets to 1. In fact, what’s happened is that a new list has been started where the number resets due to a missing list continuation.

In these cases, you should not resort to using the start attribute to fix the numbering. Not only does that require manual adjustment as items are added to the list, it doesn’t address the underlying semantics problem, which is what is causing it to be broken. Instead, use a list continuation between each block element you want to attach to the list item to ensure the list item is continuous. The list continuation glues the blocks together within a given item and keeps them at the same level of indentation.

  • For details on how to use a list continuation, refer to the Complex List Items page.

  • 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 AsciiDoc 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 the convention that the number of dots equals the level of nesting.

# 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. The AsciiDoc syntax tries 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, AsciiDoc 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.

Escaping the list marker

If you have paragraph text that begins with a list marker, but you don’t intend it to be a list item, you need to escape that marker by using the attribute reference to disrupt the pattern.

Consider the case when the line starts with a P.O. box reference:

P. O. Box

In order to prevent this paragraph from being parsed as an ordered list, you need to replace the first space with {empty}.

P.{empty}O. Box

Now the paragraph will remain as a paragraph.

In the future, it will be possible to escape an ordered list marker using a backslash, but that is not currently possible.