The PreTeXt Guide

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 marker. 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.