Pandoc Document Conversion Skill

Convert documents between formats using pandoc, the universal document converter.

Prerequisites

Check if pandoc is installed

pandoc --version

Install via Homebrew if needed

brew install pandoc

Common Conversions

Markdown to Word (.docx)

Basic conversion

pandoc input.md -o output.docx

With table of contents

pandoc input.md --toc -o output.docx

With custom reference doc (for styling)

pandoc input.md --reference-doc=template.docx -o output.docx

Standalone with metadata

pandoc input.md -s --metadata title="Document Title" -o output.docx

Markdown to PDF

Requires LaTeX - install one of:

brew install --cask basictex # Smaller (~100MB)

brew install --cask mactex-no-gui # Full (~4GB)

After install: eval "$(/usr/libexec/path_helper)" or new terminal

Basic conversion (uses pdflatex)

pandoc input.md -o output.pdf

With table of contents and custom margins

pandoc input.md -s --toc --toc-depth=2 -V geometry:margin=1in -o output.pdf

Using xelatex (better Unicode support - box drawings, arrows, etc.)

export PATH="/Library/TeX/texbin:$PATH" pandoc input.md --pdf-engine=xelatex -V geometry:margin=1in -o output.pdf

PDF Engine Selection:

Engine Use When

pdflatex

Default, ASCII content only

xelatex

Unicode characters (arrows, box-drawing, emojis)

lualatex

Complex typography, OpenType fonts

Markdown to HTML

Critical: Always use -f gfm (GitHub Flavored Markdown) for proper line break and list handling. Standard markdown collapses consecutive lines into paragraphs.

RECOMMENDED: GitHub Flavored Markdown with full styling

