Lists, Steps, Terms, and Trees

Learn by Example

This page was written in a Mallard extension format called Mallard Sites. Read the source markup for this page to learn Mallard from real-world examples.

Lists are a staple of technical documentation. Readers can more easily scan a page for what they need when information is presented in lists. Mallard provides various list elements that help you present information concisely. In this tutorial, you will learn how to create a basic list, a list of steps, a list of terms, and a simple tree.

Basic Lists

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>
  • Lima beans

  • Jelly beans

  • Magic beans

Notice that each item element contains a paragraph, marked up with the p tag. A list item can contain multiple paragraphs or other block elements. In Mallard, every element contains either block or inline content, so even when you only use a single line of text in a list item, you must use a paragraph.

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>
  1. Lima beans

  2. Jelly beans

  3. Magic beans

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>
  1. Lima beans

  2. Jelly beans

  3. Magic beans

When Mallard is converted to HTML, list style support may depend on the CSS support in your web browser.

Step Lists

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>
  1. Dig a hole 5cm deep.

  2. Place your magic beans in the hole.

  3. Fill the hole with clean dirt and pat it level.

  4. Water daily.

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.

Term Lists

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>
Lima beans

These are actually beans.

Jelly beans

These aren't really beans, but they sure are yummy.

Magic beans

You can plant these to grow a giant beanstalk.

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>
Fava beans
Lima beans

These are actually beans.

Jelly beans

These aren't really beans, but they sure are yummy.

Magic beans

You can plant these to grow a giant beanstalk.

Trees

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>
  • home
    • Drake
      • Documents
    • Wanda
    • Wilbur
      • Pictures

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>
  • home
    • Drake
      • Documents
    • Wanda
    • Wilbur
      • Pictures

Learn More

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.