List Continuation

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:

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.

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:

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:

Here’s how the source is rendered:

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:

Here’s how that content is rendered:

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

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

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.

Here’s how the source is rendered:

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

Here’s how the source is rendered:

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:

Here’s how the source is rendered:

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.

Here’s how the source is rendered:

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.