unordered.adoc 3.6 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
= Unordered Lists
:keywords: bulleted list

If you were to create a list in an e-mail, how would you do it?
Chances are, you'd mark list items using the same characters that Asciidoctor uses to find list items.

== Basic unordered list

In the example below, each list item is marked using an asterisk (`+*+`), the AsciiDoc syntax specifying an unordered list item.

[source]
----
include::example$unordered.adoc[tag=base]
----

A list item's first line of text must be offset from the marker (`+*+`) by at least one space.
If you prefer, you can indent list items.
Blank lines are required before and after a list.
Additionally, blank lines are permitted, but not required, between list items.

.Rendered unordered list
====
include::example$unordered.adoc[tag=base]
====

You can add a title to a list by prefixing the title with a period (`.`).

[source]
----
include::example$unordered.adoc[tag=base-t]
----

.Rendered unordered list with a title
====
include::example$unordered.adoc[tag=base-t]
====

Was your instinct to use a hyphen (`-`) instead of an asterisk to mark list items?
Guess what?
That works too!

[source]
----
include::example$unordered.adoc[tag=base-alt]
----

You should reserve the hyphen for lists that only have a single level because the hyphen marker (`-`) doesn't work for nested lists.
Now that we've mentioned nested lists, let's go to the next section and learn how to create lists with multiple levels.

[#separating-lists]
.Separating Lists
****
If you have adjacent lists, they have the tendency to want to fuse together.
To force lists apart, insert a line comment (`//`) surrounded by blank lines between the two lists.
Here's an example, where the `-` text in the line comment indicates the line serves as an "`end of list`" marker:

[source]
----
include::example$unordered.adoc[tag=divide]
----
****

== Nested unordered list

To nest an item, just add another asterisk (`+*+`) to the marker.
Continue doing this for each subsequent level.

[source]
----
include::example$unordered.adoc[tag=nest]
----

.Rendered nested, unordered list
====
include::example$unordered.adoc[tag=nest]
====

You can nest unordered lists to any depth.
Dan Allen's avatar
Dan Allen committed
79
Keep in mind, however, that some interfaces will begin flattening lists after a certain depth.
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
For instance, GitHub starts flattening list after 10 levels of nesting.

[source]
----
include::example$unordered.adoc[tag=max]
----

====
include::example$unordered.adoc[tag=max]
====

While it would seem as though the number of asterisks represents the nesting level, that's not how depth is determined.
A new level is created for each unique marker encountered.
However, it's much more intuitive to follow the convention that the number of asterisks equals the level of nesting.
After all, we're shooting for plain text markup that is readable _as is_.

96
[#markers]
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
== Custom markers

Asciidoctor offers numerous bullet styles for lists.
The list marker (bullet) is set using the list's block style.

The unordered list marker can be set using any of the following block styles:

* square
* circle
* disc
* none or no-bullet (indented, but no bullet)
* unstyled (no indentation or bullet) (HTML only)

NOTE: These styles are supported by the default Asciidoctor stylesheet.

When present, the style name is assigned to the unordered list element as follows:

For HTML:: the style name is assigned to the `class` attribute on the `<ul>` element.

For DocBook:: the style name is assigned to the `mark` attribute on the `<itemizedlist>` element.

Here's an unordered list that has square bullets:

[source]
----
include::example$unordered.adoc[tag=square]
----

====
include::example$unordered.adoc[tag=square]
====