Pandoc Markdown: Syntax Extensions and Conversion Commands

Pandoc markdown is pandoc's own dialect: standard Markdown plus extensions for metadata, tables, footnotes, citations, math, and attributes. This guide lists the extensions you'll actually use with one example each and gives the five conversion commands people run most. It also separates the syntax any editor renders from the parts only pandoc understands.

What Is Pandoc Markdown?

Pandoc is a command-line converter that reads and writes dozens of document formats. The current release is pandoc 3.11 from 28 August 2026, and it's free software under the GPL. When you run pandoc -f markdown, you get the extended Markdown pandoc documents in the manual section titled Pandoc's Markdown. It's also the input format pandoc assumes when you pass a .md file without -f.

Every extension is a switch. Append +name to enable one or -name to disable it, so -f markdown+emoji adds emoji shortcodes and -f markdown_strict-smart turns off smart punctuation in the original Markdown.pl dialect. To see the full list for any format, with the defaults marked, run:

pandoc --list-extensions=markdown

That distinction matters for the rest of this post. The markdown reader enables most extensions by default. The gfm and commonmark readers start from plain CommonMark and enable far fewer, which is why a README can look different after conversion.

The Pandoc Markdown Extensions You'll Actually Use

The manual describes more than 40 extensions. These are the ones that show up in real documents, with the syntax for each. Together they make a copyable sample file.

---
title: Quarterly Report
author: Dana Ortiz
date: 2026-09-11
bibliography: refs.bib
---

# Summary {#sec-summary}

Revenue grew 12% this quarter.[^1] See [the summary][] for context.

| Region | Q2 | Q3 |
|:-------|---:|---:|
| North  | 41 | 46 |
| South  | 38 | 43 |

: Revenue by region (thousands)

Term
:   A definition list entry, from PHP Markdown Extra.

::: {.warning}
This fenced div becomes a `div` with class warning in HTML.
:::

The [key figure]{.highlight} is in @sec-summary. Prior work [@doe99; @smith2000] agrees.

The growth rate is $r = \frac{46 - 41}{41}$.

(@) First numbered example
(@) Second numbered example, numbered across the whole document

[^1]: Compared with the same quarter last year.

What each block does:

YAML metadata block (yaml_metadata_block). Starts with --- and ends with --- or .... The first --- must not be followed by a blank line. Fields such as title, author, and date fill the template; bibliography feeds citations.

Header attributes. {#sec-summary} sets the heading's ID. Pandoc also generates IDs automatically, and with implicit_header_references you can link to any heading by its text: [Summary][].

Pipe tables (pipe_tables) with a caption line starting :. Pandoc also reads grid tables built from +, -, |, and =, which allow multi-line cells. Our Markdown table guide covers the pipe syntax in depth.

Footnotes (footnotes) with [^1] references. The Markdown footnotes post covers the platforms that render them.

Definition lists (definition_lists): a term on one line, then : and three spaces before the definition.

Fenced divs (fenced_divs): at least three colons plus attributes. The attribute syntax matches fenced code blocks.

Bracketed spans (bracketed_spans): [text]{.class key="val"} becomes a span with attributes.

Citations (citations): @key inline, [@key] in brackets, semicolons between items. Rendering requires --citeproc and a bibliography.

Math (tex_math_dollars): anything between dollar signs is TeX math. The opening $ needs a non-space character to its right, and the closing one needs a non-space character to its left.

Example lists (example_lists): the (@) marker numbers examples across the whole document, not just one list.

Smart punctuation (smart): straight quotes become curly, --- becomes an em dash, -- an en dash, ... an ellipsis. It's on by default for markdown input.

Five Pandoc Conversion Commands

These cover the conversions people search for. -s (standalone) adds the document head; -o names the output; --toc builds a table of contents.

1. Pandoc markdown to PDF. Pandoc doesn't write PDF itself. It writes LaTeX (or HTML, ConTeXt, ms, or Typst) and calls an engine. With no engine specified, pandoc uses pdflatex, so you need a LaTeX distribution installed.

pandoc report.md -o report.pdf
pandoc report.md -o report.pdf --pdf-engine=xelatex --toc
pandoc report.md -o report.pdf --pdf-engine=weasyprint   # HTML and CSS route

Valid engines are pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtmltopdf, weasyprint, pagedjs-cli, prince, context, groff, pdfroff, and typst. The Markdown to PDF guide walks through installing an engine and the browser alternatives.

2. Pandoc markdown to Word. DOCX output works with no extra software. To control fonts and styles, pass a reference document; pandoc ignores its content and copies its stylesheets, margins, page size, headers, and footers.

pandoc report.md -o report.docx
pandoc -o custom-reference.docx --print-default-data-file reference.docx
pandoc report.md -o report.docx --reference-doc=custom-reference.docx

Edit the styles in custom-reference.docx with Word once, then reuse it for every conversion. The Markdown to Word guide has the full workflow.

3. Markdown to HTML.

pandoc report.md -s -o report.html --toc --css style.css

4. Word to Markdown. Pandoc reads DOCX well, including headings, lists, tables, footnotes, and images (extract them with --extract-media).

pandoc report.docx -t markdown -o report.md --extract-media=./media
pandoc report.docx -t gfm -o README.md

5. Citations in any of the above. Add --citeproc and a bibliography file:

pandoc report.md -o report.docx --citeproc --bibliography refs.bib

For LaTeX source rather than a PDF, -t latex writes the .tex file; that's a separate topic.

Once a command grows past three flags, move the options into a defaults file and pass it with -d. A defaults.yaml holding the input format, the PDF engine, the reference document, and the bibliography keeps every conversion in a project consistent. It's also easier to commit than a shell alias.

Can Pandoc Convert a PDF to Markdown?

No, and every search for pandoc pdf to markdown ends here. PDF is an output format only. The -f input list in the pandoc manual includes docx, epub, html, latex, rst, and many others, but not pdf, because a PDF stores positioned glyphs rather than document structure. Running pandoc file.pdf -o file.md stops with the message: Pandoc can convert to PDF, but not from PDF. We checked with pandoc 3.8 locally.

The route that works is a PDF text extractor first, then cleanup. Our PDF to Markdown guide compares the options, and the PDF to Markdown tool does the extraction in the browser. Expect to fix headings and tables by hand; the source simply doesn't contain that information. Once the text is in Markdown, pandoc takes over again for the DOCX or HTML output, so the two tools chain together well.

markdown vs gfm vs commonmark Input Formats

Pandoc's manual lists seven Markdown readers. They are markdown (pandoc's own), markdown_strict (Markdown.pl), markdown_phpextra, markdown_mmd (MultiMarkdown), commonmark, gfm, and commonmark_x (CommonMark with many pandoc extensions). The deprecated markdown_github still exists but the manual tells you to use gfm.

