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

The maximum nesting level is five (.....). A different numbering or lettering scheme is provided for each nesting level.

Step 1
Step 2
1. Details
  1. Mini-details
    
    Micro-details
    
    We’re really down in the weeds now.
2. More details
Step 3

You can control the numbering scheme using the list style.

alpha
beta
gamma

You can control the start value using the start attribute.

Picking up where we left off.
Add one more ingredient.
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

The maximum nesting level is five (*****). Unordered lists use a bullet or other illustrative marker before each list item depending on nesting level.

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
    
    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.

Asciidoctor resources