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