continuation.adoc 5.2 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
= List Continuation

== 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:

[source]
----
include::example$complex.adoc[tag=indent]
----

====
include::example$complex.adoc[tag=indent]
====

TIP: 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 [.term]*list continuation* is a `{plus}` symbol on a line by itself, immediately adjacent to the block being attached.

Here's an example:

[source]
----
include::example$complex.adoc[tag=cont]
----

====
include::example$complex.adoc[tag=cont]
====

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:

[source]
....
include::example$complex.adoc[tag=complex]
....

Here's how the source is rendered:

.A list with complex content
====
include::example$complex.adoc[tag=complex]
====

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:

[source]
....
include::example$complex.adoc[tag=complex-o]
....

Here's how that content is rendered:

.A list with complex content wrapped in an open block
====
include::example$complex.adoc[tag=complex-o]
====

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

[source]
----
* 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]
== 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.

[source]
....
include::example$complex.adoc[tag=complex-only]
....

Here's how the source is rendered:

.A list with complex content
====
include::example$complex.adoc[tag=complex-only]
====

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

[source]
....
include::example$complex.adoc[tag=complex-parent]
....

Here's how the source is rendered:

.A block attached to the parent list item
====
include::example$complex.adoc[tag=complex-parent]
====

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:

[source]
....
include::example$complex.adoc[tag=complex-grandparent]
....

Here's how the source is rendered:

.A block attached to the grandparent list item
====
include::example$complex.adoc[tag=complex-grandparent]
====

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.

[source]
....
include::example$complex.adoc[tag=complex-enclosed]
....

Here's how the source is rendered:

.A nested block enclosed in an open block
====
include::example$complex.adoc[tag=complex-enclosed]
====

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.