Ordered and Unordered Lists

On this page, you’ll learn:

  • How to mark up an ordered list with AsciiDoc.

  • How to mark up an unordered list with AsciiDoc.

  • How to add other AsciiDoc elements to a list item.

  • How to mix ordered and unordered items in the same list.

Ordered list syntax

Ordered lists are useful when you need to number list items. First level list items are created with a single dot (a period) and nested items by using two or more dots in front of each the item. The dot (or dots) is separated from the content of the list item by a single space.

Example 1. Ordered list with nested levels
. Step 1
. Step 2
.. Details
... Mini-details
.... Micro-details
..... We're really down in the weeds now.
.. More details
. Step 3

You can nest unordered lists to any depth. A different numbering or lettering scheme (e.g., arabic, alpha, roman, etc) used to identify each nesting level. However, the depth at which a unique scheme is applied depends on the stylesheet. The scheme will fallback to the browser default (arabic numbering) beyond that depth.

  1. Step 1

  2. Step 2

    1. Details

      1. Mini-details

        1. Micro-details

          1. We’re really down in the weeds now.

    2. More details

  3. Step 3

You can control the numbering scheme using the list style.

  1. alpha

  2. beta

  3. gamma

You can control the start value using the start attribute.

  1. Picking up where we left off.

  2. Add one more ingredient.

  3. Mix and serve!

Unordered list syntax

When your list doesn’t need to be numbered, use an unordered list. First level list items are marked using an asterisk (*) and nested items by two or more asterisk.

Example 2. Unordered list with nested levels
* Item A
* Item B
** Item B1
*** Details
**** More details
***** Details about the details
** Item B2
* Item C

You can nest unordered lists to any depth. Unordered lists use a bullet or other illustrative marker in front of each list item to identify each nesting level. However, the depth at which a unique marker is applied depends on the stylesheet. The scheme will fallback to the browser default (a square bullet) beyond that depth.

  • Item A

  • Item B

    • Item B1

      • Details

        • More details

          • Details about the details

    • Item B2

  • Item C

You’ll use AsciiDoc’s unordered list syntax to structure your site’s navigation as well.

Complex ordered and unordered lists

List items can be any AsciiDoc element. You can also mix ordered and unordered list items. Let’s look at an example that contains a variety of content and list item types.

* A list item can contain two or more paragraphs or blocks of content.
+ (1)
[source,yaml]
----
  artifacts:
    expire_in: 1 week
----
+ (1)
====
An example block
====

** A literal paragraph doesn't require a list continuation.

 $ antora antora-playbook.yml

* You can also mix list item types in the same list.
** Unordered list item
... Ordered list item
.... Another ordered list item
+ (1)
term:: A description list term and content.
1 A list continuation is a plus symbol (+) on a line by itself that is immediately adjacent to the block being attached.

To add additional paragraphs or blocks to a list item, you must attach them with a list continuation (+).

Here’s how the complex list above is rendered.

  • A list item can contain two or more paragraphs or blocks of content.

      artifacts:
    expire_in: 1 week

    An example block

    • A literal paragraph doesn’t require a list continuation.

      $ antora antora-playbook.yml

  • You can also mix list item types in the same list.

    1. Ordered list item

      • Unordered list item

        1. Another ordered list item

          term

          A description list term and content.

Alternatively, when a list item contains multiple blocks, you can wrap them in a delimited open block (--). Then you only need a single list continuation line to attach the open block to the list item.

Example 3. Use an open block instead of multiple list continuations
* A list item that includes several blocks wrapped in an open block.
+ (1)
-- (2)
[source,yaml]
----
  artifacts:
    expire_in: 1 week
----

====
An example block
====

Another paragraph
-- (2)
1 Single list continuation attaching the open block to the list item.
2 Open block delimiters wrapping multiple blocks.

Here’s how that example looks when rendered.

  • A list item that includes several blocks wrapped in an open block.

      artifacts:
    expire_in: 1 week

    An example block

    Another paragraph

You can find another complex list example on the description list page.

AsciiDoc and Asciidoctor resources