Lists, Steps, Terms, and Trees

You can create a basic bulleted list using the list element. Each list item is contained in an item element.

<list>
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>

A bulleted list is the default list type in Mallard. You can specify other list types with the type attribute on the list element. To create a numbered list, use the value "numbered".

<list type="numbered">
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>

When you use the "numbered" type, processing tools will pick an appropriate numbering system based on the language the page is written in. You can also specify exactly which numbering system to use, or specify an alternate type of glyph for bulleted lists. The type attribute accepts any CSS3 list style.

<list type="lower-greek">
  <item><p>Lima beans</p></item>
  <item><p>Jelly beans</p></item>
  <item><p>Magic beans</p></item>
</list>

One of the most common uses for numbered lists in documentation is to provide a list of instructions for a user to follow. Although you can use the list element to create a numbered list, Mallard provides the steps element to list steps in a procedure.

<steps>
  <item><p>Dig a hole 5cm deep.</p></item>
  <item><p>Place your magic beans in the hole.</p></item>
  <item><p>Fill the hole with clean dirt and pat it level.</p></item>
  <item><p>Water daily.</p></item>
</steps>

Like the list element, the steps element takes any number of item elements, and each item element must contain a paragraph or other block content. Step lists will be formatted so that users can easily find them when looking through a page.

You can use the terms element to create a list of terms and descriptions in Mallard. Use term lists to create glossaries or to describe a list of configuration options.

<terms>
  <item>
    <title>Lima beans</title>
    <p>These are actually beans.</p>
  </item>
  <item>
    <title>Jelly beans</title>
    <p>These aren't really beans, but they sure are yummy.</p>
  </item>
  <item>
    <title>Magic beans</title>
    <p>You can plant these to grow a giant beanstalk.</p>
  </item>
</terms>

Notice that each item element in a term list has a title element to mark up the actual term. The description follows in a paragraph, or in any number of other block elements. You can also provide multiple terms for an item by using multiple title elements.

<terms>
  <item>
    <title>Fava beans</title>
    <title>Lima beans</title>
    <p>These are actually beans.</p>
  </item>
  <item>
    <title>Jelly beans</title>
    <p>These aren't really beans, but they sure are yummy.</p>
  </item>
  <item>
    <title>Magic beans</title>
    <p>You can plant these to grow a giant beanstalk.</p>
  </item>
</terms>

Sometimes you need to show a hierarchy of items in documentation. This is useful, for example, to show a directory structure on a file system or a class hierarchy in an object-oriented programming language. Mallard provides the tree element to help you create simple trees easily.

Use a tree to show some directories on a file system.

<tree>
  <item>home
    <item>Drake
      <item>Documents</item>
    </item>
    <item>Wanda</item>
    <item>Wilbur
      <item>Pictures</item>
    </item>
  </item>
</tree>

The item element works differently in trees than in the other types of lists. A tree item starts out with inline content, rather than block content. It can then contain other tree items that contain the child items.

The initial content doesn't have to be just text. You can use any inline markup before the child items. For example, you can use the file element to indicate that the items are file names.

<tree>
  <item><file>home</file>
    <item><file>Drake</file>
      <item><file>Documents</file></item>
    </item>
    <item><file>Wanda</file></item>
    <item><file>Wilbur</file>
      <item><file>Pictures</file></item>
    </item>
  </item>
</tree>

In this tutorial, you learned how to create four different types of lists in Mallard. You can do much more with lists in Mallard, such as add titles, create nested lists, and use richer block content. For more information, see List Elements in the language specification. The specification pages are full of examples to help you learn more.