Pandoc Skill

Universal document converter — transforms content between 40+ formats while preserving structure, metadata, and styling.

When to Use

• Convert Markdown → DOCX, PDF, HTML, EPUB, PPTX, or slides
• Convert DOCX/HTML → Markdown (for ingestion into repos or KBs)
• Batch-convert multiple files in one pass
• Generate professional reports with custom templates
• Build reveal.js slide decks from Markdown
• Extract structured content from HTML or EPUB
• Apply Lua filters for custom transformations (citation rewriting, heading renumbering, metadata injection)
• Produce camera-ready LaTeX or PDF from Markdown drafts

Core Commands

# Markdown → Word
pandoc input.md -o output.docx

# Markdown → PDF (requires LaTeX engine)
pandoc input.md -o output.pdf --pdf-engine=lualatex

# Markdown → PDF (no LaTeX — use HTML intermediate)
pandoc input.md -t html5 -o output.pdf --pdf-engine=wkhtmltopdf

# Markdown → reveal.js slides
pandoc slides.md -t revealjs -s -o slides.html

# Markdown → PowerPoint
pandoc input.md -o output.pptx

# Markdown → EPUB
pandoc input.md --metadata title="My Book" -o output.epub

# Word → Markdown (for repo ingestion)
pandoc input.docx -t markdown -o output.md

# HTML → Markdown
pandoc input.html -t markdown -o output.md

# CSV → HTML table
pandoc input.csv -f csv -t html -o table.html

# With custom template
pandoc input.md --template=template.tex -o output.pdf

# With Lua filter
pandoc input.md --lua-filter=filter.lua -o output.docx

# Batch convert (all .md in directory)
for f in *.md; do pandoc "$f" -o "${f%.md}.docx"; done

Workflow

1. Identify source and target formats — determine the conversion path.
2. Check if extras are needed:
   • PDF output → needs a LaTeX engine (lualatex, xelatex) or wkhtmltopdf
   • Styled DOCX → use --reference-doc=reference.docx
   • Slides → choose revealjs (HTML) or pptx (PowerPoint)
   • Citations → use --citeproc with a .bib file
3. Run the conversion — use the simplest command that achieves the goal.
4. Verify output:
   • For DOCX/PPTX: open or use the doc/pptx skill for visual QA
   • For PDF: use the pdf skill to render pages and inspect
   • For HTML: open in browser or use agent-browser skill
5. Iterate — adjust metadata, templates, or filters as needed.
6. Clean up — remove intermediate files.

Key Options

Flag	Purpose
-f FORMAT	Input format (auto-detected from extension if omitted)
-t FORMAT	Output format (auto-detected from extension if omitted)
-s / --standalone	Produce complete document (not fragment)
--template=FILE	Custom template for output
--reference-doc=FILE	Style reference for DOCX/PPTX output
--pdf-engine=ENGINE	PDF engine: lualatex, xelatex, wkhtmltopdf, weasyprint
--toc	Generate table of contents
--number-sections	Number headings
--metadata KEY=VAL	Set metadata (title, author, date)
--lua-filter=FILE	Apply Lua filter for custom transforms
--citeproc	Process citations from bibliography
--bibliography=FILE	BibTeX/CSL JSON bibliography
--highlight-style=STYLE	Code syntax highlighting theme
--columns=N	Line wrap width for plain text output
--wrap=none	No line wrapping (useful for Markdown output)
--extract-media=DIR	Extract images to directory

YAML Metadata Block

Place at the top of Markdown files for rich output:

---
title: "Document Title"
author: "Author Name"
date: 2026-05-16
abstract: "Brief summary"
lang: en
toc: true
number-sections: true
geometry: margin=1in
fontsize: 12pt
---

Lua Filters (Advanced)

Pandoc supports Lua scripting for custom transformations. Save as .lua:

-- uppercase-headings.lua — capitalize all headings
function Header(el)
  el.content = pandoc.walk_inline(el.content, {
    Str = function(s) return pandoc.Str(s.text:upper()) end
  })
  return el
end

Use with: pandoc input.md --lua-filter=uppercase-headings.lua -o output.docx

Temp and Output Conventions

• Intermediate files: tmp/pandoc/ — delete when done
• Final deliverables: output/pandoc/ or alongside source file
• Templates: store in ~/.pandoc/templates/ or project-local templates/
• Lua filters: store in ~/.pandoc/filters/ or project-local filters/

Dependencies

Pandoc is installed via the system package manager (brew install pandoc on macOS, apt install pandoc on Linux).

For PDF output, one of:

# LaTeX (full — large install ~4GB)
brew install --cask mactex

# LaTeX (minimal — recommended)
brew install basictex
# then: sudo tlmgr install collection-fontsrecommended

# No LaTeX alternative
brew install wkhtmltopdf
# or: pip install weasyprint

Format Quick Reference

Input	Best Output Targets
Markdown	docx, pdf, html, epub, pptx, revealjs, latex
DOCX	markdown, html, plain
HTML	markdown, docx, epub, pdf
LaTeX	pdf, html, docx
CSV	html (tables), markdown
EPUB	markdown, html, docx
Org-mode	markdown, html, docx, pdf
RST	markdown, html, docx, pdf

Integration with Other Skills

• doc/docx skill — use pandoc to generate DOCX, then doc skill for visual QA
• pdf skill — use pandoc for PDF generation, then pdf skill to render and verify
• pptx skill — use pandoc for slide generation, then pptx skill for refinement
• deep-research — convert research outputs to polished deliverables
• hyperframes — convert Markdown scripts to HTML for video compositions