Skip to main content

Section 4.11 Lists

A list is an unusual construction, even if everybody knows exactly what one is. We view the list itself as a container of various chunks of text, while those chunks of text are the list items. Each item has a label to identify it (which is quite different from how uses the term “label”).

Markup and processing is complicated by the possibility of a list item containing a list, resulting in nested lists. We simplify this problem by requiring that a list appear within a paragraph (<p>), see Subsection 4.1.3. One of the three exceptions is the possibility to place a list into a block that earns a caption and a number, using the <list> element, see Subsection 4.11.6.

The final subsection contains some examples that you may wish to consult as you read this section.

Subsection 4.11.1 Ordered, Unordered, Description Lists

An ordered list has items with labels that are naturally ordered (usually numerically or alphabetically). We borrow from HTML, and use the <ol> tag to construct an ordered list. Some commentators suggest an ordered list should only be used when the order of the content is important. So the steps in a recipe would belong in an ordered list, but the shopping list when you go to the store need not be an ordered list.

An unordered list has items with labels that have no inherent order and so are usually symbols like circles, disks, squares, etc. We borrow from HTML, and use the <ul> tag to construct an unordered list.

A description list has items that have short pieces of text as their labels. We borrow from HTML, and use the <dl> tag to construct a description list.

Ordered lists are used as part of <objectives> ([provisional cross-reference: topic-objectives]) and exercises (Section 4.12). Any of the three lists may occur inside the <list> element (below, Subsection 4.11.6). Otherwise, a list must occur within a paragraph, <p>. This means that to place a list within a list item of another list, the list item must contain a paragraph.

Subsection 4.11.2 List Labels

Do nothing, and your ordered and unordered lists will get sensible default labels. They are consistent in the following sense. If your list has two items, and each of the two items contains a list, then these two lists will use the same type of label.

For a description list, you author each label as part of each list item, as discussed below in the discussion of list items.

If you want to change how an ordered list is labeled, then you use the @label attribute on the <ol>, whose value is a format code. This string contains one of five codes (a single character), which may be surrounded by other characters, excluding the five codes. For example label="(A)" will produce uppercase letters wrapped in parentheses: (A), (B), (C), …. The extra formatting works well in a conversion to , but is not possible technically in a conversion to HTML, so it should be considered decorative, and not relied upon for meaning. The formatting does not carry through to the numbers of list items in cross-references.

If you want to change how an unordered list is labeled, then you use the @label attribute on the <ul>, whose value is a format code. This string contains one of three codes in the table below. Then every item of the list will have that symbol as its label.

Table 4.11.1. Ordered List Labels
Code Realization
1 Arabic numerals
a Lowercase letters
i Lowercase Roman numerals
A Uppercase letters
I Uppercase Roman numerals
0 Arabic numerals, from zero
Table 4.11.2. Unordered List Labels
Code Realization
disc Filled small circle, aka a bullet
circle Small circle
square A square

Default label types are assigned to each level of nested lists in the order shown in the table, and cycle back to the top of the table if necessary, though zero-based Arabic numerals will be skipped for ordered lists.

Start with the defaults, and experiment as needed. See the examples below for some extreme (and unwise) customizations of labels.

For a description list, possible labels are more varied than what you can express with an XML attribute. So the list item must have a <title> element (see below). This should be very short text, and may contain inline mathematics. It is often rendered in bold, so be aware that some markup may get lost. Perhaps for obvious reasons, do not include footnotes, cross-references, or display mathematics. The <dl> element has a @width attribute, with possible values narrow, medium, and wide. The default is narrow. This is a hint about how much text you have in these labels, and in certain presentations may make better use of horizontal space on a page.

Subsection 4.11.3 List Items

So now you have a list all organized as a container. What do you put in it? List items, using the <li> tag, again borrowed from HTML, and independent of the type of list.

A list item could be really simple, maybe just one or two words. Then you can use, and conceptualize, an <li> element as not much different from a <p> element, and the rules about content are not much different. Even several full sentences, with some intermediate displayed mathematics, is fine.

But once you want two paragraphs in a list item, then you need to structure the contents of the item. So a list item might have five paragraphs in it, requiring five <p> elements. Notice that this is how you nest lists. Make a list item, include a paragraph, then put the subsidiary list into the paragraph. Indeed, this is the only way to nest lists. A consequence of this is that the only way to have an unstructured list item is if it is a terminal item, like the leaf of a tree.

Other items may be interspersed among the paragraphs of a list item, such as a chunk of verbatim text delimited by a <pre> tag. But anything with a number, such as a <figure> or <remark> is banned, in part because the consequences for numbering and organization become too complicated. Imagine a remark, and a paragraph of the remark has a list. Fine so far. But if the items of that list can again contain remarks, the possibilities become endless. You should be able to include non-textual items, like an <image>, and work is underway to improve this. You can use a <sidebyside> in a structured list item, which can in turn hold an <image>, <tabular>, or similar. But you cannot place items in such a <sidebyside> that are numbered, so a <figure> or <table> is not possible. A general rule is no numbered components in a list item. Computational components, such as <sage> are also banned from list items due to the difficulty of converting them into electronic computational notebooks with a relatively flat structure.

