Extensions

The original Markdown is small on purpose. Over the years, flavours and plugins have added the things real documents need — tables, task lists, footnotes, math and diagrams. Below is an index of the most useful ones and how to write them. Support varies by processor, so check your tool.

GitHub Flavored Markdown (GFM)

By far the most widely used dialect. GFM is a strict superset of CommonMark that bundles several of the extensions below into one spec: tables, task lists, strikethrough, autolinks for bare URLs, and disallowed raw HTML filtering. If a tool says it "supports GitHub Markdown", you get all of these at once.

CommonMark superset GitHub · GitLab · Gitea Most editors

Tables

Build a table with pipes for columns and a row of dashes to separate the header. Colons in the separator set column alignment.

You write 
| Feature | Core | GFM |
|:--------|:----:|----:|
| Tables  |  No  | Yes |
| Tasks   |  No  | Yes |
You get
FeatureCoreGFM
TablesNoYes
TasksNoYes

Task lists

Add [ ] or [x] after a list marker to get interactive checkboxes — the basis of every Markdown to-do list and pull-request checklist.

You write 
- [x] Write the draft
- [x] Review it
- [ ] Publish
You get
  • Write the draft
  • Review it
  • Publish

Diagrams & charts

Several extensions turn a fenced code block into a rendered diagram, so the source of the picture lives in your text file and versions alongside it. These are the most common:

Mermaid

Flowcharts, sequence, class, state, Gantt, pie and ER diagrams from a ```mermaid block. Rendered natively on GitHub, GitLab, Notion and many editors.

flowchartssequencegantt

PlantUML

Text-based UML — sequence, component, deployment and more — embedded in a ```plantuml block via a plugin or server.

UMLserver

Vega-Lite charts

Data charts (bar, line, scatter) from a JSON spec in a fenced block, supported by Markdown viewers such as VS Code extensions and Observable.

data chartsJSON

Graphviz / DOT

Render dot graph descriptions as node-and-edge diagrams through plugins like markdown-it-graphviz.

graphsDOT

Math & formulas

Write LaTeX between dollar signs and have it typeset by KaTeX or MathJax. Single $…$ is inline; double $$…$$ is a centred block. Now supported directly on GitHub and GitLab.

The mass–energy relation is $E = mc^2$.

$$
\int_0^\infty e^{-x}\,dx = 1
$$

Footnotes, callouts & definition lists

Footnotes

Reference a note with [^1] and define it anywhere in the document.

Markdown was created in 2004.[^1]

[^1]: By John Gruber and Aaron Swartz.

Admonitions / callouts

Highlighted note, warning and tip boxes. Syntax varies: GitHub uses > [!NOTE] blockquotes; Obsidian uses > [!warning]; MkDocs and Python-Markdown use !!! note.

> [!NOTE]
> Useful information that users should know.

> [!WARNING]
> Something that could cause a problem.

Definition lists

Pair a term with one or more definitions (PHP Markdown Extra, kramdown).

Markdown
:   A lightweight markup language.
:   Created by John Gruber in 2004.

More handy extensions

Front matter

A YAML (or TOML) metadata block fenced by --- at the top of a file — title, date, tags — read by static-site generators.

Jekyll · Hugo

Auto table of contents

A [[toc]] or [TOC] marker is replaced with a generated, linked table of contents from your headings.

docs

Emoji shortcodes

Type :rocket: and get 🚀. Supported on GitHub, Slack, Discord and many editors.

:shortcodes:

Heading anchors / IDs

Add {#custom-id} after a heading, or auto-generate slugs so every heading is directly linkable.

linking

Highlight & sub/superscript

==marked== for highlight, H~2~O and x^2^ for sub- and superscript (Pandoc, markdown-it plugins).

typography

Abbreviations

Define *[HTML]: HyperText Markup Language once and every match gets a tooltip (PHP Markdown Extra).

tooltips

Which of these work depends entirely on your processor. The tools directory notes what each one supports.