Pandoc

Pandoc

Convert Markdown (and other formats) to PDF, DOCX, HTML, LaTeX, and 40+ others. Always prefer Docker over a local install to avoid LaTeX dependency hell.

Docker Setup (Preferred)

The pandoc/extra image bundles pandoc + LaTeX (Tectonic) + Eisvogel template + Lua filters + open-source fonts. No local LaTeX required.

# One-shot conversion (run from the document directory)
docker run --rm \
  --volume "$(pwd):/data" \
  --user $(id -u):$(id -g) \
  pandoc/extra input.md -o output.pdf

# Convenient shell alias (add to ~/.bashrc or ~/.zshrc)
alias pandock='docker run --rm -v "$(pwd):/data" -u $(id -u):$(id -g) pandoc/extra'

# Then use as a drop-in replacement for pandoc
pandock input.md -o output.pdf --template eisvogel

Windows note: Replace $(id -u):$(id -g) with your UID or omit --user on Windows.

Core Conversion Patterns

PDF (recommended defaults)

# Plain PDF
pandock document.md -o document.pdf

# With TOC + numbered sections (most documents)
pandock document.md -o document.pdf --toc --number-sections

# Unicode / custom fonts → use XeLaTeX
pandock document.md -o document.pdf --pdf-engine=xelatex

# Academic paper with citations
pandock paper.md -o paper.pdf \
  --pdf-engine=pdflatex \
  --citeproc \
  --number-sections \
  --toc

DOCX (Word)

pandock document.md -o document.docx
pandock document.md -o document.docx --reference-doc=template.docx

HTML

pandock document.md -o document.html --standalone --toc
pandock document.md -o document.html --standalone --self-contained  # embed all resources

Mermaid Diagrams

Pandoc/LaTeX cannot render Mermaid syntax directly. Use the bundled scripts/mermaid.py to render ```mermaid blocks to images with the Mermaid CLI (mmdc), then let Pandoc embed them.

# 1. Install Mermaid CLI (requires Node.js + Chromium/Puppeteer)
npm install -g @mermaid-js/mermaid-cli

# 2. Render all mermaid blocks to PNGs and rewrite the markdown
python3 scripts/mermaid.py document.md -i -f png -s 3

# 3. Convert as usual (images are now referenced from markdown)
pandock document.md -o document.pdf

• Use -s 3 (3x scale) for crisp diagrams in PDF; -f svg for HTML/DOCX.
• --keep preserves the original Mermaid source as an HTML comment above each image.
• If Puppeteer/Chrome fails (Docker/CI sandbox errors), add -p assets/mermaid/puppeteer.json.
• Run with --dry-run to preview the replacements before rendering.
• Incremental by default: existing images are reused unless --force is passed.

Presentations

# Beamer (PDF slides)
pandock slides.md -o slides.pdf --to beamer

# reveal.js (web slides)
pandock slides.md -o slides.html --to revealjs --standalone -V theme=black

Eisvogel Template (Polished PDFs)

Eisvogel is already in pandoc/extra — no install needed with Docker.

pandock document.md -o document.pdf \
  --template eisvogel \
  --syntax-highlighting idiomatic

Minimal YAML frontmatter for Eisvogel:

---
title: "Document Title"
author: [Author Name]
date: "2026-01-01"
titlepage: true
titlepage-color: "1E4B7A"
titlepage-text-color: "FFFFFF"
toc: true
toc-own-page: true
---

For business proposals, see references/business_proposals.md for complete templates and best practices.

See references/eisvogel.md for the full list of Eisvogel variables.

Citations (BibTeX / CSL)

1. Add to YAML frontmatter:

   bibliography: references.bib
   csl: assets/csl/apa.csl   # or harvard.csl / ieee.csl
   link-citations: true
   

2. Cite in text: [@citekey] (parenthetical) or @citekey (in-text).

3. Add # References section at the end, or use :::{#refs}:::.

4. Convert with --citeproc:

   pandock paper.md -o paper.pdf --citeproc --number-sections
   

Bundled CSL files: assets/csl/apa.csl, assets/csl/harvard.csl, assets/csl/ieee.csl.

Validation

Run the bundled validation script before converting to catch YAML and dependency errors early:

python3 scripts/validate.py document.md

Defaults Files (Avoiding Long Commands)

For repeatable builds, define a defaults.yaml:

from: markdown
to: pdf
pdf-engine: pdflatex
citeproc: true
number-sections: true
toc: true
metadata:
  fontsize: 12pt
  geometry: margin=1in

pandock document.md --defaults=defaults.yaml -o output.pdf

Starter defaults files are in assets/templates/.

Batch Conversion

# Convert all .md files in a directory to PDF
for f in *.md; do
  pandock "$f" -o "${f%.md}.pdf" --pdf-engine=pdflatex
done

Local Install (Fallback)

Use only when Docker is unavailable.

# macOS
brew install pandoc && brew install --cask mactex

# Ubuntu/Debian
sudo apt-get install pandoc texlive-xetex texlive-fonts-recommended texlive-latex-extra

# Windows (Chocolatey)
choco install pandoc miktex

Minimum: Pandoc ≥ 2.19 (3.x recommended) + a LaTeX distribution for PDF output.

Bundled Resources

Reference Files

Load these when you need detailed information:

• references/conversion_guide.md — Format-specific commands and advanced options (filters, resource paths, metadata overrides, batch patterns)
• references/yaml_reference.md — Complete YAML frontmatter variable reference (all PDF, HTML, DOCX settings)
• references/templates_guide.md — How to use and customize each bundled template
• references/eisvogel.md — All Eisvogel template variables and custom title-page options
• references/docker.md — Docker image variants (pandoc/core, pandoc/latex, pandoc/extra), tagging, and CI/CD usage
• references/troubleshooting.md — Common errors with fixes (YAML syntax, missing LaTeX packages, fonts, images, Unicode)
• references/snippets.md — Copy-paste commands for common workflows
• references/business_proposals.md — Templates and best practices for business proposals (lists, diagrams, hierarchy, branding)