List Continuation

This section applies to complex lists—​ordered or unordered lists that have multiple lines of text per item or that contain a mix of content types—​that you want to keep continuous.

Indented lines

As with regular paragraph text, the text in a list item can wrap across any number of lines as long as all the lines are adjacent. Multiple lines are combined into a paragraph and wrap as normal paragraph text even if they’re indented, as shown in the third bullet in this example:

* The header in AsciiDoc is optional, but if
it is used it must start with a document title.

* Optional Author and Revision information
immediately follows the header title.

* The document header must be separated from
  the remainder of the document by one or more
  blank lines and cannot contain blank lines.
  • The header in AsciiDoc is optional, but if it is used it must start with a document title.

  • Optional Author and Revision information immediately follows the header title.

  • The document header must be separated from the remainder of the document by one or more blank lines and cannot contain blank lines.

When list items contain more than one line of text, leave a blank line between items to make the list easier to read while working in the code.

Blank lines between items in an ordered list do not reset numbering to 1 as long as each adjacent line starts with a period. Blank lines do reset numbering to 1 when something, such as a figure or a supporting paragraph, comes between two lines that start with a period. To keep numbering continuous in those cases—for example, if you’re documenting steps in a procedure—put a + symbol in the otherwise blank line. A + used in this way is called a list continuation. For details on continuous numbering in an ordered list, see Ordered Lists.

A list item may contain any type of AsciiDoc content, including paragraphs, delimited blocks, and block macros. You just need to attach that content to the list item by using a list continuation.

List continuation

To add paragraphs or other block elements to a list item, you must “attach” them (in a series) using a list continuation. A list continuation is a + symbol on a line by itself, immediately adjacent to the block being attached.

A + at the end of a line is not a list continuation. In that case, the + simply creates a line break.

Example list continuation:

* The header in AsciiDoc must start with a document title.
+
The header is optional.
  • The header in AsciiDoc must start with a document title.

    The header is optional.

Using the list continuation, you can attach any number of block elements to a list item. Each block must be preceded by a list continuation to form a chain of blocks.

Here’s an example that attaches both a listing block and an admonition paragraph to the first item:

* The header in AsciiDoc must start with a document title.
+
----
= Document Title
----
+
Keep in mind that the header is optional.

* Optional Author and Revision information immediately follows the header title.
+
----
= Document Title
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2022-01-01
----

Here’s how the source is rendered:

A list with complex content
  • The header in AsciiDoc must start with a document title.

    = Document Title

    Keep in mind that the header is optional.

  • Optional Author and Revision information immediately follows the header title.

    = Document Title
    Doc Writer <doc.writer@asciidoc.org>
    v1.0, 2022-01-01

If you’re attaching more than one block to a list item, you’re strongly encouraged to wrap the content inside an open block. That way, you only need a single list continuation line to attach the open block to the list item. Within the open block, you write like you normally would, no longer having to worry about adding list continuations between the blocks to keep them attached to the list item.

Here’s an example of wrapping complex list content in an open block:

* The header in AsciiDoc must start with a document title.
+
--
Here's an example of a document title:

----
= Document Title
----

NOTE: The header is optional.
--

Here’s how that content is rendered:

A list with complex content wrapped in an open block
  • The header in AsciiDoc must start with a document title.

    Here’s an example of a document title:

    = Document Title
    The header is optional.

The open block wrapper is also useful if you’re including content from a shared file into a list item. For example:

* list item
+
--
include::shared-content.adoc[]
--

By wrapping the include directive in an open block, the content can be used unmodified.

The only limitation of this technique is that the content itself may not contain an open block (since open blocks cannot be nested).

Dropping the principal text

If the principal text of a list item is blank, the node for the principal text is dropped. This is how you can get the first block (such as a listing block) to line up with the list marker. You can make the principal text blank by using the {blank} attribute reference.

Here’s an example of a list that has items with only complex content.

. {blank}
+
----
print("one")
----
. {blank}
+
----
print("one")
----

Here’s how the source is rendered:

A list with complex content
  1. print("one")
  2. print("one")

Attaching to an ancestor list

Instead of attaching a block to the current list item, you may need to end that list and attach a block to its ancestor instead. There are two ways to express this composition in the AsciiDoc syntax. You can either enclose the child list in an open block, or you can use insert empty lines above the list continuation to first escape from the nesting. Let’s look at enclosing the child list in an open block first, since that is the preferred method.

Enclose in open block

If you plan to attach blocks to a list item as a sibling of a nested list, the most robust way of creating that structure is to enclose the nested list in an open block. That way, it’s clear where the nested list ends and the current list item continues.

Here’s an example of a list item with a nested list followed by an attached paragraph. The open block makes the boundaries of the nested list clear.

* grandparent list item
+
--
** parent list item
*** child list item
--
+
paragraph attached to grandparent list item

Here’s how the source is rendered:

A nested list enclosed in an open block
  • grandparent list item

    • parent list item

      • child list item

    paragraph attached to grandparent list item

The main limitation of this approach is that it can only be used once in the hierarchy (i.e., it can only enclose a single nested list). That’s because the open block itself cannot be nested. If you require more control, then you must use the ancestor list continuation.

Ancestor list continuation

Normally, a list continuation will attach a block to the current list item. For each empty line you add before the list continuation, the association will move up one level in the nesting. In other words, an empty line signals to the list continuation to back out of the current list by one level. As a result, the block will be attached to the current item in an ancestor list. This syntax is referred to as an ancestor list continuation.

The ancestor list continuation is a fragile syntax. For one, it may not be apparent to new authors that the empty lines before the list continuation are significant. That’s because the AsciiDoc syntax generally ignores repeating empty lines. There are also scenarios where even these empty lines are collapsed, thus preventing the ancestor list continuation from working as expected. Use this feature of the syntax with caution. If possible, enclose the nested list in an open block, as described in the previous section.

Here’s an example of a paragraph that’s attached to the parent list item after the nested list ends. The empty line above the list continuation indicates that the block should be attached to current list item in the parent list.

* parent list item
** child list item

+
paragraph attached to parent list item

Here’s how the source is rendered:

A block attached to the parent list item
  • parent list item

    • child list item

    paragraph attached to parent list item

Each empty line that precedes the list continuation signals a move up one level of nesting. Here’s an example that shows how to attach a paragraph to a grandparent list item using two leading empty lines:

* grandparent list item
** parent list item
*** child list item


+
paragraph attached to grandparent list item

Here’s how the source is rendered:

A block attached to the grandparent list item
  • grandparent list item

    • parent list item

      • child list item

    paragraph attached to grandparent list item

Summary

You learned on this page that you can attach any type of block content to a list item using the list continuation. You also learned that using this feature in combination with the open block makes it easier to create list items with complex content, or to attach blocks to a parent list. Finally, you learned that you can use the ancestor list continution to attach blocks to the current item in an ancestor list.