4 + Universal document converter — format conversion (Markdown, HTML, LaTeX, docx,
5 + PDF, EPUB, presentations), Lua filters, templates, citations, YAML metadata,
6 + and document pipelines. Use when converting between document formats, generating
7 + PDFs, extracting content, or programmatically transforming documents.
12 +Pandoc is a universal document converter. It reads many input formats, transforms them
13 +through an AST, and writes to many output formats. Agents use it primarily for:
14 +format conversion, PDF generation, content extraction, and document pipelines with Lua filters.
16 +**Version**: targets pandoc 3.x (tested on 3.6). Features like `--sandbox`, `--syntax-highlighting`,
17 +`--variable-json`, and the modern Table AST require pandoc ≥ 3.0.
19 +**Official docs**: <https://pandoc.org/MANUAL.html>
23 +##
Quick Reference: Essential Commands 27 +pandoc input.md -s -o output.html
30 +pandoc input.md -o output.pdf
33 +pandoc input.md -o output.docx
36 +pandoc input.md -o output.tex
39 +pandoc -f html -t markdown input.html -o output.md
42 +pandoc -f html -t markdown https://example.com -o page.md
45 +pandoc input.md -s --toc -N -o output.html
48 +pandoc ch1.md ch2.md ch3.md -s -o book.html
51 +echo "# Hello" | pandoc -f markdown -t html
54 +pandoc --list-input-formats
55 +pandoc --list-output-formats
60 +##
1. Format Conversion Matrix 62 +###
Input Formats (most useful for agents) 64 +| Format | Flag | Notes |
65 +|--------|------|-------|
66 +| Markdown (pandoc) | `markdown` | Default input; richest extensions |
67 +| GFM | `gfm` | GitHub-Flavored Markdown |
68 +| CommonMark | `commonmark` | Strict spec |
69 +| HTML | `html` | Parses web pages |
70 +| LaTeX | `latex` | Requires valid LaTeX |
71 +| Docx | `docx` | MS Word |
72 +| ODT | `odt` | LibreOffice |
73 +| EPUB | `epub` | E-books |
74 +| Org | `org` | Emacs Org mode |
75 +| RST | `rst` | reStructuredText |
76 +| Jupyter | `ipynb` | Notebooks |
77 +| CSV/TSV | `csv` / `tsv` | Tabular data |
78 +| Typst | `typst` | Modern typesetting |
79 +| Djot | `djot` | Lightweight markup |
81 +###
Output Formats (most useful for agents) 83 +| Format | Flag | Notes |
84 +|--------|------|-------|
85 +| HTML5 | `html` | Default output |
86 +| PDF | `pdf` | Via LaTeX/Typst/HTML engine |
87 +| LaTeX | `latex` | Intermediate for PDF |
88 +| Docx | `docx` | MS Word |
89 +| PPTX | `pptx` | PowerPoint presentations |
90 +| EPUB3 | `epub` | E-books |
91 +| Markdown | `markdown` | Pandoc's extended MD |
92 +| GFM | `gfm` | For GitHub |
93 +| Beamer | `beamer` | LaTeX slide shows |
94 +| reveal.js | `revealjs` | HTML slide shows |
95 +| Typst | `typst` | Modern typesetting |
96 +| Plain text | `plain` | Stripped formatting |
97 +| ANSI | `ansi` | Terminal output with colors |
98 +| Man page | `man` | Unix manual pages |
100 +###
Extension Syntax 102 +Enable/disable per-format extensions with `+EXTENSION` / `-EXTENSION`:
106 +pandoc -f markdown+emoji-footnotes input.md
109 +pandoc -f gfm+raw_html input.md
114 +##
2. PDF Generation 118 +| Engine | Flag | When to Use |
119 +|--------|------|-------------|
120 +| pdflatex | `--pdf-engine=pdflatex` | Default; fastest, Latin scripts |
121 +| xelatex | `--pdf-engine=xelatex` | CJK, Unicode fonts, system fonts |
122 +| lualatex | `--pdf-engine=lualatex` | Lua scripting, font fallbacks |
123 +| typst | `--pdf-engine=typst` | Fast, modern, no TeX needed |
124 +| weasyprint | `--pdf-engine=weasyprint` | HTML/CSS → PDF, no TeX |
125 +| context | `--pdf-engine=context` | ConTeXt engine |
127 +###
Common PDF Recipes 131 +pandoc doc.md -o doc.pdf
134 +pandoc doc.md --pdf-engine
=xelatex -V mainfont=
"Noto Sans CJK SC" -o doc.pdf
137 +pandoc doc.md -V geometry:margin=1in -o doc.pdf
140 +pandoc doc.md -V geometry:margin=1in -V classoption=twocolumn -V classoption=landscape -o doc.pdf
143 +pandoc doc.md -N --toc --toc-depth
=3 -o doc.pdf
146 +pandoc doc.md --pdf-engine
=typst -o doc.pdf
149 +pandoc doc.md -t html --css
=style.css --pdf-engine
=weasyprint -o doc.pdf
152 +pandoc doc.md -s -o debug.tex
155 +###
Key LaTeX Variables 157 +| Variable | Example | Effect |
158 +|----------|---------|--------|
159 +| `geometry` | `margin=1in` | Page margins |
160 +| `papersize` | `a4`, `letter` | Paper size |
161 +| `fontsize` | `12pt` | Body font size |
162 +| `documentclass` | `article`, `book`, `report` | LaTeX class |
163 +| `mainfont` | `"Noto Sans"` | Body font (xelatex/lualatex) |
164 +| `monofont` | `"JetBrains Mono"` | Code font |
165 +| `linestretch` | `1.5` | Line spacing |
166 +| `colorlinks` | `true` | Colored links instead of boxes |
167 +| `linkcolor` | `blue` | Link color |
168 +| `toc` | (flag) | Include TOC |
169 +| `toc-depth` | `3` | TOC heading depth |
170 +| `numbersections` | (flag) | Number sections |
178 +pandoc doc.md -s -o doc.html
181 +pandoc doc.md -s --embed-resources -o doc.html
184 +pandoc doc.md -s --css
=style.css -o doc.html
187 +pandoc doc.md -s --syntax-highlighting
=kate -o doc.html
190 +pandoc doc.md -s --section-divs -o doc.html
193 +pandoc doc.md -s --katex -o doc.html
196 +pandoc doc.md -s --mathjax -o doc.html
199 +pandoc doc.md -s -N -o doc.html
202 +pandoc doc.md -s --toc --toc-depth
=2 -o doc.html
207 +| Variable | Effect |
208 +|----------|--------|
209 +| `mainfont` | CSS font-family on html |
210 +| `fontsize` | Base font-size |
211 +| `monofont` | Code font-family |
212 +| `monobackgroundcolor` | Code background |
213 +| `linkcolor` | Link color |
214 +| `maxwidth` | Max content width (default 36em) |
215 +| `margin-left/right/top/bottom` | Body padding |
219 +##
4. Docx (Word) Output 223 +pandoc doc.md -o doc.docx
226 +pandoc doc.md --reference-doc
=template.docx -o doc.docx
229 +pandoc -o custom-reference.docx --print-default-data-file reference.docx
232 +pandoc input.docx --extract-media
=./images -t markdown -o output.md
235 +pandoc input.docx --track-changes
=accept -o output.md
238 +###
Reference Doc Styles 240 +When customizing `reference.docx`, modify these styles:
241 +Normal, Body Text, Title, Subtitle, Author, Date, Heading 1–9,
242 +Block Text, Source Code, Footnote Text, Caption, Table, Hyperlink.
248 +###
reveal.js (HTML Slides) 251 +pandoc slides.md -t revealjs -s -o slides.html
254 +pandoc slides.md -t revealjs -s -V revealjs-url=https://unpkg.com/reveal.js@^5 \
255 + -V theme=moon -o slides.html
258 +pandoc slides.md -t revealjs -s --embed-resources -o slides.html
261 +pandoc slides.md -t revealjs -s -i -o slides.html
264 +###
Beamer (PDF Slides) 267 +pandoc slides.md -t beamer -o slides.pdf
270 +pandoc slides.md -t beamer -V theme=metropolis -o slides.pdf
273 +pandoc slides.md -t beamer -V aspectratio=169 -o slides.pdf
278 +Slides are separated by headings. The `--slide-level` option controls which heading level creates slides:
281 +# Section Title <!-- creates a section divider -->
283 +## Slide Title <!-- creates a slide (if slide-level=2) -->
292 +Use horizontal rules `---` to force slide breaks when needed.
294 +###
PowerPoint (PPTX) 297 +pandoc slides.md -o slides.pptx
300 +pandoc slides.md --reference-doc
=template.pptx -o slides.pptx
307 +Lua filters modify the pandoc AST between parsing and writing. No external deps — Lua 5.4 is built into pandoc.
309 +###
Basic Filter Structure 312 +-- Save as myfilter.lua, use with: pandoc --lua-filter=myfilter.lua
314 + Str = function(elem)
315 + -- Transform inline text elements
318 + Para = function(elem)
319 + -- Transform paragraph blocks
327 +- `nil` → element unchanged
328 +- New element → replaces original (must be same type)
329 +- List of elements → spliced in place (empty list = delete)
331 +###
Global Variables Available 333 +| Variable | Description |
334 +|----------|-------------|
335 +| `FORMAT` | Output format name (`html`, `latex`, etc.) |
336 +| `PANDOC_VERSION` | Pandoc version as table `{major, minor, patch}` |
337 +| `PANDOC_READER_OPTIONS` | Reader options |
338 +| `PANDOC_WRITER_OPTIONS` | Writer options |
339 +| `PANDOC_SCRIPT_FILE` | Path to current filter file |
341 +###
Common Filter Patterns 344 +-- 1. Format-conditional logic
345 +if FORMAT:match 'html' then
346 + function Image(elem)
347 + elem.attributes.style = 'max-width:100%;'
352 +-- 2. Replace text with inline elements
354 + Str = function(elem)
355 + if elem.text == "{{date}}" then
356 + return pandoc.Str(os.date("%Y-%m-%d"))
361 +-- 3. Remove all links, keep text
363 + Link = function(el)
364 + return el.content -- unwrap link, keep inline content
368 +-- 4. Add class to all code blocks
370 + CodeBlock = function(el)
371 + table.insert(el.classes, "highlight")
376 +-- 5. Extract all headings (metadata → document)
377 +function Pandoc(doc)
378 + local headings = {}
379 + for _, el in ipairs(doc.blocks) do
380 + if el.t == "Header" then
381 + table.insert(headings, pandoc.Para(el.content))
384 + return pandoc.Pandoc(headings, doc.meta)
391 + if el.text:match("%P") then words = words + 1 end
393 + Pandoc = function(doc)
396 + if el.text:match("%P") then words = words + 1 end
399 + print(words .. " words in body")
404 +-- 7. Top-down traversal (process parents before children)
406 + traverse = 'topdown',
408 + if el.classes[1] == 'skip' then
409 + return el, false -- skip children
418 +Default is `typewise`: all Inlines → all Blocks → Meta → Pandoc.
419 +Set `traverse = 'topdown'` for depth-first parent-before-children.
421 +###
Useful Lua Modules (built-in) 425 +| `pandoc.utils` | `stringify`, `type`, `sha1`, `to_simple_table` |
426 +| `pandoc.text` | Unicode-aware `upper`, `lower`, `len` |
427 +| `pandoc.mediabag` | `insert`, `fetch`, `list` — manage binary assets |
428 +| `pandoc.system` | `with_temporary_directory`, `with_working_directory` |
429 +| `pandoc.layout` | Pretty-printing, text wrapping |
430 +| `pandoc.path` | Path manipulation (`directory`, `filename`, `join`) |
431 +| `lpeg` | Parsing Expression Grammars |
432 +| `re` | Regex-like pattern matching via lpeg |
434 +###
Running External Commands in Lua 437 +local output = pandoc.pipe("sed", {"-e", "s/foo/bar/"}, input_string)
440 +###
Multiple Filters 442 +Filters run in command-line order. Lua filters (`--lua-filter`) are faster than JSON filters (`--filter`):
445 +pandoc doc.md --lua-filter
=filter1.lua --lua-filter
=filter2.lua -o out.html
454 +title: "Document Title"
455 +author: "Author Name"
458 + This is the abstract.
459 + It can span multiple lines.
460 +keywords: [pandoc, markdown, conversion]
461 +subtitle: "A Subtitle"
463 +geometry: margin=1in
467 +numbersections: true
471 + \usepackage{cleveref}
476 +Content starts here.
479 +###
Setting Metadata from CLI 483 +pandoc doc.md -M title=
"My Title" -o out.html
486 +pandoc doc.md -M toc=true -o out.html
489 +pandoc doc.md --metadata-file
=meta.yaml -o out.html
492 +###
Template Variables vs Metadata 494 +- `-V` / `--variable` → template variables only (strings, not parsed as Markdown)
495 +- `-M` / `--metadata` → metadata (affects document, accessible in filters, parsed as Markdown)
501 +Templates control standalone output structure. Variables are interpolated with `$var$` syntax.
510 +pandoc doc.md --template
=mytemplate.html -o out.html
525 +${body} <!-- variable interpolation -->
526 +$if(foo)$ <!-- conditional -->
529 +$for(items)$ <!-- loop -->
530 +$sep$, $endfor$ <!-- separator -->
533 +###
Custom Templates Location 535 +Place in `$HOME/.local/share/pandoc/templates/default.FORMAT` to override defaults.
539 +##
9. Citations & Bibliography 543 +pandoc doc.md --citeproc -o out.html
546 +pandoc doc.md --citeproc --bibliography
=refs.bib -o out.html
549 +pandoc doc.md --citeproc --csl
=ieee.csl -o out.html
552 +###
Citation Syntax (in Markdown) 555 +See @smith2020 for details.
556 +Multiple: [@smith2020; @jones2019].
557 +Suppress author: [-@smith2020].
560 +###
YAML for Bibliography 564 +bibliography: refs.bib
565 +csl: https://www.zotero.org/styles/ieee
566 +nocite: "@*" # include all entries in bibliography
572 +##
10. Content Extraction & Processing 576 +pandoc input.docx --extract-media
=./media -t markdown -o output.md
579 +pandoc doc.md --lua-filter
=extract-headings.lua -t markdown
582 +pandoc -f html -t markdown https://example.com -o page.md
585 +pandoc doc.md -t json
| ./my-filter.py
| pandoc -f json -t html
588 +pandoc doc.md --lua-filter
=wordcount.lua
593 +##
11. Defaults Files 595 +Reusable YAML config files instead of long CLI commands:
606 +number-sections: true
608 + geometry: margin=1in
610 + documentclass: book
617 +pandoc --defaults
=pdf.yaml
620 +Place in `$HOME/.local/share/pandoc/defaults/` for global access by name.
624 +##
12. Common Agent Pipelines 626 +###
Web Page → Clean Markdown 629 +pandoc -f html -t markdown --wrap
=none \
630 + https://example.com -o page.md
633 +###
Markdown → Professional PDF Report 636 +pandoc report.md -o report.pdf \
637 + --pdf-engine
=xelatex \
638 + -V geometry:margin=1in \
640 + -V mainfont=
"TeX Gyre Pagella" \
641 + -V monofont=
"JetBrains Mono" \
642 + -V colorlinks=true \
643 + -V linkcolor=blue \
644 + --toc --toc-depth
=3 \
646 + --syntax-highlighting
=kate
649 +###
Docx → Markdown (with images) 653 + --extract-media
=./images \
658 +###
Notebook → HTML Report 661 +pandoc analysis.ipynb \
662 + -s --embed-resources \
664 + --syntax-highlighting
=tango \
668 +###
Batch Convert Directory 673 + pandoc
"$f" -s -o
"${f%.md}.html" 678 + pandoc
"$f" --pdf-engine
=xelatex -o
"${f%.md}.pdf" 682 +###
Combine Chapters into Book 685 +pandoc ch1.md ch2.md ch3.md metadata.yaml \
687 + --pdf-engine
=xelatex \
695 +pandoc doc.md -t json
| jq
'.blocks[0]' 698 +pandoc doc.md -t native
703 +##
13. Key CLI Options Reference 707 +| `-f` / `--from` | Input format |
708 +| `-t` / `--to` | Output format |
709 +| `-o` / `--output` | Output file |
710 +| `-s` / `--standalone` | Full document (header + footer) |
711 +| `--toc` | Table of contents |
712 +| `--toc-depth=N` | TOC depth (default 3) |
713 +| `-N` / `--number-sections` | Number sections |
714 +| `--lua-filter=FILE` | Apply Lua filter |
715 +| `--filter=PROG` | Apply JSON filter (external) |
716 +| `-M KEY=VAL` | Set metadata |
717 +| `-V KEY=VAL` | Set template variable |
718 +| `--metadata-file=FILE` | Load metadata from YAML |
719 +| `--template=FILE` | Custom template |
720 +| `--css=URL` | Link CSS (HTML/EPUB) |
721 +| `--embed-resources` | Inline all resources (HTML) |
722 +| `--extract-media=DIR` | Extract media to directory |
723 +| `--wrap=auto\|none\|preserve` | Text wrapping |
724 +| `--columns=N` | Line width (default 72) |
725 +| `--shift-heading-level-by=N` | Adjust heading levels |
726 +| `--reference-doc=FILE` | Style reference (docx/odt/pptx) |
727 +| `--pdf-engine=PROG` | PDF engine |
728 +| `--citeproc` | Process citations |
729 +| `--bibliography=FILE` | Bibliography file |
730 +| `-d` / `--defaults=FILE` | Defaults file |
731 +| `--sandbox` | Restrict file access |
732 +| `--syntax-highlighting=STYLE` | Highlighting style or `none` |
733 +| `-H` / `--include-in-header` | Include raw in header |
734 +| `-B` / `--include-before-body` | Include before body |
735 +| `-A` / `--include-after-body` | Include after body |
736 +| `--resource-path=PATH` | Search path for resources |
737 +| `--file-scope` | Parse files individually |
738 +| `--fail-if-warnings` | Exit on warnings |
748 +| 3 | Fail on warnings |
749 +| 5 | Template error |
750 +| 6 | Option error |
751 +| 21 | Unknown reader |
752 +| 22 | Unknown writer |
754 +| 47 | PDF engine not found |
755 +| 83 | Filter error |
760 +##
15. Helper Scripts 762 +See `scripts/` directory:
764 +- `pandoc-batch-convert.sh` — Batch convert files between formats
765 +- `pandoc-md-to-pdf.sh` — Markdown to polished PDF with sensible defaults
766 +- `pandoc-web-to-md.sh` — Fetch URL and convert to clean Markdown
767 +- `pandoc-wordcount.lua` — Count words in document body
769 +###
Lua Filter Library 771 +See `references/` directory:
773 +- `filters/strong-to-smallcaps.lua` — Convert **bold** to SMALL CAPS
774 +- `filters/center-images.lua` — Center images in HTML/LaTeX
775 +- `filters/meta-vars.lua` — Replace `%var%` placeholders with metadata values
776 +- `filters/extract-headings.lua` — Extract document outline
777 +- `filters/add-meta-date.lua` — Auto-set date metadata
778 +- `filters/remove-empty-paras.lua` — Strip empty paragraphs
784 +- **mdbook**: Building documentation books from Markdown
785 +- **presenterm**: Terminal-based presentations
786 +- **d2**: Diagram syntax used with pandoc preprocessing
787 +- **jq**: Processing pandoc JSON AST output