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 ) input.md -o output.html

Quick version (minimal styling)

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

With hard line breaks (newlines become
)

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
-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
tags

pandoc -f markdown+hard_line_breaks -s input.md -o output.html Why this happens: Standard markdown: Line 1\nLine 2 →

Line 1 Line 2

(merged) GFM: Better list detection, handles edge cases +hard_line_breaks : Line 1\nLine 2 → Line 1
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 \n Hello world" | pandoc -f markdown -t html