Pandoc Cheatsheet - Document Conversion Command Reference

Copy-pasting a document between formats usually destroys the structure you worked for. Pandoc converts between Markdown, HTML, PDF, DOCX and EPUB by mapping to a document model, so headings, tables and citations survive. This reference covers basic interchange, Chinese-PDF fonts, templates/styles, slides, e-books and citations/math. Use it when your CMS, wiki or client insists on a format you don't author in. After reading you move content across formats with markup intact.

Dev Tools·38 commands·Last updated 2026-07-21

Typical Use Case

For technical writers and documentation maintainers who want one source file to produce many formats: write in Markdown, send Word to reviewers, PDF for archiving, HTML for the website, slides for a talk. This sheet is grouped by four layers: formats via -f/-t and -o, metadata via -V and --metadata-file, layout via --reference-doc / --template / --self-contained, and references via --citeproc with --csl. It fits a "one Markdown, many outputs" content pipeline, and debugging cases where output loses styles, the TOC, or math rendering.

Basic Conversion 8

pandoc input.md -o output.html

Markdown to HTML

pandoc input.md -o output.pdf

Markdown to PDF (needs LaTeX)

pandoc input.md -o output.docx

Markdown to Word

pandoc input.html -o output.md

HTML to Markdown

pandoc input.docx -o output.md

Word to Markdown

pandoc input.md -o output.epub

Markdown to EPUB

pandoc -f markdown -t html5 input.md -o output.html

Explicitly set input/output formats

pandoc input.md -o output.org

Markdown to Org-mode

PDF Advanced Options 5

pandoc input.md -o output.pdf --pdf-engine=xelatex

Use xelatex engine (Chinese support)

pandoc input.md -o output.pdf -V mainfont="Noto Sans CJK SC"

Specify a Chinese font

pandoc input.md -o output.pdf --toc

Generate a table of contents

pandoc input.md -o output.pdf --toc --toc-depth=3

TOC depth of 3 levels

pandoc input.md -o output.pdf -V geometry:margin=1in

Set page margins

Templates & Styles 5

pandoc -s input.md -o output.html

Produce standalone HTML (with head)

pandoc input.md --template=mytemplate.html -o output.html

Use a custom template

pandoc input.md --css=style.css --self-contained -o output.html

Inline CSS into a single file

pandoc input.md -H header.html -o output.html

Inject custom content into head

pandoc -o template.html --print-default-template html5

Print the default template

Metadata & Slides 5

pandoc input.md -V title="Title" -V author="Author" -o output.pdf

Set metadata

pandoc input.md -t beamer -o output.pdf

Markdown to Beamer slides

pandoc input.md -t slidy -o output.html

To Slidy HTML slides

pandoc input.md -t revealjs -o output.html

To reveal.js slides

pandoc input.md -f markdown -t plain

To plain text (strip formatting)

Citations & Math 6

pandoc input.md --citeproc -o output.pdf

Enable citation processing

pandoc input.md --bibliography=refs.bib --citeproc -o output.pdf

Specify a BibTeX library

pandoc input.md --csl=ieee.csl -o output.pdf

Specify citation style (CSL)

pandoc input.md --mathjax -o output.html

Render math with MathJax

pandoc input.md --katex -o output.html

Render math with KaTeX

pandoc --list-extensions markdown

List Markdown extensions supported

Common Flags 9

--highlight-style=tango

Code highlighting theme

--number-sections

Number section headings

--standalone / -s

Produce a complete document (with head/foot)

--metadata-file=meta.yaml

Read metadata from YAML

--filter=pandoc-filter

Use a custom filter

-V key=value

Pass a variable to the template

--wrap=auto

Auto-wrap lines (auto/preserve/none)

--columns=80

Set wrap column width

--reference-doc=template.docx

Use a Word reference doc for styling

Parameter matrix

Parameter	Effect	Example
`-s / --standalone`	Emit a full document with head and body wrappers; without it you only get a fragment	`pandoc -s input.md -o output.html`
`--reference-doc=template.docx`	Control docx styling from a Word reference document, fixing default heading and code fonts	`--reference-doc=template.docx`
`--self-contained + --css`	Inline the CSS into one HTML file for offline distribution	`pandoc input.md --css=style.css --self-contained -o output.html`
`--citeproc + --bibliography / --csl`	Enable citation processing with a bibliography and a CSL style; without them citations stay raw	`pandoc input.md --csl=ieee.csl -o output.pdf`

Common pitfalls

SymptomThe Word output uses default styles for headings and code blocks, losing the original layout.

CauseThe docx writer does not inherit external styles; it uses built-in defaults or a reference document.

FixExport a docx, restyle it, save it as a template, then pass --reference-doc=template.docx.

SymptomThe generated HTML has no styling and renders as a bare fragment in the browser.

CauseOnly a fragment was emitted, or the CSS is still linked externally and the file was not copied along.

FixAdd -s for a full document, and --self-contained --css=style.css for a single file.

SymptomChinese characters in the PDF come out blank or as boxes.

CauseThe default pdflatex engine has no support for system fonts or CJK text.

