Lists

Inline markup structured the inside of the paragraph. Some content, though, is not a paragraph: ordered steps, items of equal standing, term–description pairs. Writing these as paragraphs destroys structural information — the reader cannot tell how many items there are, whether their order is meaningful, or where they end.

There are three list kinds, and the choice is made according to the content’s nature.

Three Kinds

Unordered list (ul) is a list whose items’ order carries no meaning. If items swap places, the document’s meaning does not change.

Ordered list (ol) is a list where order carries meaning: steps, ranking, priority. Swapping places breaks the meaning.

Definition list (dl) is made of name–value pairs: a term and its description, a field and its content, a question and its answer.

The choice criterion is not appearance. Removing an unordered list’s markers or hiding an ordered list’s numbers is the presentation layer’s job; which element is chosen is decided by whether order is meaningful.

The Item Element and Its Container

The li element is a list item and can only be the direct child of a list element. An li element written directly into the body is invalid.

The li element’s closing tag may go unwritten; as seen in the Document Object Model lesson, the previous one closes on its own when a new li is opened. Writing it is still preferred.

Writing text as a direct child of a list element is invalid: the children of ul and ol elements can only be li. Whitespace and line breaks between them are ignored, but real text is moved by the parser to outside the list.

<ul>
  <li>Temperature</li>
  <li>Relative humidity</li>
  <li>Wind speed</li>
  <li>Precipitation</li>
</ul>

The Numbering Rule

An ordered list’s numbers start from one and increase by one by default. Three attributes change this behavior: start decides the starting value, reversed a decreasing order, value a single item’s value. Once value is written, the following items continue from there.

// lists.mjs — ordered list numbering rule
function number(list) {
  const n = list.items.length;
  const start = list.start ?? (list.reversed ? n : 1);
  const result = [];
  let counter = start;
  for (const item of list.items) {
    const value = item.value ?? counter;
    result.push([value, item.text]);
    counter = value + (list.reversed ? -1 : 1);
  }
  return result;
}

const lists = [
  { name: "default", items: [{ text: "housing opens" }, { text: "sensor is read" }, { text: "record is written" }] },
  { name: "start=5", start: 5, items: [{ text: "housing opens" }, { text: "sensor is read" }] },
  { name: "reversed", reversed: true, items: [{ text: "housing opens" }, { text: "sensor is read" }, { text: "record is written" }] },
  { name: "skip with value", items: [{ text: "housing opens" }, { text: "sensor is read", value: 7 }, { text: "record is written" }] },
];

for (const list of lists) {
  console.log("[" + list.name + "]");
  for (const [num, text] of number(list)) console.log("  " + num + ". " + text);
}

[default]
  1. housing opens
  2. sensor is read
  3. record is written
[start=5]
  5. housing opens
  6. sensor is read
[reversed]
  3. housing opens
  2. sensor is read
  1. record is written
[skip with value]
  1. housing opens
  7. sensor is read
  8. record is written

In the reversed case, note that the starting value comes from the item count: if the list has three items, it starts from three. If start is written, that value applies instead.

These values are not just appearance; they are data the document carries. Writing start="8" on a procedure’s second page is different from writing the numbers by hand in the presentation layer: it is declared in the document that this is the eighth step.

The numbers’ form — digit, letter, roman numeral — is a presentation decision and is decided in the presentation layer.

Definition Lists

The dl element carries name–value pairs. dt marks the name, dd the value. The relationship between the two comes from adjacency: dd elements following a dt element belong to it.

<dl>
  <dt>Installation elevation</dt>
  <dd>1840 m</dd>

  <dt>Measurement interval</dt>
  <dd>10 minutes</dd>

  <dt>Temperature</dt>
  <dt>Relative humidity</dt>
  <dd>Measured in the same sensor housing.</dd>
</dl>

The last group shows that more than one name can share a single description. The reverse holds too: a name can be given more than one dd element.

If a pair needs to be grouped as a single unit, the dt and dd elements can be wrapped in a div; this is the only extra element allowed as a direct child of dl.

A definition list is used beyond what its name suggests: an identification block, a metadata table, a question–answer set are also name–value structures. The criterion is not being a dictionary, it is that every item has a name and a value bound to it.

Nested Lists

A sublist is written inside the parent list’s item — not between items.

<ul>
  <li>Temperature
    <ul>
      <li>Housing temperature</li>
      <li>Soil temperature</li>
    </ul>
  </li>
  <li>Relative humidity</li>
</ul>

Writing the sublist between li elements, as a direct child of the ul element, breaks the structure: the sublist does not declare which item it belongs to. The flaw is easy to miss because the appearance stays similar in most cases; on a screen reader, though, the nesting is announced incorrectly.

Writing closing tags is especially important in nested writing. If the outer item’s closing is not written, the implicit-closing rule fires not at the sublist’s end but at the next li opening; the result is usually what was expected, but the source text becomes misleading.

The Information a List Announces

A list element’s value is not in its markers, it is in the count it carries. Screen readers announce the item count and which item number is currently on when entering a list. Writing the same content as consecutive paragraphs destroys this information: the user only learns how many items there are once they reach the end.

This criterion also decides when a list should not be used. A single-item list carries no count information and is unnecessary if it was only written for indentation. A structure where every line is its own list is misleading the same way: the count drops to one every time.

Two-dimensional data is not a list either. If every item has more than one field — like each measurement’s time, value, and unit — the structure is a table and is written with the table elements covered in this topic’s last lesson. The criterion that turns a list into a table is whether items are split into comparable fields.

In the Station Document

The measurement station page has two lists, and their kinds differ:

<h2>Measured Quantities</h2>
<ul>
  <li>Temperature</li>
  <li>Relative humidity</li>
  <li>Wind speed</li>
  <li>Precipitation</li>
</ul>

<h2>Calibration Procedure</h2>
<ol>
  <li>The housing cover is opened.</li>
  <li>A reading is taken without disconnecting the sensor.</li>
  <li>It is compared against the reference value.</li>
  <li>The deviation is recorded and the housing is closed.</li>
</ol>

The order of the measured quantities carries no meaning; the calibration steps’ order does. The distinction is given not by the two elements’ appearance, but by the nature of the content.

Summary

• An unordered list is where order is meaningless, an ordered list where it is meaningful; a definition list carries name–value pairs.
• The li element can only be the direct child of a list element; text cannot be written as the direct child of a list element.
• In an ordered list, start, reversed, and value decide numbering; once value is written, the following items continue from there.
• In a definition list, more than one value can be bound to a name, more than one name to a value; the relationship comes from adjacency.
• A sublist is written inside the item it belongs to; writing it between items breaks the nesting information.

Next Step

Lists grouped content, but the document is still closed in on itself: there is no way to move to another document. The next lesson takes up links and shows how a relative address is resolved — against which base, with which rule — through real resolution output.