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
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[]
|