Definition list syntax
This is a Markdown Extra / PHP Markdown extension, supported by Pandoc, Python-Markdown, and some static site generators, but not by GitHub Flavored Markdown or CommonMark.
Markdown
: A plain-text formatting syntax created in 2004.
GFM
: GitHub Flavored Markdown, GitHub’s superset of CommonMark.Portable alternative
For GitHub READMEs and maximum compatibility, fake it with bold terms, which renders acceptably everywhere.
**Markdown**
A plain-text formatting syntax created in 2004.
**GFM**
GitHub’s superset of CommonMark.HTML <dl> lists on GitHub
When you want a real definition list on GitHub, write it in HTML. GitHub’s sanitizer allows the <dl>, <dt> and <dd> tags, so the result is semantic markup that browsers indent automatically and screen readers announce as a list of terms.
<dl>
<dt>Markdown</dt>
<dd>A plain-text formatting syntax created in 2004.</dd>
<dt>GFM</dt>
<dd>GitHub Flavored Markdown, a superset of CommonMark.</dd>
</dl>Multiple terms and multiple definitions
In parsers that support the colon syntax, a term can have several definitions (one colon line each), and PHP Markdown Extra also lets several terms share one definition by stacking them. Pandoc additionally accepts a tilde as the marker, and lets a definition span several paragraphs when the extra paragraphs are indented.
Converter
: A tool that changes a file from one format to another.
: In MDTool, a page such as Markdown to PDF.
PDF
Portable Document Format
: A fixed-layout file format for sharing documents.Which parsers support definition lists
Support depends entirely on the parser or its extensions, which is why definition lists are the least portable syntax on this cheat sheet.
| Renderer | Colon syntax | Note |
|---|---|---|
| Pandoc | Yes | definition_lists extension, on by default |
| PHP Markdown Extra | Yes | Where the syntax comes from |
| Hugo (Goldmark) | Yes | Enabled by default |
| Jekyll (kramdown) | Yes | - |
| MkDocs, Python-Markdown | With def_list extension | Add it to markdown_extensions |
| GitHub, GitLab | No | Use <dl> HTML or bold terms |
| Obsidian, VS Code preview | No | Plugins can add it |
A table as a glossary
For a short glossary with one-line definitions, a two-column table is often clearer than any definition list, works on every GFM platform, and converts cleanly to PDF and Word. Switch to bold terms or <dl> when definitions run to several sentences, because long text in table cells becomes hard to read.
| Term | Definition |
|------|------------|
| Markdown | Plain-text formatting syntax |
| GFM | GitHub Flavored Markdown |
| CommonMark | A strict Markdown specification |Frequently Asked Questions
Do definition lists work on GitHub?
No. GitHub Flavored Markdown renders the colon syntax as plain text. Use bold terms followed by an indented or line-broken description, or inline HTML <dl>/<dt>/<dd> tags, which GitHub does allow.
How do I make a glossary in a GitHub README?
Use an HTML <dl> list with <dt> for each term and <dd> for its definition, or a two-column Markdown table for short definitions. Both render correctly on GitHub.
Does Obsidian support definition lists?
Not natively. The colon syntax shows as plain text in Obsidian. Use bold terms followed by a line break, or a community plugin that adds definition list rendering.
Try it live
Paste this syntax into the free markdown to html converter and see the rendered output instantly. No signup, and everything runs in your browser.
Open Markdown to HTML Converter →