You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

85 lines
2.1 KiB

4 years ago
////
Included in:
- user-manual: Description lists
- writers-guide: description lists
- writers-guide: hybrid lists
////
// tag::description[]
A description list (often abbreviate as dlist) is useful when you need to include a description or supporting text for one or more terms.
Each item in a description list consists of:
* one or more terms
* a separator following each term (typically a double colon, `::`)
* at least one space or endline
* the supporting content (either text, attached blocks, or both)
Here's an example of a description list that identifies parts of a computer:
[source]
----
include::ex-dlist.adoc[tag=base]
----
By default, the content of each item is displayed below the description when rendered.
Here's a preview of how this list is rendered:
.A basic description list
====
include::ex-dlist.adoc[tag=base]
====
If you want the description and content to appear on the same line, add the horizontal style to the list.
[source]
----
include::ex-dlist.adoc[tag=base-horz]
----
====
include::ex-dlist.adoc[tag=base-horz]
====
The content of a description list can be any AsciiDoc element.
For instance, we could rewrite the grocery list from above so that each aisle is a description rather than a parent outline list item.
[source]
----
include::ex-dlist.adoc[tag=base-mix]
----
====
include::ex-dlist.adoc[tag=base-mix]
====
Description lists are quite lenient about whitespace, so you can spread the items out and even indent the content if that makes it more readable for you:
[source]
----
include::ex-dlist.adoc[tag=base-mix-alt]
----
// end::description[]
// tag::hybrid[]
[#three-hybrid]
Finally, you can mix and match the three list types within a single hybrid list.
Asciidoctor works hard to infer the relationships between the items that are most intuitive to us humans.
Here's a list that mixes description, ordered, and unordered list items:
[source]
----
include::ex-dlist.adoc[tag=3-mix]
----
Here's how the list is rendered:
.A hybrid list
====
include::ex-dlist.adoc[tag=3-mix]
====
You can include more complex content in a list item as well.
// end::hybrid[]