Markdown Definition List: Syntax, Support, and the Fallback

The Markdown definition list syntax puts a term on one line and a colon-prefixed definition on the next. Pandoc, kramdown, PHP Markdown Extra, Hugo, and GitLab render it as an HTML <dl>. GitHub, Obsidian, Notion, and VS Code don't. This post shows the syntax, a support table, and the fallback that works everywhere.

Definition List Markdown Syntax

The syntax comes from PHP Markdown Extra, and Pandoc adopted it with a few additions. Write the term on its own line, then one or more definitions, each beginning with a colon and at least one space.

Markdown
:   A plain-text formatting syntax created in 2004.

Renderer
:   The program that turns Markdown into HTML.
:   Examples include Pandoc, kramdown, and marked.

Rendered, that produces a <dl> with two <dt> terms. "Markdown" has one <dd> and "Renderer" has two, displayed as indented lines under the bold-ish term (styling depends on the site's CSS). Per the PHP Markdown Extra spec, the colon may be indented up to three spaces and must be followed by one or more spaces or a tab. Terms need a blank line separating them from the previous definition.

The Pandoc manual extends this under the definition_lists extension. A tilde works as well as a colon, a blank line between term and definition is optional, and a definition may hold several indented blocks (paragraphs, code, nested lists).

Leave a blank line before the definition and Pandoc wraps it in a paragraph, which adds spacing; omit it for a compact list. kramdown follows the same colon rule. Its docs note that every line of the preceding paragraph becomes a term, so two adjacent lines give you two terms sharing one definition.

What Is Meant by Definition List?

A definition list pairs names with descriptions, the way a glossary or a man page does. In HTML it's the <dl> element, holding <dt> (term) and <dd> (description) children. HTML's own docs now call it a description list, because it suits any name-value grouping: glossary entries, metadata like "Author: Jane", or FAQ pairs.

That semantic structure is the reason to want one. A screen reader announces a <dl> as a list of terms and descriptions, and search engines can parse it. A bold word followed by an indented paragraph looks the same to a sighted reader but carries none of that meaning. Ordinary bullet and numbered lists are a different element entirely; our Markdown lists guide covers those.

Where Do Markdown Definition Lists Work?

Support is the whole problem. The colon syntax isn't in CommonMark, and the GFM spec defines no definition list extension either, so anything built on those parsers ignores it. Here is what the docs of the ten processors people actually hit say.

Processor	Colon syntax	Notes
Pandoc	Yes	definition_lists extension, on by default in pandoc markdown
PHP Markdown Extra	Yes	The original syntax
kramdown (Jekyll default)	Yes	Built in
Python-Markdown / MkDocs	Yes, opt in	Enable the def_list extension
Hugo (Goldmark)	Yes	definitionList: true by default
markdown-it	Plugin	markdown-it-deflist, Pandoc-compatible
GitLab	Yes	Description lists since GitLab 17.7
GitHub	No	Raw <dl> HTML renders instead
Obsidian	No	Long-standing forum feature request; HTML works
Notion, VS Code preview	No	Notion strips HTML too

A few rows need a sentence. Python-Markdown's def_list extension follows the PHP Markdown Extra syntax exactly, and MkDocs users turn it on under markdown_extensions. Hugo's docs list definitionList: true among the Goldmark defaults, so Hugo sites get it for free. GitLab's Markdown docs describe description lists as introduced in GitLab 17.7, with the same colon-per-description form.

For Obsidian, the workaround is HTML, and the Obsidian cheat sheet lists the other syntax it does and doesn't support. If your definition list markdown has to render on GitHub, skip to the HTML section.

Try the Definition List Syntax in the Editor

Our editor uses the marked parser, which has no definition list extension. The colon lines below therefore render as plain text, which is exactly what GitHub and Obsidian do with them. The HTML block underneath renders as a real list. Seeing both side by side tells you which one to paste.

One limitation of the preview: it shows unsupported syntax as text rather than flagging it, so a colon line can look like a deliberate sentence. Read the rendered pane carefully when you're testing.

How Do You Make a Definition List in HTML?

Markdown lets you drop raw HTML into a document, and <dl> is one of the tags GitHub keeps. The open-source html-pipeline sanitizer that GitHub's Markup project points to allows dl, dt, and dd, while stripping style and class attributes. GitLab's docs say they use the same allowlist plus a few extra tags.

<dl>
  <dt>Term</dt>
  <dd>Definition of the term.</dd>
  <dt>Second term</dt>
  <dd>First definition.</dd>
  <dd>Second definition of the same term.</dd>
</dl>

Two rules keep this rendering. Don't indent the whole block by four spaces, or Markdown treats it as a code block. And inside the tags, write HTML rather than Markdown: <dd>**bold**</dd> shows literal asterisks on GitHub, so use <strong> instead. Our Markdown vs HTML comparison explains why raw HTML is the portable escape hatch.

We prefer the HTML form for anything shared on GitHub. The same file then renders correctly in Obsidian, in our editor, and through Pandoc, which passes raw HTML through to HTML output.

Definition List Workarounds Without HTML

Sometimes HTML is banned too (Notion, most chat apps, some static site themes). Three plain-Markdown patterns get close.

Bold term, then a paragraph. **Term** on one line, a blank line, then the definition. Simplest, renders everywhere, no semantics.

A two-column table. Term in the left column, definition on the right. Good for short definitions; multi-paragraph definitions don't fit in a cell. Our Markdown table guide has the syntax.

Nested bullets. A bullet for the term with an indented bullet for each definition. It keeps the one-to-many shape of a real list and renders in every parser, at the cost of bullet glyphs you may not want.

- Markdown
  - A plain-text formatting syntax created in 2004.
- Renderer
  - The program that turns Markdown into HTML.

Common Definition List Markdown Mistakes

No space after the colon. :Definition is a paragraph in every parser. The marker needs at least one space or a tab after it.

No blank line before the next term. In PHP Markdown Extra and Python-Markdown, a term that directly follows a definition line is read as a continuation of that definition. Leave one blank line between the last definition and the next term.

Expecting it to render on GitHub. The colon syntax turns into a sentence starting with a colon. Switch to the <dl> block above; it's the only markdown definition list form GitHub renders.

Markdown Definition List FAQ

Use the definition list markdown colon syntax when your pipeline is Pandoc, kramdown, Hugo, Python-Markdown with def_list, or GitLab. Use the <dl> HTML block when the page has to render on GitHub or in Obsidian. Paste either into the editor first; the preview shows in seconds which one your readers will actually see.