# all·markdown

How to write a definition list in Markdown

Try it — edit the markdown and watch the preview

Result

Runs entirely in this tab. Open the full editor to work on a real document.

Definition lists are not part of Markdown. There is no <dl> in the original spec, none in CommonMark and none in GitHub Flavored Markdown. Three things are usually meant by the question, and they have three different answers.

The extension syntax

Markdown
: A plain-text formatting syntax.

CommonMark
: The specification that pinned down the ambiguous parts.

Term on one line, definition on the next starting with : . This comes from PHP Markdown Extra and works in kramdown (so Jekyll), Pandoc, Python-Markdown, MultiMarkdown and Quarto.

It does not work on GitHub, in most JavaScript renderers, or in the preview on this page — you get a paragraph beginning with a colon.

The HTML that works everywhere

<dl>
  <dt>Markdown</dt>
  <dd>A plain-text formatting syntax.</dd>
  <dt>CommonMark</dt>
  <dd>The specification that pinned down the ambiguous parts.</dd>
</dl>

<dl>, <dt> and <dd> pass every sanitiser worth using, including GitHub’s and this site’s. This is the option to reach for when the document has to render somewhere you do not control.

Several definitions, or several terms

Both directions work:

<dl>
  <dt>Fence</dt>
  <dd>Three backticks opening a code block.</dd>
  <dd>Also: the same with tildes.</dd>

  <dt>ATX heading</dt>
  <dt>Hash heading</dt>
  <dd>Two names for the same thing.</dd>
</dl>

In the extension syntax, repeat the colon line for extra definitions and stack the term lines for extra terms.

When a table is the better answer

A two-column table is the same amount of typing, renders in every flavour of Markdown that exists, and is easier to scan when there are more than a handful of entries:

| Term | Meaning |
| :--- | :--- |
| Fence | Three backticks opening a code block |
| ATX heading | A heading written with hashes |

Use <dl> when the relationship should be in the markup — a screen reader announces a definition list as one — and a table when it just needs to look right wherever it lands.

Common questions

Does Markdown support definition lists?
Not in the standard. CommonMark has no definition list and neither does GitHub Flavored Markdown. The colon syntax comes from PHP Markdown Extra and was picked up by kramdown, Pandoc, Python-Markdown and a few static site generators.
What is the definition list syntax?
The term on one line, then the definition on the next line starting with a colon and a space. A blank line between entries is optional in most implementations, and a term can have more than one definition line.
Will it work on GitHub?
No. GitHub renders the colon as a literal character, so you get a paragraph that starts with a colon. Use a `<dl>` block instead — GitHub allows it, and so does the preview on this page.
When should I use a table instead?
Whenever portability matters more than semantics. A two-column table renders everywhere, is easy to scan, and takes the same amount of typing. A `<dl>` is better only when the term-and-definition relationship should be in the markup for a screen reader or a stylesheet.
Can a term have several definitions?
Yes, in both forms. Repeat the colon line in the extension syntax, or repeat `<dd>` under one `<dt>` in HTML. Several terms sharing one definition works too — stack the `<dt>` elements.