gh-cadrianmae-claude-marketplace-plugins-pandoc/skills/pandoc/references/conversion_guide.md

Pandoc Conversion Guide

Format-specific conversion instructions and best practices.

PDF Conversion

Basic PDF

pandoc document.md -o document.pdf

With Smart Defaults

pandoc document.md -o document.pdf \
    --pdf-engine=pdflatex \
    --number-sections

PDF Engines

pdflatex (default)

• Fast, widely available
• ASCII-only (no Unicode support)
• Good for most documents

pandoc doc.md -o doc.pdf --pdf-engine=pdflatex

XeLaTeX

• Unicode support
• Custom fonts
• Slightly slower

pandoc doc.md -o doc.pdf --pdf-engine=xelatex

LuaLaTeX

• Modern, full Unicode
• Advanced typography
• Slowest option

pandoc doc.md -o doc.pdf --pdf-engine=lualatex

With Citations

pandoc paper.md -o paper.pdf \
    --pdf-engine=pdflatex \
    --citeproc \
    --number-sections

Custom Margins

pandoc doc.md -o doc.pdf \
    -V geometry:margin=1.5in

Table of Contents

pandoc doc.md -o doc.pdf \
    --toc \
    --toc-depth=3

Custom Template

pandoc doc.md -o doc.pdf \
    --template=custom.tex

HTML Conversion

Standalone HTML

pandoc doc.md -o doc.html --standalone

Self-Contained (Embed Resources)

pandoc doc.md -o doc.html \
    --standalone \
    --self-contained

With Table of Contents

pandoc doc.md -o doc.html \
    --standalone \
    --toc \
    --toc-depth=3

Custom CSS

pandoc doc.md -o doc.html \
    --standalone \
    --css=style.css

Syntax Highlighting

pandoc doc.md -o doc.html \
    --standalone \
    --highlight-style=tango

Available highlight styles:

• tango (default)
• pygments
• kate
• monochrome
• espresso
• zenburn
• haddock
• breezedark

Fragment (No HTML/Body Tags)

pandoc doc.md -o fragment.html
# No --standalone flag

DOCX Conversion

Basic DOCX

pandoc doc.md -o doc.docx

With Reference Template

pandoc doc.md -o doc.docx \
    --reference-doc=template.docx

With Citations

pandoc paper.md -o paper.docx \
    --citeproc

Preserve Formatting

pandoc doc.md -o doc.docx \
    --standalone

Presentation Conversion

Beamer (PDF Slides)

Basic:

pandoc slides.md -o slides.pdf --to beamer

With Theme:

---
title: "Presentation"
author: "Name"
theme: Madrid
colortheme: default
---

pandoc slides.md -o slides.pdf --to beamer

Slide Breaks:

# Section Title

## Slide 1

Content

## Slide 2

More content

reveal.js (Web Slides)

Basic:

pandoc slides.md -o slides.html \
    --to revealjs \
    --standalone

With Theme:

pandoc slides.md -o slides.html \
    --to revealjs \
    --standalone \
    -V theme=black \
    -V transition=slide

Available Themes:

• black (default)
• white
• league
• beige
• sky
• night
• serif
• simple
• solarized

Custom Background:

## Slide Title {background-color="#2E3440"}

Content

Two Columns:

::::: {.columns}

:::: {.column width="50%"}
Left content
::::

:::: {.column width="50%"}
Right content
::::

:::::

Advanced Options

Metadata Override

pandoc doc.md -o doc.pdf \
    -M title="New Title" \
    -M author="Author Name"

Include Files

pandoc doc.md -o doc.pdf \
    --include-before-body=header.tex \
    --include-after-body=footer.tex

Filters

pandoc doc.md -o doc.pdf \
    --filter pandoc-citeproc \
    --lua-filter=custom.lua

Resource Path

pandoc doc.md -o doc.pdf \
    --resource-path=.:images:assets

Variables

pandoc doc.md -o doc.pdf \
    -V documentclass=report \
    -V fontsize=12pt \
    -V geometry:margin=1in

Defaults Files

Instead of long command lines, use defaults files:

Create defaults file:

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

Use defaults:

pandoc doc.md --defaults=defaults.yaml -o doc.pdf

Batch Conversion

Convert All MD Files

for file in *.md; do
    pandoc "$file" -o "${file%.md}.pdf" --pdf-engine=pdflatex
done

With Validation

PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"

for file in *.md; do
    if python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" "$file"; then
        pandoc "$file" -o "${file%.md}.pdf"
    fi
done

Format Detection

Pandoc auto-detects formats from extensions:

Extension	Format
.md, .markdown	Markdown
.pdf	PDF
.html, .htm	HTML
.docx	DOCX
.tex	LaTeX
.epub	EPUB
.rst	reStructuredText
.org	Org-mode

Override with --from and --to:

pandoc input.txt --from markdown --to html -o output.html

Common Patterns

Academic Paper

pandoc paper.md -o paper.pdf \
    --pdf-engine=pdflatex \
    --citeproc \
    --number-sections \
    --toc \
    --toc-depth=3

Web Article

pandoc article.md -o article.html \
    --standalone \
    --self-contained \
    --toc \
    --css=style.css \
    --highlight-style=tango

Presentation

pandoc slides.md -o slides.html \
    --to revealjs \
    --standalone \
    -V theme=black \
    -V transition=slide

Book/Thesis

pandoc thesis.md -o thesis.pdf \
    --pdf-engine=xelatex \
    --citeproc \
    --number-sections \
    --toc \
    --toc-depth=4 \
    -V documentclass=book \
    -V fontsize=12pt \
    -V geometry:margin=1in

Performance Tips

1. Use pdflatex for speed - Switch to xelatex only if needed
2. Cache intermediate files - Use --standalone wisely
3. Batch similar conversions - Reuse pandoc process
4. Optimize images - Compress before embedding
5. Use defaults files - Faster than parsing long command lines