plinde 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 |
|
| 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:
```python
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