Description Lists

A description list (often abbreviated as dlist) is useful when you need to include a description, definition, or supporting text for one or more terms. Each item in a description list consists of a term or phrase followed by:

one or more terms
a separator following each term (typically a double colon, ::)
at least one space or endline
the supporting content (i.e., description) (can be text, attached blocks, or both)

Here’s an example of a description list that identifies parts of a computer:

CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
Keyboard:: Used to enter text or control items on the screen.
Mouse:: Used to point to and select items on your computer screen.
Monitor:: Displays information in visual form using text and graphics.

By default, the content of each item is displayed below the label when rendered. Here’s a preview of how this list is rendered:

A basic description list

CPU: The brain of the computer.
Hard drive: Permanent storage for operating system and/or user files.
RAM: Temporarily stores information the CPU uses during operation.
Keyboard: Used to enter text or control items on the screen.
Mouse: Used to point to and select items on your computer screen.
Monitor: Displays information in visual form using text and graphics.

If you want the label and content to appear on the same line, add the horizontal style to the list.

[horizontal]
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.

CPU	The brain of the computer.
Hard drive	Permanent storage for operating system and/or user files.
RAM	Temporarily stores information the CPU uses during operation.

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 label rather than a parent outline list item.

Dairy::
* Milk
* Eggs
Bakery::
* Bread
Produce::
* Bananas

Dairy

Milk
Eggs

Bakery

Bread

Produce

Bananas

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:

Dairy::

  * Milk
  * Eggs

Bakery::

  * Bread

Produce::

  * Bananas

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:

Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace

Here’s how the list is rendered:

A hybrid list

Operating Systems

Linux

Fedora
- Desktop
Ubuntu
- Desktop
- Server

BSD

FreeBSD
NetBSD

Cloud Providers

PaaS

OpenShift
CloudBees

IaaS

Amazon EC2
Rackspace

You can include more complex content in a list item as well.