Description Lists

Description lists are useful when you need to include a description, definition, or supporting text for each item in a list. Each item in a description list consists of a term or phrase followed by:

  • a separator (typically a double colon, ::)

  • at least one space or endline

  • the item’s content

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
  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD
  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS
  1. OpenShift

  2. CloudBees

IaaS
  1. Amazon EC2

  2. Rackspace

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