Description Lists

A description list (often abbreviated as dlist in AsciiDoc) is an association list that consists of one or more terms (or sets of terms) that each have a description. This list type is useful when you have a list of terms that you want to emphasize and describe with text or other supporting content.

You may know this list variation by the antiquated term definition list. The preferred term is now description list, which matches the terminology used by the HTML specification.

Anatomy

A description list item marks the beginning of a description list. Each item in a description list consists of:

one or more terms, each followed by a term delimiter (typically a double colon, ::, unless the list is nested)
one space or newline character
the description in the form of text, attached blocks, or both

If a term has an anchor, the anchor must be defined at the start of the same line as the term.

The first term defines which term delimiter is used for the description list. The terms for the remaining entries at that level must use the same delimiter.

The valid set of term delimiters is fixed. When the term delimiter is changed, that term begins a new, nested description list (similar to how ordered and unordered lists work). The available term delimiters you can use for this purpose are as follows:

::
:::
::::
;;

There’s no direct correlation between the number of characters in the delimiter and the nesting level. Each time you change delimiters (selected from this set), it introduces a new level of nesting. This is how list depth is implied in a language with a left-aligned syntax. It’s customary to use the delimiters in the order shown above to provide a hint that the list is nested at a certain level.

Basic description list

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.

Mixing lists

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

Nested description list

Finally, you can mix and match the three list types within a single hybrid list. The AsciiDoc syntax tries 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 lists. Notice how the term delimiter is changed from :: to ::: to create a nested description list.

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.