The original Markdown was deliberately minimal: headings, paragraphs, emphasis, lists, links and code. As soon as you use it for real documents, though, important pieces are missing: a comparison table, a footnote, a to-do list. That is why extensions were born, meaning additional syntax supported by some parsers but not by all.
The first concept to fix in your mind is exactly this: Markdown is not a single standard. There is CommonMark, a rigorous specification of the basic syntax, and on top of it variants such as GitHub Flavored Markdown (GFM) or Pandoc's Markdown, which add features. Before using an extension it is worth knowing where the file will be read.
Tables
Pipe tables are the most widespread extension. The second row, made of dashes, separates the header from the body; colons set the alignment.
| Format | Editable | Suitable for archiving |
|:---------|:--------:|-----------------------:|
| DOCX | yes | with reservations |
| PDF/A | no | yes |
| Markdown | yes | yes |
:---aligns left,:---:centre,---:right.- The pipes do not need to line up visually: the parser recognises them anyway. Aligning them only helps whoever reads the source.
- The main limit is that each cell sits on one line. No lists or paragraphs inside a cell, apart from tricks that are not very portable.
If a table goes beyond five or six columns, the source becomes unreadable. In that case consider whether the content would not be better as a structured list or as a separate CSV file.
Footnotes
Many parsers, including Pandoc and GFM, accept footnotes in this form:
The format was standardised in 2005.[^iso]
[^iso]: This is the first version of the dedicated ISO standard.
The placeholder [^iso] can be a number or a word; the final numbering is assigned automatically, in the order in which the notes appear. Using a meaningful label instead of [^1] makes it easier to move paragraphs around without getting confused.
On web pages the notes end up at the bottom of the document with a back-link; when converting to PDF they become real footnotes.
Task lists
Task lists are a bulleted list with a checkbox:
- [x] Gather the requirements
- [ ] Write the draft
- [ ] Review with the team
On development platforms the boxes become clickable and show progress. In a PDF or a static site they are just symbols. They are very useful in meeting minutes and release plans, because readers immediately see what is left to do.
Strikethrough, highlighting and other additions
~~text~~produces strikethrough in GFM and in Pandoc.==text==for highlighting works in some note apps but not in GFM: a typical example of syntax that breaks when you change tools.- Web addresses written out in full are turned into links automatically in GFM, but not in pure CommonMark.
Definition lists
Pandoc and other parsers support definition lists, handy for glossaries:
Hash
: Fixed-length fingerprint computed from some content.
Checksum
: Value used to verify the integrity of a file.
GFM does not recognise them: there the result would be a paragraph with the colons showing.
YAML header
Many site generators and Pandoc read an initial block delimited by three dashes, with title, author, date and other information:
---
title: "Operations manual"
author: "Technical office"
lang: en
---
This metadata does not appear in the body but is used for the PDF cover, the web page title or the filters of an archive. Watch out for quotes and colons inside values: a YAML syntax error often blocks the entire conversion.
Which variant to choose
| Destination | Recommended variant | Notes |
|---|---|---|
| Code repository | GFM | Tables, task lists, strikethrough |
| Conversion to PDF or DOCX | Pandoc Markdown | Footnotes, definitions, citations, metadata |
| Note app | The app's own | Check the export |
| Text everyone must be able to read | CommonMark | Maximum compatibility |
In my work I keep a simple rule: if a document has to move between different tools, I use only tables, footnotes and task lists, which are the most widely supported extensions, and I avoid exotic syntax.
In short
- Markdown has several variants: CommonMark for the basics, GFM and Pandoc for extensions.
- Tables and footnotes are the most useful and best-supported extensions, but cells stay on one line.
- Task lists work well in meeting minutes and become interactive only on some platforms.
- Definition lists and highlighting are not portable: check the destination tool.
- The YAML header carries metadata, but a syntax error can block the conversion.
