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.
Key Takeaways
- Write the term on its own line, then the definition on the next line starting with a colon.
- Definition lists are NOT part of CommonMark or GFM; they come from the Markdown Extra extension.
- A single term can have multiple definitions, and a single definition can apply to multiple terms.
- Support varies widely by platform, so confirm your renderer handles definition lists before relying on them.
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>Definition lists are not part of core CommonMark or GFM. They originate from Michel Fortin’s Markdown Extra extension, so support depends entirely on your renderer or plugin (for example, remark-definition-list in the remark/rehype ecosystem).
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>Definition lists work especially well for glossary pages and API parameter references, where each entry has a clear term-and-explanation shape that a plain bullet list doesn’t capture semantically.
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.
Related Articles
Deepen your understanding with these curated continuations.
Autolinks in Markdown: Bare URLs and Emails
Learn the difference between CommonMark's angle-bracket autolinks and GitHub-Flavored Markdown's extended autolinks for bare URLs and email addresses.
Escaping Special Characters in Markdown
Learn how to escape asterisks, underscores, brackets, and other special characters in Markdown so they display as literal text instead of triggering formatting.
Beyond GFM: Highlight, Subscript, Superscript & Emoji in Markdown
Learn the non-standard highlight, subscript, superscript, and emoji shortcode syntax some Markdown renderers support, and why they need a plugin to work.