FixSwitch to --pdf-engine=xelatex and set -V mainfont="Noto Sans CJK SC".

SymptomCitations appear literally as [@key] and the reference list is empty.

Cause--citeproc was not enabled, or no bibliography file was supplied.

FixAdd --citeproc --bibliography=refs.bib and pick a style with --csl.

Troubleshooting

1Confirm which extensions this build supports
pandoc --list-extensions markdown
Parsing behaviour depends on the extension set, so check it before blaming your syntax.
2Export the default template as a starting point
pandoc -o template.html --print-default-template html5
Add your own blocks to that template and apply it with --template=mytemplate.html.
3Inspect how a source file is actually parsed
pandoc -f markdown -t plain
Plain text output immediately reveals whether headings, lists and tables were recognised.

Command Examples

One Markdown file into several formats

pandoc input.md -o output.html
pandoc input.md -o output.docx
pandoc input.md -o output.epub
pandoc -f markdown -t html5 input.md -o output.html

Formats are inferred from the extension by default, and -f/-t state them explicitly; the same works in reverse with pandoc input.html -o output.md.

Engine and font for a Chinese PDF

pandoc input.md -o output.pdf --pdf-engine=xelatex -V mainfont="Noto Sans CJK SC"
pandoc input.md -o output.pdf --toc --toc-depth=3 -V geometry:margin=1in

Engine and font must both be supplied, and -V feeds template variables, which is how margins and the table-of-contents depth are controlled.

A single-file HTML and a custom template

pandoc -s input.md -o output.html
pandoc input.md --css=style.css --self-contained -o output.html
pandoc input.md -H header.html -o output.html
pandoc -o template.html --print-default-template html5
pandoc input.md --template=mytemplate.html -o output.html

Start customising from the exported default template; -H injects a head fragment while --self-contained inlines the CSS.

Citations, math and extension self-check

pandoc input.md --bibliography=refs.bib --citeproc -o output.pdf
pandoc input.md --csl=ieee.csl --citeproc -o output.pdf
pandoc input.md --katex -o output.html
pandoc --list-extensions markdown

Bibliography, CSL style and citeproc all have to be present for citations to render; math can alternatively go through MathJax with --mathjax.

Common Pitfalls

Without -s / --standalone the output is only a fragment and the HTML has no head or body structure.
A Chinese PDF needs both --pdf-engine=xelatex and a CJK font; changing the engine alone still produces boxes.
When docx styles go missing, supply --reference-doc rather than fighting the Markdown source.
Citations render only when --citeproc, --bibliography and --csl are all present; missing any one leaves a literal [@key] behind.
Always quote the value in -V key=value, especially for titles and authors containing spaces, or the shell splits it into extra arguments.

Tips

Chinese PDFs must use the xelatex engine and a Chinese font, or text is garbled.
Markdown to Word may lose styles; convert to HTML first, then DOCX for better fidelity.
Run pandoc --list-output-formats to see all supported output formats.

FAQ

Why does the generated HTML look like a bare fragment?

Because -s is missing. By default pandoc emits only a document fragment with no head and no body wrapper; pandoc -s input.md -o output.html produces a standalone document. To inject your own head content, use pandoc input.md -H header.html -o output.html, and to carry the styling along with the file add --css=style.css --self-contained so the CSS is embedded into one portable file.

The Word output lost all the styling. How do I preserve it?

Because docx output targets Word style definitions rather than Markdown syntax. Pass --reference-doc=template.docx so pandoc reuses that document heading, body and code block styles; you can obtain such a template by saving a copy of an existing document. To edit the template itself, start from pandoc -o template.html --print-default-template html5, which dumps the built-in template, and then supply it with --template=mytemplate.html.

Chinese text turns into blanks or boxes in the PDF. What fixes it?

Check both the engine and the font. Use pandoc input.md -o output.pdf --pdf-engine=xelatex so the engine can reach system fonts, and name a font explicitly with -V mainfont="Noto Sans CJK SC". Switching the engine alone still yields boxes on a machine lacking that font. Layout values go through -V as well, for example -V geometry:margin=1in, and a table of contents comes from --toc with --toc-depth=3 to cap the nesting level.

Why do my citations come out as literal [@key] text?

Citation processing is off, or it is on but one of the bibliography and style files is missing. pandoc input.md --citeproc -o output.pdf turns processing on; then supply --bibliography=refs.bib for the BibTeX database and --csl=ieee.csl for the output style. Without both the citation is left untouched and the reference list stays empty. Before digging further, run pandoc --list-extensions markdown to confirm what your installed version actually supports.

Where should metadata live when one Markdown file feeds several formats?

Two ways. For a couple of values pass them inline with -V key=value, for example -V title="Title" -V author="Author"; once the list grows, keep it in a YAML file and point --metadata-file=meta.yaml at it so the command line stays short. Variables are only visible to the template, which is exactly why layout settings such as -V geometry:margin=1in travel the same route.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

Pandoc User Guide

Maintained by LaoHand

Publicly updated on Jul 21, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.