A glossary with hanging indents that stays scannable

Why this block is harder than it looks

A glossary is read by looking for one term, not by reading through, so everything about the layout has to serve scanning. That means the terms have to form an unbroken column at the left edge, which a normal paragraph layout destroys the moment a definition runs to two lines and the next term starts under the middle of the previous definition. The other question is where a definition splits across a page, because a definition whose second half opens a page with no term above it is unattributable.

The decisions that make it work

Reasons rather than a description of the code. Each of these is a choice that has a wrong answer, and the wrong answer is usually the default.

• Use a hanging indent so the term sits at the left edge and the definition is indented, rather than a definition list that puts them on separate lines.
• Keep the term column width fixed and let a long term wrap within it rather than pushing the definition across, so the left column stays a column.
• Set the term in a different weight, not a different size. A size change breaks the baseline grid across the two columns.
• Give each entry break-inside: avoid where the definitions are short, and where they are long, repeat the term with a continuation marker at the top of the next page.
• Sort alphabetically and say so, because a glossary that is in document order rather than alphabetical order is a different tool and readers assume the wrong one.
• Cross-reference other defined terms by setting them in the same weight as the term column, so a reader knows a word is defined elsewhere without a see-also line.

The fragment

Markup and the CSS it needs, and nothing else. It expects a document that already has a page rule and a base stylesheet, so paste it into one rather than opening it on its own.

<dl class="glossary">
  <div class="entry">
    <dt>Actual delivery date</dt>
    <dd>The date on which goods or services were supplied, which may differ from
      the invoice issue date and from the date of the order.</dd>
  </div>
  <div class="entry">
    <dt>Allowance</dt>
    <dd>A reduction applied to an amount, at either document or line level.
      See also <b>charge</b>.</dd>
  </div>
</dl>

<style>
  .glossary { margin: 0; font-size: 9pt; }
  .glossary .entry {
    display: grid;
    grid-template-columns: 42mm 1fr;      /* fixed term column */
    gap: 6mm;
    break-inside: avoid;
    margin-bottom: 5pt;
    align-items: start;
  }
  .glossary dt { font-weight: 700; }
  .glossary dd { margin: 0; line-height: 1.45; }
  .glossary b { font-weight: 700; }       /* a cross-reference reads as a term */
</style>

What breaks when it is built the obvious way

Setting it as a run-in list where the term is bold at the start of the paragraph. Every term then starts at a different horizontal position depending on where the previous definition ended, so scanning for a term means reading the whole page.

How to prove it survived pagination

Render forty entries and try to find one in the middle by scanning the left edge only. If your eye has to enter the definitions to track the terms, the hanging indent is not holding. Then confirm no definition opens a page with no term above it.

Where it sits in a finished document

This page is one block. The document it belongs to has a page rule, a base stylesheet, a header and everything else around it, and repeating all of that here would make thirty pages that say the same thing. The multi-page report template is a complete file with this block already in it, so take that and change the fragment rather than assembling one from parts. The property doing most of the work here is covered on its own page, with the support caveats that belong there rather than here.

Frequently asked

Other parts of a document

The blocks that sit next to this one, and one from the next group along so you are not sealed inside a single kind of problem.