pandoc

What this skill does

# Pandoc Universal Document Converter Skill

Convert documents between 40+ formats with Pandoc. This skill covers Markdown to PDF/DOCX/HTML conversions, custom templates, citation management, and batch processing automation.

## When to Use This Skill

### USE When

- Converting Markdown to PDF with professional formatting
- Creating Word documents from Markdown sources
- Need reproducible document builds from plain text
- Managing academic papers with citations (BibTeX/CSL)
- Batch converting multiple documents
- Need custom templates for consistent branding
- Converting between multiple documentation formats
- Creating LaTeX documents from Markdown
- Need cross-references (figures, tables, equations)
- Building automated document pipelines

### DON'T USE When

- Building documentation websites (use MkDocs or Sphinx)
- Need interactive documentation (use web frameworks)
- Require real-time collaborative editing (use Google Docs)
- Building slide presentations (use Marp)
- Need WYSIWYG editing (use Word directly)
- Converting complex nested HTML (may lose formatting)

## Prerequisites

### Installation

```bash
# macOS (Homebrew)
brew install pandoc
brew install pandoc-crossref  # For cross-references
brew install basictex         # Minimal LaTeX for PDF
# Or full LaTeX: brew install --cask mactex

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install pandoc pandoc-citeproc
sudo apt-get install texlive-xetex texlive-fonts-recommended
sudo apt-get install texlive-latex-extra  # For additional packages

# Fedora/RHEL
sudo dnf install pandoc pandoc-citeproc
sudo dnf install texlive-xetex texlive-collection-fontsrecommended

# Windows (Chocolatey)
choco install pandoc
choco install miktex  # LaTeX distribution

# Windows (Scoop)
scoop install pandoc
scoop install latex

# Verify installation
pandoc --version
```

### System Requirements

- Pandoc 2.19 or higher (3.x recommended)
- LaTeX distribution (for PDF output)
- Python 3.8+ (for pandoc-filters)

## Core Capabilities

### 1. Basic Format Conversion

```bash
# Markdown to PDF
pandoc document.md -o document.pdf

# Markdown to DOCX
pandoc document.md -o document.docx

# Markdown to HTML
pandoc document.md -o document.html --standalone

# Markdown to LaTeX
pandoc document.md -o document.tex

# HTML to Markdown
pandoc page.html -o page.md

# DOCX to Markdown
pandoc document.docx -o document.md

# Multiple input files
pandoc chapter1.md chapter2.md chapter3.md -o book.pdf

# Specify input format explicitly
pandoc -f markdown -t pdf document.md -o document.pdf
```

### 2. PDF Generation with Options

```bash
# Basic PDF with table of contents
pandoc document.md -o document.pdf --toc

# PDF with XeLaTeX engine (better font support)
pandoc document.md -o document.pdf \
    --pdf-engine=xelatex \
    --toc \
    --toc-depth=3

# PDF with custom margins
pandoc document.md -o document.pdf \
    --pdf-engine=xelatex \
    -V geometry:margin=1in

# PDF with custom fonts
pandoc document.md -o document.pdf \
    --pdf-engine=xelatex \
    -V mainfont="Georgia" \
    -V sansfont="Helvetica" \
    -V monofont="Menlo"

# PDF with paper size and font size
pandoc document.md -o document.pdf \
    --pdf-engine=xelatex \
    -V papersize=a4 \
    -V fontsize=11pt

# PDF with numbered sections
pandoc document.md -o document.pdf \
    --number-sections \
    --toc

# PDF with syntax highlighting style
pandoc document.md -o document.pdf \
    --highlight-style=tango

# List available highlighting styles
pandoc --list-highlight-styles
```

### 3. Word Document (DOCX) Generation

```bash
# Basic DOCX
pandoc document.md -o document.docx

# DOCX with table of contents
pandoc document.md -o document.docx --toc

# DOCX with reference document (template)
pandoc document.md -o document.docx \
    --reference-doc=template.docx

# DOCX with syntax highlighting
pandoc document.md -o document.docx \
    --highlight-style=kate

# Creating a reference document template
pandoc --print-default-data-file reference.docx > template.docx
# Edit template.docx in Word to customize styles
```

### 4. HTML Generation

