Glossaries, API parameter references, and term-by-term documentation all share the same shape: a term, followed by its definition. Regular bullet lists can approximate this, but they don’t semantically separate the term from its description. Definition lists solve that with dedicated syntax, though unlike most topics in this series, they come from an extension rather than CommonMark or GFM itself. This guide covers the syntax and where it does and doesn’t work.
How Do I Write a Basic Definition List?
Write the term as a plain line of text, then on the very next line, start the definition with a colon and a space.
Markdown
: A lightweight markup language for formatting plain text.
CommonMark
: A strict, standardized specification of Markdown syntax.This renders as a term/definition pairing:
<dl>
<dt>Markdown</dt>
<dd>A lightweight markup language for formatting plain text.</dd>
<dt>CommonMark</dt>
<dd>A strict, standardized specification of Markdown syntax.</dd>
</dl>Can a Term Have Multiple Definitions?
Yes. Add another : line directly after the first to attach a second definition to the same term.
API Key
: A unique identifier used to authenticate requests.
: Should never be committed to version control.Both definitions attach to the same term:
<dl>
<dt>API Key</dt>
<dd>A unique identifier used to authenticate requests.</dd>
<dd>Should never be committed to version control.</dd>
</dl>Can Multiple Terms Share One Definition?
Yes. Stack several term lines directly above a single definition line to apply that definition to all of them.
HTML
XHTML
: Markup languages used to structure web page content.This produces two terms sharing one definition:
<dl>
<dt>HTML</dt>
<dt>XHTML</dt>
<dd>Markup languages used to structure web page content.</dd>
</dl>Summary Checklist
- Write the term on its own line, then the definition on the next line starting with
:. - Definition lists require an extension, since they aren’t part of CommonMark or GFM.
- Stack multiple
:lines under one term for multiple definitions. - Stack multiple term lines above one
:line to share a single definition. - Confirm renderer support first, especially for MDX-based sites that need a specific remark plugin enabled.
Frequently Asked Questions
Does GitHub render definition lists?
No. GitHub’s Markdown renderer does not support the Markdown Extra definition list syntax, so it displays as plain paragraph text with a literal colon.
Do I need a blank line before a definition list?
Yes, generally. Like most block-level Markdown elements, a definition list needs a blank line separating it from the preceding paragraph so the parser recognizes it as a new block.
Is there a simpler alternative if my renderer doesn’t support this syntax?
Yes. A bold term followed by a colon and its description in a regular paragraph or bullet list (- **Term**: Definition) achieves a similar visual result without requiring extension support, at the cost of losing the semantic <dl>/<dt>/<dd> markup.
What to Read Next
- Markdown List Guide: Ordered and Unordered Lists — Compare this syntax against standard bullet and numbered lists.
- Tables in Markdown - Create & Format Data — See another structured-data format for term/value pairs.
