Complex Lists

Indented lines

Aside from nested lists, all of the list items you’ve seen only have one line of text. But like 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. The wrapped lines can be indented and they will still be treated as normal paragraph text. For 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 items contain more than one line of text, leave a blank line before the next item to make the list easier to read.

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

List continuation

To add additional 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.

Here’s an example:

* 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, 2013-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, 2013-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

You may find that you need to attach block content to a parent list item instead of the current one. In other words, you want to attach the block content to the parent list item so it becomes a sibling of the child list. To do this, you add a blank line before the list continuation. The blank line signals to the list continuation to move out of the current list so it attaches the block to the last item of the parent list.

Here’s an example of a paragraph that’s attached to the parent list item, placing it adjacent to the child list (instead of inside of it).

* 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 blank 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 blank 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

Using blank lines to back out of the nesting may feel fragile. A more robust way to accomplish the same thing is to enclose the nested lists in an open block. That way, it’s clear where the nested list ends and the enclosing list continues.

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

Here’s how the source is rendered:

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

    • parent list item

      • child list item

    paragraph attached to grandparent list item

As you’ve learned in this section, the primary text of a list item can wrap to any number of adjacent lines. You can also attach any type of content to a list item using the list continuation. Combining those features with the open block makes it even easier to create lists with complex content.