To group multiple terms and descriptions, place one or more dt elements before one or more dd elements inside a dl. This guide shows how to choose the right grouping, create a small glossary in TextEdit on a Mac, and check that its relationships remain clear.

How does an HTML description list group terms?

A description list represents associations between names and values. Each group contains at least one term and at least one description, with all terms appearing before the descriptions. The next term after a description begins another group. These relationships come from document order. HTML Standard: The dl element

For a glossary, a term might be a layout word and its description might explain that word. Multiple consecutive terms can share a description. You do not need to repeat the same explanation after every alternate name. MDN: Description term element

The practical question is what belongs together. Before writing markup, write down each intended association in ordinary language. For this synthetic example, “Gap” and “Gutter” share one explanation, while “Tile” has two alternative meanings.

Intended relationship Structure within one group
One term with one description One dt, then one dd
Several terms sharing one description All the dt elements, then one dd
One term with alternative descriptions One dt, then several dd elements
Several terms sharing alternative descriptions All the dt elements, then all the dd elements
One description containing several paragraphs One dd containing the paragraphs

These patterns follow the standard’s grouping rules. In particular, separate descriptions represent alternative values; paragraphs that belong to one value stay inside the same dd. HTML Standard: Description-list semantics

Which descriptions should share a group?

Use this decision test: can every description in the proposed group reasonably apply to every term in that group? If the answer is no, divide the content into separate groups. This is an editorial check derived from the association model, and it helps catch accidental pairings before they reach the page.

Several terms with one shared description

This fragment gives two synthetic glossary terms one shared explanation. Both terms appear before the description, matching MDN’s documented multiple-term pattern. MDN: Multiple terms, single description

<dl>
  <dt>Gap</dt>
  <dt>Gutter</dt>
  <dd>The space between adjacent columns.</dd>
</dl>

Do not read this as two separate entries whose descriptions happen to be missing. The example deliberately treats the two names as one group. If your own glossary assigns them different meanings, give each name its own description instead.

One term with alternative descriptions

A description can follow another description within the same group. Here, the invented glossary uses “Tile” for two different concepts. MDN: Description details element

<dl>
  <dt>Tile</dt>
  <dd>A repeating unit in a visual pattern.</dd>
  <dd>A rectangular content block in a page layout.</dd>
</dl>

For several names sharing those same alternatives, place the additional terms before the first description. Avoid assuming that the first term pairs only with the first description and the second term only with the second: that would require separate groups. MDN explicitly documents combining multiple terms and descriptions. MDN: Multiple terms and descriptions

One description with several paragraphs

If the second paragraph expands the first explanation, keep both inside one dd. A dd accepts flow content, including paragraphs. This preserves a single description while allowing a readable internal structure. MDN: Description details technical summary

<dl>
  <dt>Canvas</dt>
  <dd>
    <p>The working area for a composition.</p>
    <p>In this glossary, the term refers to the whole area.</p>
  </dd>
</dl>

Create a complete example in TextEdit on your Mac

Start with a new file so you can examine the result without changing an existing document. In TextEdit, choose File > New, then Format > Make Plain Text. Apple documents this as the starting point for authoring an HTML file. Apple: Work with HTML documents in TextEdit on Mac

Paste the complete document below. It combines the three decisions above into one small glossary. Each group has its own div wrapper, a supported structure for applying styling or attributes to an entire group. MDN: Wrapping name-value groups

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Layout glossary</title>
</head>
<body>
  <h1>Layout glossary</h1>
  <dl>
    <div>
      <dt>Gap</dt>
      <dt>Gutter</dt>
      <dd>The space between adjacent columns.</dd>
    </div>
    <div>
      <dt>Tile</dt>
      <dd>A repeating unit in a visual pattern.</dd>
      <dd>A rectangular content block in a page layout.</dd>
    </div>
    <div>
      <dt>Canvas</dt>
      <dd>
        <p>The working area for a composition.</p>
        <p>In this glossary, the term refers to the whole area.</p>
      </dd>
    </div>
  </dl>
</body>
</html>

Choose File > Save, name the file layout-glossary.html, and click Save. If TextEdit asks which extension to use, choose Use .html. These are Apple’s documented saving steps for a hand-written HTML file. Apple: Create an HTML file

Open the saved file in your browser. Compare its displayed text against three expected associations: “Gap” and “Gutter” share one explanation; “Tile” has two descriptions; “Canvas” has one description containing two paragraphs. Use this comparison to check your intended content relationships, even if the browser’s default spacing looks different from your preferred design.

Keep the grouping intact when editing

HTML supports either direct term-description groups inside dl, or groups wrapped in div elements. Choose one structure throughout a particular list. In the wrapped version above, keep each group’s terms and descriptions directly inside its wrapper; do not wrap the terms and descriptions in separate containers. HTML Standard: Description-list content model

When you revise the example, use this short check:

  1. Find the group you intend to change.
  2. Keep its complete set of terms before its descriptions.
  3. Decide whether new explanatory text is another value or another paragraph of the current value.
  4. Add a new complete group when introducing an unrelated term.
  5. Save the document and reload the browser preview.

For example, adding “Panel” between the two “Tile” descriptions would interrupt the intended relationship: the following description would belong to the newly started group. Put a new term and its description in their own wrapper instead. This follows the standard’s rule that a term encountered after a description starts another group. HTML Standard: Grouping algorithm

If TextEdit reopens the file as formatted text, use File > Open, select the document, click Show Options, and select Ignore rich text commands before opening it. For future files, select Display HTML files as HTML code instead of formatted text under TextEdit > Settings > Open and Save. Apple: View an HTML document as code

Keep the final review focused on meaning: identify the terms, identify their shared descriptions, and confirm that paragraph breaks do not accidentally become separate values. Once those associations are correct, the glossary is ready for whatever presentation styling your document needs.

Sources