Definition Lists and Other Markdown Extras Most Editors Skip

A Markdown definition list pairs a term with its definition using a colon. It works in Pandoc. It doesn't work in GitHub Flavored Markdown, because definition lists were never part of the core spec to begin with.

Quick answer

Definition lists, footnotes, subscript/superscript, and abbreviations are all real Markdown syntax — just not core Markdown syntax. Original Markdown and CommonMark, the spec most editors build on, never defined any of them. They exist because PHP Markdown Extra and Pandoc added their own extensions, and GitHub Flavored Markdown (GFM) picked up some but not all of that work. So a definition list you write in one editor can quietly turn into plain paragraphs in another. Knowing which extras your renderer actually supports, before you write something that depends on one, saves you from finding out the hard way.

How it actually works

Definition lists: the term-and-colon construct

The syntax is short. Put the term on its own line, then a colon (or tilde) and a space, then the definition on the next line.

Markdown
: A lightweight markup language for formatting plain text.

CommonMark
: A formal, unambiguous specification of Markdown syntax.
: Published in 2014 to resolve years of implementation drift.

A term can carry more than one definition — just stack additional colon-prefixed lines underneath it, as the Markdown Guide documents. The construct comes from PHP Markdown Extra and is implemented by Pandoc. It's not in CommonMark, and it's not in GFM either — GitHub's own syntax documentation never mentions it.

Footnotes: reference plus definition, with a wiki gap

Footnotes use a bracket-caret reference inline, paired with a definition anywhere else in the file:

Markdown's core spec is informal by design.[^1]

[^1]: John Gruber never published a formal grammar for it.

Where you place the footnote in your source doesn't matter — it renders at the bottom of the page regardless. GFM handles this cleanly, with one exception worth knowing: GitHub doesn't render footnotes inside wikis. Write a footnote-heavy page into a wiki, and you'll get a broken-looking reference tag and nothing else. GitHub's alert syntax makes a good comparison — see GitHub's own alert syntax for another feature GFM bolted onto the core spec that other renderers don't recognize at all.

Subscript, superscript, and abbreviations: no dedicated token

Neither subscript nor superscript has real Markdown syntax in GFM. You write raw HTML instead: <sub>text</sub> or <sup>text</sup>. No asterisk-style shorthand for either one.

Abbreviations diverge even further between implementations. Pandoc treats an abbreviation list as a separate, file-driven feature — a plain wordlist fed in as a command-line option, expanded at render time with a nonbreaking space so the term doesn't wrap awkwardly. Markdown Extra treats abbreviations as an inline tag instead, written directly in the document. Two processors, two different mental models, for what looks like the same feature on paper. If a Markdown feature has ever seemed to "just not work" for you, this is often why — see Markdown comments that never render for another extra that behaves differently depending on where you paste it.

When to use it (and when to skip it)

None of this is an oversight. John Gruber's original Markdown spec explicitly scoped out tables, definition lists, and anything else that couldn't be expressed cleanly in plain text — his fallback for anything outside that scope was simple: drop into raw HTML. When CommonMark formalized the ambiguous parts of that spec in 2014, it deliberately left the same extras out of scope. That's exactly why they never converged into one shared syntax. Every processor that wanted tables, footnotes, or definition lists had to invent — or borrow — its own version.

The practical rule: don't reach for an extra until you've confirmed your renderer supports it. If a document only ever lives in one tool, use whatever that tool supports. If it needs to survive a move between GitHub, a static site generator, and a Pandoc export, stick to the core syntax and note anywhere you had to fall back to raw HTML — see why the same Markdown file renders differently everywhere for the fuller picture of what breaks and why. Definition lists and footnotes earn their keep in glossaries, reference docs, and citation-heavy writing, where the structure actually does something. For a quick note or a README, plain paragraphs and a regular list usually get the job done just as well.

Frequently Asked Questions

Do definition lists work in GitHub Flavored Markdown?

No. GFM's own syntax documentation never mentions definition lists — the term-plus-colon construct comes from PHP Markdown Extra and is implemented by Pandoc and a handful of other processors, not GitHub.

What's the exact syntax for a Markdown definition list?

Put the term on its own line, then a colon (or tilde) and a space, then the definition on the next line. Multiple definitions for one term just stack as additional colon-prefixed lines underneath it.

Will footnotes render everywhere I use them?

Footnotes are widely supported in GitHub Flavored Markdown and Pandoc, but GitHub explicitly doesn't render them inside wikis — always check your target renderer before writing a footnote-heavy document.

How do I add subscript or superscript in Markdown?

There's no dedicated Markdown token for either in GFM — you write raw HTML directly in the file: <sub>text</sub> or <sup>text</sup>.

Why do these extras exist outside the core Markdown spec in the first place?

CommonMark deliberately standardized only the ambiguous parts of Gruber's original syntax and left tables, footnotes, and definition lists out of scope. Each processor — Pandoc, Markdown Extra, GFM — ended up implementing its own version differently.

How Carets fits in

Knowing which Markdown extras are processor-specific matters most when you're deciding where to actually write. Carets keeps every file in plain Markdown and plain text — no proprietary dialect, no lock-in to one renderer's version of "extended syntax." Files stay organized into files, projects, and tags, and the editor is native and fast on iPhone, iPad, and Mac, so switching devices doesn't mean switching formats.

That portability is the point. A document you write in Carets opens correctly anywhere Markdown is understood, because it never depended on an extra your next tool might not support. Carets is available on the App Store for iPhone, iPad, and Mac.