A list item of a description list must have a <title> element, to provide the text of the label. Now that the list item has some structure, the remainder must also be structured, typically with some paragraphs, as discussed above. In other words, the earlier option of employing an <li> element just like a <p> element is not available in a description list. Further, given the complexity of presenting a description list, it can only be a top-level list. It can contain the two other types nested within its list items.

For ordered and unordered lists, you may optionally include a <title> when you have structured the <li>. This will be rendered as a heading of sorts for the list item, though the only distinction might be a change to an italic or oblique font. As an example, this might be a good way to author a Frequently Asked Questions (FAQ).

Note that a list item holding only an <m> element will get special treatment. See Subsection 4.9.15.

Subsection 4.11.4 Cross-References to List Content

Note that a list is a container, so it cannot be the target of a cross-reference, and so the three types of lists cannot have an @xml:id attribute. But you may well be able to point at some other structure (e.g., a <remark>) with a paragraph containing a list of interest. If this seems overly restrictive, read below about named lists.

By contrast, a list item, <li>, is not a container, and does contain content. Further, a list item of an ordered list has a label that is natural text for a cross-reference. So in this situation, the list item can have an @xml:id attribute. But note that the “number” of a list item of an ordered list, which is nested inside a list item of an unordered list, is not defined, so a cross-reference by number can fail.

The “number” of a list item, mostly for the purposes of a cross-reference, is the concatenation of all of the individual labels in the containing lists, outermost first. For example, from the example lists below, the list item with content “Walleye” has number 2.I. These are indivisible, there is no way to get a component, excepting leading subsequences obtained by using an @xml:id on a containing list item. Note that the format codes never become part of the number.

Subsection 4.11.5 Lists in Columns

You can control the number of columns used to layout an ordered or unordered list (but not a description list). On the <ol> or <ul> use a @cols attribute with values 2 through 6. (1 is the default.)

We do not yet (2018-03-28) have enough technical confidence to allow an author to specify a row-major order versus a column-major order for the layout. So understand that this is can be an implementation choice for a particular conversion, and can vary across implementations. If this is critical to conveying meaning, and not an aesthetic preference, then maybe consider using a <table> or <tabular> (Section 4.14).

Best Practice 4.11.3. Use Only a Few Columns for Lists.

Anything more than three columns tends to get very crowded horizontally. Think twice about using more than that, and realize that six columns should be a ridiculously generous upper limit, and not a promise of good behavior in final output.

Subsection 4.11.6 Named Lists

As mentioned above, it is not possible to have a list be the target of a cross-reference. Should an entire list be so important that you need to point to it from elsewhere, then make it a named list by wrapping it in the <list> tag.

This element can begin with an optional <introduction>, then has a single, required list, which may be any of the three types. It concludes with an optional <conclusion>. It can have an @xml:id attribute, which in a way is the whole raison d'être for this construction. It will be numbered when rendered, and so also requires a <title>. You might think of this as similar to a <table>—bits of information organized spatially.

Since this element associates a number, title, to an entire list, we call it a “named list”. What should we call a list that is authored within a paragraph and cannot be the target of a cross-reference? We call it an anonymous list when we want to make the distinction.

Subsection 4.11.7 Exceptional Lists

We use the tags for lists in a few situations outside of anonymous lists inside paragraphs and named lists. These include the items within an objectives, subparts of an exercise, and within panels of a side-by-side. See those topics to learn about subtle differences in use.

Subsection 4.11.8 Examples of Lists

To illustrate this section, we offer three too-elaborate examples. Take these as compact examples of what is possible, and not best practice in your writing. We also use these to illustrate cross-references to list items, see Subsection 4.7.6.

We have a paragraph that begins with anonymous list of species that live in water (maybe partially), which necessarily is placed inside a paragraph. The roman numerals purposely do not have any extra adornment in the version (but may for HTML output).

  1. Amphibians

    1. Frog

    2. Salamander

    3. Newt

    4. Toad

  2. Freshwater Sport Fish

    1. Walleye

    2. Bass

    3. Exquisite Fish.


  3. Saltwater Sport Fish

    1. Salmon

    2. Halibut

    3. Marlin

Within the same paragraph, we transition to an unordered, two-column, list of some germs:

  • Bacteria

    • Staphylococci

    • Streptococci

    • Salmonella

  • Viruses

    • Varicellovirus

    • Orthopoxvirus

This sentence concludes our (small) paragraph on small and large organisms.

A named list, only to test cross-references.

List 4.11.4. A two-deep ordered list
    1. A and i

    2. A and ii

    1. B and a

    2. B and b

    3. A Test Title.

      B and c

    1. C and I

    2. C and II

    3. C and III

An example of a description list, anonymously in a paragraph.


The color of the sun at sunset.


The color of a clear sky.


The color of shallow tropical waters.

\(x^2 + y^2\)

Definitely not a color

Remark 4.11.5. Best Practice.

Lists are a very attractive device. Hopefully the discussion above has convinced you that they are more complicated than they first appear. Think carefully before using one, and consider if some other structure (<paragraphs>, <sidebyside>, a subdivision) might do a better job of organizing and communicating your meaning. And if a list is really necessary, consider if it should be named or anonymous, heavily-nested or nearly-flat, with columns, or with long or short content in the items. Cross-references from the items of a list to more complicated structures is another device that works well.