```bash
# Standalone HTML (includes head, body)
pandoc document.md -o document.html --standalone

# HTML with custom CSS
pandoc document.md -o document.html \
    --standalone \
    --css=styles.css

# HTML with embedded CSS
pandoc document.md -o document.html \
    --standalone \
    --css=styles.css \
    --embed-resources \
    --self-contained

# HTML with syntax highlighting
pandoc document.md -o document.html \
    --standalone \
    --highlight-style=pygments

# HTML with table of contents
pandoc document.md -o document.html \
    --standalone \
    --toc \
    --toc-depth=2

# HTML with math rendering (MathJax)
pandoc document.md -o document.html \
    --standalone \
    --mathjax

# HTML5 output
pandoc document.md -o document.html \
    --standalone \
    -t html5
```

### 5. Custom LaTeX Templates

```latex
%% template.tex - Custom Pandoc LaTeX template
\documentclass[$if(fontsize)$$fontsize$,$endif$$if(papersize)$$papersize$paper,$endif$]{article}

%% Packages
\usepackage{geometry}
\geometry{margin=1in}
\usepackage{fontspec}
\usepackage{hyperref}
\usepackage{fancyhdr}
\usepackage{titlesec}
\usepackage{xcolor}
\usepackage{listings}

%% Fonts
$if(mainfont)$
\setmainfont{$mainfont$}
$endif$
$if(sansfont)$
\setsansfont{$sansfont$}
$endif$
$if(monofont)$
\setmonofont{$monofont$}
$endif$

%% Colors
\definecolor{linkcolor}{RGB}{0, 102, 204}
\definecolor{codebackground}{RGB}{248, 248, 248}

%% Hyperlinks
\hypersetup{
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    pdfauthor={$author$},
    pdftitle={$title$}
}

%% Headers and footers
\pagestyle{fancy}
\fancyhf{}
\fancyhead[L]{$title$}
\fancyhead[R]{\thepage}
\renewcommand{\headrulewidth}{0.4pt}

%% Code blocks
\lstset{
    backgroundcolor=\color{codebackground},
    basicstyle=\ttfamily\small,
    breaklines=true,
    frame=single,
    numbers=left,
    numberstyle=\tiny\color{gray}
}

%% Section formatting
\titleformat{\section}
    {\Large\bfseries\color{linkcolor}}
    {\thesection}{1em}{}
\titleformat{\subsection}
    {\large\bfseries}
    {\thesubsection}{1em}{}

%% Title
$if(title)$
\title{$title$}
$endif$
$if(author)$
\author{$author$}
$endif$
$if(date)$
\date{$date$}
$endif$

\begin{document}

$if(title)$
\maketitle
$endif$

$if(abstract)$
\begin{abstract}
$abstract$
\end{abstract}
$endif$

$if(toc)$
\tableofcontents
\newpage
$endif$

$body$

\end{document}
```

```bash
# Use custom template
pandoc document.md -o document.pdf \
    --template=template.tex \
    --pdf-engine=xelatex \
    -V title="My Document" \
    -V author="Your Name" \
    -V date="2026-01-17" \
    --toc
```

### 6. YAML Metadata in Documents

```markdown
---
title: "Technical Report"
author:
  - name: "John Smith"
    affiliation: "University of Example"
    email: "[email protected]"
  - name: "Jane Doe"
    affiliation: "Tech Corp"
date: "January 17, 2026"
abstract: |
  This document demonstrates advanced Pandoc features
  including custom metadata, citations, and formatting.
keywords:
  - documentation
  - pandoc
  - markdown
lang: en-US
toc: true
toc-depth: 3
numbersections: true
geometry: margin=1in
fontsize: 11pt
mainfont: "Georgia"
monofont: "Fira Code"
linkcolor: blue
bibliography: references.bib
csl: ieee.csl
---

# Introduction

Your document content starts here...
```

### 7. Citations and Bibliography

```bibtex
%% references.bib
@article{smith2024,
    author = {Smith, John and Doe, Jane},
    title = {Advanced Documentation Techniques},
    journal = {Journal of Technical Writing},
    year = {2024},
    volume = {15},
    number = {3},
    pages = {42--58},
    doi = {10.1234/jtw.2024.001}
}

@book{johnson2023,
    author = {Johnson, Robert},
    title = {The Complete Guide to Markdown},
    publisher = {Tech Press},
    year = {2023},
    address = {New York},
    isbn = {978-0-123456-78-9}
}

@inproceedings{williams2025,
    author = {Williams, Sarah},