pandoc -f gfm -s -H <(cat << 'STYLE' <style> body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;max-width:800px;margin:0 auto;padding:2em;line-height:1.6} h1{border-bottom:2px solid #333;padding-bottom:0.3em} h2{border-bottom:1px solid #ccc;padding-bottom:0.2em;margin-top:1.5em} h3{margin-top:1.2em} ul,ol{margin:0.5em 0 0.5em 1.5em;padding-left:1em} ul{list-style-type:disc}ol{list-style-type:decimal} li{margin:0.3em 0}ul ul,ol ul{list-style-type:circle;margin:0.2em 0 0.2em 1em} table{border-collapse:collapse;width:100%;margin:1em 0} th,td{border:1px solid #ddd;padding:8px;text-align:left} th{background-color:#f5f5f5} code{background-color:#f4f4f4;padding:2px 6px;border-radius:3px} pre{background-color:#f4f4f4;padding:1em;overflow-x:auto;border-radius:5px} blockquote{border-left:4px solid #ddd;margin:1em 0;padding-left:1em;color:#666} </style> STYLE ) input.md -o output.html

Quick version (minimal styling)

pandoc -f gfm -s input.md -o output.html

With hard line breaks (newlines become <br>)

pandoc -f markdown+hard_line_breaks -s input.md -o output.html

Self-contained (embeds images/CSS)

pandoc -f gfm -s --embed-resources --standalone input.md -o output.html

Format Options:

Option Use When

-f gfm

Default choice - handles lists, line breaks, tables correctly

-f markdown+hard_line_breaks

Force all newlines to become <br>

-f commonmark

Strict CommonMark compliance

HTML for Print-to-PDF (No LaTeX Required)

When LaTeX isn't available, create styled HTML and print to PDF from browser:

Create inline CSS file

cat > /tmp/print-style.css << 'EOF' body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 800px; margin: 0 auto; padding: 2em; line-height: 1.6; } h1 { border-bottom: 2px solid #333; padding-bottom: 0.3em; } h2 { border-bottom: 1px solid #ccc; padding-bottom: 0.2em; margin-top: 1.5em; } h3 { margin-top: 1.2em; } /* Lists - critical for proper rendering / ul, ol { margin: 0.5em 0 0.5em 1.5em; padding-left: 1em; } ul { list-style-type: disc; } ol { list-style-type: decimal; } li { margin: 0.3em 0; } ul ul, ol ul { list-style-type: circle; margin: 0.2em 0 0.2em 1em; } ul ol, ol ol { margin: 0.2em 0 0.2em 1em; } ul ul ul, ol ul ul { list-style-type: square; } / Tables / table { border-collapse: collapse; width: 100%; margin: 1em 0; } th, td { border: 1px solid #ddd; padding: 8px; text-align: left; } th { background-color: #f5f5f5; } / Code / code { background-color: #f4f4f4; padding: 2px 6px; border-radius: 3px; } pre { background-color: #f4f4f4; padding: 1em; overflow-x: auto; border-radius: 5px; } / Other */ blockquote { border-left: 4px solid #ddd; margin: 1em 0; padding-left: 1em; color: #666; } @media print { body { max-width: none; } } EOF

Convert with embedded styles (ALWAYS use -f gfm)

pandoc -f gfm input.md -s --toc --toc-depth=2 -c /tmp/print-style.css --embed-resources --standalone -o output.html

Open and print to PDF (Cmd+P > Save as PDF)

open output.html

Word to Markdown

Extract markdown from docx

pandoc input.docx -o output.md

With ATX-style headers

pandoc input.docx --atx-headers -o output.md

Useful Options

Option Description

-s / --standalone

Produce standalone document with header/footer

--toc

Generate table of contents

--toc-depth=N

TOC depth (default: 3)

-V key=value

Set template variable

--metadata key=value

Set metadata field

--reference-doc=FILE

Use FILE for styling (docx/odt)

--template=FILE

Use custom template

--highlight-style=STYLE

Syntax highlighting (pygments, tango, etc.)

--number-sections

Number section headings

-f FORMAT

Input format (if not auto-detected)

-t FORMAT

Output format (if not auto-detected)

Format Identifiers

Format Identifier

Markdown markdown , gfm (GitHub), commonmark

Word docx

PDF pdf

HTML html , html5

LaTeX latex

RST rst

EPUB epub

ODT odt

RTF rtf

Google Docs Workflow

To get markdown into Google Docs with formatting preserved:

1. Convert to docx

pandoc document.md -o document.docx

2. Upload to Google Drive

3. Right-click > Open with > Google Docs

Google Docs imports .docx files well and preserves:

Headings
Bold/italic
Lists (bulleted and numbered)
Tables
Links
Code blocks (as monospace)

PSI Document Conversion

For PSI documents with tables and complex formatting:

Convert PSI markdown to Word

pandoc PSI-document.md
--standalone
--toc
--toc-depth=2
-o PSI-document.docx

Open for review

open PSI-document.docx

Troubleshooting

Lists/Lines Running Together (HTML)

If bullet points, numbered lists, or consecutive lines merge into one paragraph:

Cause: Standard markdown treats consecutive lines as one paragraph. Lists need blank lines before them.

Fix: Use GitHub Flavored Markdown (-f gfm ):

Always use -f gfm for reliable formatting

pandoc -f gfm -s input.md -o output.html

For documents where newlines should be <br> tags

pandoc -f markdown+hard_line_breaks -s input.md -o output.html

Why this happens:

Standard markdown: Line 1\nLine 2 → <p>Line 1 Line 2</p> (merged)
GFM: Better list detection, handles edge cases
+hard_line_breaks : Line 1\nLine 2 → Line 1<br>Line 2 (preserved)

Tables Not Rendering

Pandoc requires proper markdown table syntax:

Header 1	Header 2
Cell 1	Cell 2

Code Blocks Missing Highlighting

Use fenced code blocks with language identifier:

def example():
    pass

### PDF Generation Fails

**"pdflatex not found"** - Install LaTeX:
```bash
# Smaller option (~100MB)
brew install --cask basictex

# Full option (~4GB)
brew install --cask mactex-no-gui

# After install, update PATH
eval "$(/usr/libexec/path_helper)"
# Or open a new terminal

Unicode character errors (box-drawing, arrows, emojis):

# Use xelatex instead of pdflatex
export PATH="/Library/TeX/texbin:$PATH"
pandoc input.md --pdf-engine=xelatex -o output.pdf

No LaTeX available - Use HTML print-to-PDF workflow:

pandoc input.md -s --toc -o output.html
open output.html
# Then Cmd+P > Save as PDF

Self-Test

# Verify pandoc installation
pandoc --version | head -1

# Test basic conversion
echo "# Test\n\nHello **world**" | pandoc -f markdown -t html

pandoc

Safety Notice

Copy this and send it to your AI assistant to learn