The practical differences, checked against pandoc --list-extensions on pandoc 3.8, are these.

Feature	-f markdown	-f gfm	-f commonmark
Pipe tables	Yes	Yes	No
Footnotes	Yes	Yes	No
Task lists	Yes	Yes	No
YAML metadata	Yes	Yes	No
Definition lists, fenced divs, citations	Yes	No	No
Smart punctuation	On by default	Off	Off
Heading IDs	Pandoc style	GitHub style	None

This is why a GitHub README converted with -f markdown can come out with curly quotes, em dashes where you typed ---, and different anchor links. Use -f gfm for files written for GitHub and -f markdown for files written for pandoc. The same rule applies to output: -t gfm writes a README that GitHub renders as intended, while -t markdown writes pandoc's dialect with attributes and smart punctuation reversed to straight quotes. When in doubt, -f commonmark_x gives you CommonMark parsing with most of pandoc's extensions available as switches.

Try Pandoc Markdown in the Editor

The portable half of the sample file, the part any CommonMark or GFM renderer handles, is below. Headings, the pipe table, emphasis, and code render in the preview. The fenced div, definition list, and citation show as plain text. The YAML block comes out as a horizontal rule followed by a heading, because a plain renderer reads the closing --- as a setext underline. That's a quick way to see which lines depend on pandoc before you convert.

For a one-off conversion without installing pandoc or LaTeX, the Markdown to PDF and Markdown to DOCX tools take the same file, and DOCX to Markdown covers the reverse. We prefer pandoc for anything scripted or repeated, and the browser tools for a document you convert once.

Common Pandoc Markdown Mistakes

A blank line after the opening ---. The YAML block is then read as a horizontal rule and a paragraph. The manual is explicit: the initial --- must not be followed by a blank line.

Forgetting -s for HTML. Without --standalone, pandoc emits an HTML fragment with no head, so your CSS and title are missing. PDF and DOCX output are always standalone.

No LaTeX engine installed. pandoc report.md -o report.pdf fails with a message that pdflatex was not found. Install TeX Live, MiKTeX, or TinyTeX, or switch engines with --pdf-engine=typst or --pdf-engine=weasyprint.

Citations that never render. [@doe99] stays literal unless you pass --citeproc and supply bibliographic data through --bibliography or the bibliography metadata field. One acknowledged limitation: pandoc's citation processing is powerful but slow to learn, and CSL style errors are hard to read.

Pandoc Markdown FAQ

Pandoc markdown gives you metadata, tables, footnotes, citations, math, and attributes in one plain-text file, and five commands cover nearly every conversion you'll need. Draft the portable parts in the editor to check the structure, keep the pandoc-only syntax for the final file, and let the command line do the rest. The pandoc manual is the reference when an extension behaves unexpectedly.