Pandoc CLI options cheatsheet (with extra focus on Markdown).
---
title: Pandoc cheatsheet
subtitle: 'Pandoc CLI options cheatsheet (with extra focus on Markdown)'
author: Jon LaBelle
date: March 4, 2026
source: https://pandoc.org/MANUAL.html
notoc: false
---
This is a “one stop” option map you can skim. Pandoc’s option set varies a bit by version, so for _your_ exact build also check: `pandoc --version` and `pandoc --help`. The option names, behaviors, and many details below are from the official Pandoc User’s Guide / manpage.
---
## Table of contents
- [Golden patterns](#golden-patterns)
- [Markdown focus](#markdown-focus)
- [Markdown flavors (input/output)](#markdown-flavors-inputoutput)
- [Markdown extensions (`+EXTENSION` / `-EXTENSION`)](#markdown-extensions-extension---extension)
- [Markdown-reader knobs](#markdown-reader-knobs)
- [Markdown-writer knobs](#markdown-writer-knobs)
- [All core options (grouped)](#all-core-options-grouped)
- [General / discovery](#general--discovery)
- [Input/output + defaults](#inputoutput--defaults)
- [Transforms (filters)](#transforms-filters)
- [Metadata + templates](#metadata--templates)
- [Output formatting controls](#output-formatting-controls)
- [Includes, resources, HTTP](#includes-resources-http)
- [Writer-specific knobs](#writer-specific-knobs)
- [EPUB + chunked HTML](#epub--chunked-html)
- [PDF generation](#pdf-generation)
- [Citations](#citations)
- [HTML math rendering](#html-math-rendering)
- [Wrapper-script helpers](#wrapper-script-helpers)
- [Deprecated / legacy aliases](#deprecated--legacy-aliases)
- [Example command cookbook](#example-command-cookbook)
---
## Golden patterns
```bash
# Convert file(s) from one format to another
pandoc -f <inputfmt> -t <outputfmt> input.md -o output.html
# Let pandoc infer formats by extension
pandoc input.md -o output.pdf
# Chain multiple inputs (concatenated by default)
pandoc chap1.md chap2.md -o book.html
# Put common options in a defaults file (YAML/JSON)
pandoc -d letter -o out.pdf in.md
```
Pandoc supports explicit `--from/--to` format selection and can list supported formats and extensions.
---
## Markdown focus
### Markdown flavors (input/output)
Use these with `-f/--from` and `-t/--to`:
- `markdown` — Pandoc’s extended Markdown
- `gfm` — GitHub-Flavored Markdown (and `markdown_github` is deprecated/less accurate)
- `commonmark` / `commonmark_x` — CommonMark, with/without extensions
- `markdown_strict` — original, unextended Markdown
- `markdown_mmd` — MultiMarkdown
- `markdown_phpextra` — PHP Markdown Extra
- `markua` — Markua
- (and many non-Markdown formats too)
Quick picks:
- Target GitHub READMEs/issues → `-t gfm`
- Want predictable CommonMark compliance → `-t commonmark` (or `commonmark_x`)
- Want Pandoc’s richest Markdown features → `-t markdown`
### Markdown extensions (`+EXTENSION` / `-EXTENSION`)
Pandoc lets you toggle extensions right inside the format string:
```bash
pandoc -f markdown+hard_line_breaks -t gfm ...
pandoc -f gfm-emoji -t markdown+tex_math_dollars ...
```
That `FORMAT+EXTENSION` (or `FORMAT-EXTENSION`) syntax is the key to “Markdown options” in Pandoc.
**List extensions and their defaults:**
```bash
pandoc --list-extensions=markdown
pandoc --list-extensions=gfm
```
### Markdown-reader knobs
These are options that matter a lot when **reading** Markdown (or producing AST from it):
- `--abbreviations=FILE` — load an abbreviations list (used by the Markdown reader).
- `--strip-comments[=true|false]` — strip HTML comments in Markdown/Textile instead of passing them through.
- `-p/--preserve-tabs` + `--tab-stop=NUM` — control tab handling while parsing.
- `--default-image-extension=EXT` — treat image paths without extensions as having EXT (Markdown/LaTeX readers).
- `--file-scope` — parse each file independently (important for multifile Markdown footnotes/IDs).
**YAML metadata blocks (Markdown-specific workflow):**
- `--metadata-file=FILE` can load YAML/JSON metadata; string scalars in the metadata file are parsed as Markdown.
- When writing _Markdown output_, a YAML metadata block is only produced if you use `-s/--standalone`.
### Markdown-writer knobs
These matter a lot when **writing** Markdown:
- `--reference-links` — write reference-style links (instead of inline).
- `--reference-location=block|section|document` — where link refs + footnotes land (especially useful for long docs).
- `--markdown-headings=setext|atx` — control heading style for level 1–2 in Markdown output.
- `--wrap=auto|none|preserve` + `--columns=NUM` — control how the generated Markdown source wraps.
- `--ascii` — emit ASCII-only entities where supported (Markdown/gfm/CommonMark included).
---
## All core options (grouped)
### General / discovery
- `--help` / `-h` — usage help
- `--version` / `-v` — version info
- `--verbose` / `--quiet` — verbosity level
- `--fail-if-warnings[=true|false]` — nonzero exit on warnings
- `--log=FILE` — JSON log output
- `--bash-completion` — generate bash completion script
- `--list-input-formats` / `--list-output-formats`
- `--list-extensions[=FORMAT]`
- `--list-highlight-languages` / `--list-highlight-styles`
### Input/output + defaults
- `-f FORMAT`, `-r FORMAT`, `--from=FORMAT`, `--read=FORMAT` — set input format (supports `FORMAT+EXT/-EXT`)
- `-t FORMAT`, `-w FORMAT`, `--to=FORMAT`, `--write=FORMAT` — set output format (also supports extensions)
- `-o FILE`, `--output=FILE` — output file (`-` for stdout; special behavior for `chunkedhtml`)
- `--data-dir=DIRECTORY` — pandoc user data dir override
- `-d FILE`, `--defaults=FILE` — load YAML/JSON defaults file(s)
### Transforms (filters)
- `-F PROGRAM`, `--filter=PROGRAM` — JSON filter (reads/writes Pandoc JSON)
- `-L SCRIPT`, `--lua-filter=SCRIPT` — Lua filter(s), applied in CLI order
### Metadata + templates
- `-M KEY[=VAL]`, `--metadata=KEY[:VAL]` — set document metadata (template variables too)
- `--metadata-file=FILE` — load YAML/JSON metadata file; string scalars parsed as Markdown
- `-s`, `--standalone` — emit full document (header/footer); affects Markdown YAML block emission
- `--template=FILE|URL` — custom template (implies standalone)
- `-V KEY[=VAL]`, `--variable=KEY[=VAL]` — set template variables
- `--variable-json=KEY=JSON` — set template variable with structured JSON
- `-D FORMAT`, `--print-default-template=FORMAT` — print system default template
- `--print-default-data-file=FILE` — print bundled data file (templates/refs/etc)
### Output formatting controls
- `--eol=crlf|lf|native` — line endings
- `--dpi=NUMBER` — default DPI for pixel↔physical conversion
- `--wrap=auto|none|preserve` — wrap generated source
- `--columns=NUMBER` — wrap width + affects plain table layout
- `--toc` / `--table-of-contents` — TOC (needs standalone)
- `--toc-depth=NUMBER` — TOC depth
- `--lof` / `--list-of-figures` — list of figures (standalone; limited formats)
- `--lot` / `--list-of-tables` — list of tables (standalone; limited formats)
- `--strip-comments[=true|false]` — strip HTML comments in Markdown/Textile source
- `--syntax-highlighting=default|none|idiomatic|STYLE|FILE` — highlighting method/style
- `--syntax-definition=FILE` — add KDE syntax definition(s)
- `--print-highlight-style=STYLE|FILE` — emit JSON theme
### Includes, resources, HTTP
- `-H FILE|URL`, `--include-in-header=...` — inject into header (implies standalone)
- `-B FILE|URL`, `--include-before-body=...` — inject at start of body (implies standalone)
- `-A FILE|URL`, `--include-after-body=...` — inject at end of body (implies standalone)
- `--resource-path=SEARCHPATH` — where to look for images/resources
- `--request-header=NAME:VAL` — custom HTTP header for fetching URLs/resources
- `--no-check-certificate[=true|false]` — disable TLS cert verification
- `--extract-media=DIR|FILE.zip` — extract embedded/linked media + rewrite refs
- `--sandbox[=true|false]` — restrict file/network access (useful for untrusted inputs)
### Writer-specific knobs
- `--embed-resources[=true|false]` — make HTML self-contained with data URIs (HTML outputs)
- `--self-contained[=true|false]` — deprecated synonym for `--embed-resources --standalone`
- `--link-images[=true|false]` — link images instead of embedding (ODT)
- `--html-q-tags[=true|false]` — use `<q>` tags for quotes (HTML; needs `smart`)
- `--ascii[=true|false]` — ASCII-only output where supported (incl. Markdown/gfm)
- `--reference-links[=true|false]` — reference-style links (Markdown/RST)
- `--reference-location=block|section|document` — where to place refs/footnotes
- `--markdown-headings=setext|atx` — Setext vs ATX for H1/H2 in Markdown output
- `--figure-caption-position=above|below` (HTML/LaTeX/Docx/ODT/Typst)
- `--table-caption-position=above|below` (HTML/LaTeX/Docx/ODT/Typst)
- `--list-tables[=true|false]` — render RST tables as list-tables
- `--top-level-division=default|section|chapter|part` — heading→division mapping (LaTeX/ConTeXt/DocBook/TEI/Docx behavior)
- `-N`, `--number-sections[=true|false]` — number headings (many formats)
- `--number-offset=NUM,NUM,...` — offset heading numbers (implies numbering; limited formats)
- `-i`, `--incremental[=true|false]` — incremental bullets (slides)
- `--slide-level=NUMBER` — which heading level splits slides
- `--section-divs[=true|false]` — wrap HTML sections in `<section>/<div>`
- `--email-obfuscation=none|javascript|references` — HTML mailto obfuscation
- `--id-prefix=STRING` — prefix generated IDs/internal links (HTML/DocBook; also affects footnote numbers in some outputs)
- `-T STRING`, `--title-prefix=STRING` — prefix HTML `<title>` (implies standalone)
- `-c URL`, `--css=URL` — link CSS (HTML/EPUB; repeatable)
- `--reference-doc=FILE|URL` — style reference for docx/odt/pptx
- `--ipynb-output=all|none|best` — how notebook output cells are preserved
### EPUB + chunked HTML
- `--split-level=NUMBER` — heading level to split EPUB / `chunkedhtml` into files
- `--chunk-template=PATHTEMPLATE` — filename template for `chunkedhtml` chunks
- `--epub-chapter-level=NUMBER` — deprecated synonym for `--split-level`
- `--epub-cover-image=FILE` — cover image
- `--epub-title-page=true|false` — include title page
- `--epub-metadata=FILE` — Dublin Core metadata XML
- `--epub-embed-font=FILE` — embed fonts
- `--epub-subdirectory=DIRNAME` — EPUB container subdir name
### PDF generation
- `--pdf-engine=PROGRAM` — engine used to produce PDFs (LaTeX, Typst, HTML engines, roff, etc.)
- `--pdf-engine-opt=STRING` — pass option through to PDF engine (repeatable)
### Citations
- `-C`, `--citeproc` — run built-in citeproc (renders citations + bibliography)
- `--bibliography=FILE` — bibliography file(s)
- `--csl=FILE` — CSL style file
- `--citation-abbreviations=FILE` — abbreviation JSON
- `--natbib` — use natbib in LaTeX output (not with `--citeproc`/PDF)
- `--biblatex` — use biblatex in LaTeX output (not with `--citeproc`/PDF)
### HTML math rendering
- `--mathjax[=URL]` — MathJax
- `--mathml` — MathML
- `--webtex[=URL]` — web TeX image service
- `--katex[=URL]` — KaTeX
- `--gladtex` — GladTeX `<eq>` tags workflow
### Wrapper-script helpers
- `--dump-args[=true|false]` — print parsed args info then exit
- `--ignore-args[=true|false]` — ignore args after `--` separator (wrapper usage)
### Deprecated / legacy aliases
These still show up in docs/help, but prefer the newer forms:
- `--self-contained` (deprecated) → use `--embed-resources --standalone`
- `--no-highlight` (deprecated) → use `--syntax-highlighting=none`
- `--highlight-style=...` (deprecated) → use `--syntax-highlighting=...`
- `--listings` (deprecated) → prefer `--syntax-highlighting=idiomatic|default` approaches
- `--epub-chapter-level` (deprecated) → use `--split-level`
- `--base-header-level` (deprecated) → use `--shift-heading-level-by`
---
## Example command cookbook
### 1) Markdown → HTML (standalone, TOC, embed resources)
```bash
pandoc -f markdown -t html -s --toc --embed-resources \
-o site.html README.md
```
(TOC requires standalone; embed-resources is HTML-only.)
### 2) Markdown → GitHub Flavored Markdown (reference links, Setext headings)
```bash
pandoc -f markdown -t gfm \
--reference-links --reference-location=document \
--markdown-headings=setext \
-o out.md in.md
```
### 3) CommonMark with a couple extension toggles
```bash
pandoc -f commonmark_x-raw_html+attributes -t commonmark_x \
-o out.md in.md
```
(Extension toggling uses `FORMAT+EXTENSION` / `FORMAT-EXTENSION`.)
### 4) Multi-file Markdown book with shared metadata
```bash
pandoc metadata.yaml chap1.md chap2.md chap3.md \
-s -o book.html
```
(YAML metadata blocks can be separate; `--metadata-file` is another approach.)
### 5) Markdown → PDF with a chosen engine + engine options
```bash
pandoc doc.md -o doc.pdf \
--pdf-engine=lualatex \
--pdf-engine-opt=-interaction=nonstopmode
```
### 6) Markdown with citations via citeproc
```bash
pandoc paper.md -o paper.html \
--citeproc --bibliography=refs.bib --csl=ieee.csl
```
### 7) DOCX → Markdown + extract all media
```bash
pandoc -f docx -t markdown \
--extract-media=media \
-o out.md in.docx
```
### 8) Chunked HTML (zip) split at H2, custom filenames
```bash
pandoc -t chunkedhtml --split-level=2 \
--chunk-template="section-%s-%i.html" \
-o site.zip book.md
```