• Use Pandoc Markdown when you need features that core Markdown cannot express: footnotes, academic citations, definition lists, or maths notation.
• Be aware that Pandoc Markdown files are designed to be processed by Pandoc — some syntax will not render correctly in other tools such as GitHub or VS Code.
• Keep to the extension set your project actually needs; enabling every available extension unnecessarily complicates your source files.
• For documents that must also work in web-based renderers, stick to CommonMark or GFM syntax in the body text and reserve Pandoc-specific features for dedicated publishing projects.

Origin

Pandoc was created by John MacFarlane — the same person who later led the CommonMark standardisation effort — and first released in 2006. MacFarlane needed a tool to convert between academic document formats, and Markdown was a natural plain-text source language to build on.

Pandoc Markdown evolved alongside the tool, accumulating extensions to support the writing conventions that standard Markdown lacked: footnotes, citations, definition lists, metadata headers, raw LaTeX blocks, and more. Today the full list of Pandoc Markdown extensions runs to several dozen.

The Extension System

Rather than treating Pandoc Markdown as a fixed set of rules, Pandoc lets you choose a base format and add or remove individual extensions. The default markdown format enables a wide set of extensions. Starting from commonmark or gfm and adding only what you need is a cleaner approach for documents that may also be read in other tools.

Key Extensions

Footnotes

Pandoc Markdown supports both reference footnotes and inline footnotes. Reference footnotes use a label in the text and a matching definition elsewhere in the document.

The castle was completed in 1483.[^1]

[^1]: Based on the dating evidence in the 1985 survey by English Heritage.

Definition lists

Definition lists associate a term with one or more definitions. They are ideal for glossaries, Q&A sections, and reference guides.

Recto
:   A right-hand page in a book — always odd-numbered.

Verso
:   A left-hand page in a book — always even-numbered.

Metadata blocks

A YAML block at the top of a Pandoc document sets document-level metadata — title, author, date, and more — that Pandoc passes through to the output format.

---
title: A History of Thornbury Village
author: Margaret Hollis
date: 2026
---

Citations

With a bibliography file attached, Pandoc can resolve citation keys in your text and format a complete reference list automatically in the style of your choice.

The population peaked in the mid-nineteenth century [@census1851].

Maths notation

LaTeX maths notation is supported inline and as block equations, rendered via the output format's maths engine.

The area of a circle is $A = \pi r^2$.

Pandoc as a Conversion Tool

Pandoc is not a renderer in the usual sense — it does not display Markdown in a browser or application. It converts documents between formats. The typical workflow is:

1. Write the document in Pandoc Markdown
2. Run Pandoc to convert it to the target format (PDF, EPUB, Word, HTML, etc.)
3. Distribute or publish the output

This means Pandoc Markdown files are usually not read directly in a web browser. If portability to web renderers matters, use CommonMark or GFM for the body text and limit Pandoc-specific syntax to projects where Pandoc is the intended processing tool.