Pandoc

Pandoc Document Conversion

Quick Example

# User: "Convert my thesis to PDF with citations"
# Skill assists by:
# 1. Validating YAML frontmatter (spaces, required fields)
# 2. Checking bibliography.bib and harvard.csl exist
# 3. Running: pandoc thesis.md -o thesis.pdf --citeproc --number-sections
# 4. ✅ Output: thesis.pdf created successfully

Overview

Provide expert assistance for converting markdown documents to PDF, DOCX, HTML, and presentations using Pandoc. Handle YAML frontmatter validation, bibliography setup, template generation, and format-specific conversion guidance.

When to Use This Skill

Automatically invoke this skill when the user:

• Mentions "convert to PDF", "generate PDF", "export to Word/DOCX"
• Asks about "pandoc", "markdown to PDF", "document conversion"
• Shows markdown with YAML frontmatter
• Asks about citations, bibliographies, academic papers
• Requests help with presentations (Beamer, reveal.js)
• Mentions LaTeX, XeLaTeX, or PDF engines
• Has errors converting documents

Do not use for:

• Simple markdown rendering/preview
• Other converters (not Pandoc)
• Markdown syntax questions (unless conversion-related)

Plugin Resources

Scripts

• scripts/validate.py - Python validation script for YAML frontmatter and dependencies

Templates (in assets/templates/)

• academic-paper.yaml - Academic paper with citations
• thesis-report.yaml - Thesis/report with custom title page
• presentation-beamer.yaml - LaTeX Beamer slides
• presentation-revealjs.yaml - reveal.js web slides
• article-simple.yaml - Simple article format
• defaults-pdf.yaml - Reusable PDF defaults file
• references.bib - BibTeX bibliography template
• Makefile - Project automation template

Citation Styles (in assets/csl/)

• harvard.csl - Harvard Cite Them Right style
• apa.csl - APA 7th edition style
• ieee.csl - IEEE style

Users can copy these to their project without downloading separately.

References

• references/conversion_guide.md - Format-specific instructions
• references/yaml_reference.md - Complete YAML variables
• references/templates_guide.md - Template usage guide
• references/troubleshooting.md - Common errors and solutions

Core Workflows

1. Validate Document

User asks: "Check if my document is ready to convert"

Workflow using tools directly:

# Path to validation script
PLUGIN_DIR="${CLAUDE_SKILL_DIR}"
VALIDATE_SCRIPT="$PLUGIN_DIR/skills/pandoc/scripts/validate.py"

# Run validation
python3 "$VALIDATE_SCRIPT" document.md

Suggest to user: "You can also validate with: /pandoc:validate document.md"

2. Create from Template

User asks: "Help me create an academic paper"

Workflow using tools directly:

# Path to templates
PLUGIN_DIR="${CLAUDE_SKILL_DIR}"
TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml"

# Copy template to user's file
cp "$TEMPLATE" paper.md

# Show what to edit
echo "Created paper.md from template"
echo ""
echo "Edit the following fields:"
echo "  - title: Your paper title"
echo "  - author: Your name"
echo "  - bibliography: Path to your .bib file"

Suggest to user: "Or use the template command: /pandoc:template academic-paper paper.md"

3. Convert Document

User asks: "Convert this to PDF"

Workflow using tools directly:

# Validate first
PLUGIN_DIR="${CLAUDE_SKILL_DIR}"
python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md

if [[ $? -eq 0 ]]; then
    # Check for bibliography
    if grep -q "^bibliography:" document.md; then
        CITEPROC="--citeproc"
        echo "Bibliography detected - enabling citations"
    fi

    # Convert with smart defaults
    pandoc document.md -o document.pdf \
        --pdf-engine=pdflatex \
        --number-sections \
        $CITEPROC

    if [[ $? -eq 0 ]]; then
        echo "✅ Conversion successful: document.pdf"
    else
        echo "❌ Conversion failed - check errors above"
    fi
else
    echo "❌ Validation failed - fix errors before converting"
fi

Suggest to user: "Or use the convert command with smart defaults: /pandoc:convert document.md document.pdf"

4. Add Frontmatter to Existing File

User asks: "This markdown file needs frontmatter"

Workflow using tools directly:

FILE="document.md"
PLUGIN_DIR="${CLAUDE_SKILL_DIR}"
TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml"

# Check if already has frontmatter
if head -n 1 "$FILE" | grep -q "^---$"; then
    echo "File already has frontmatter"
    echo "Use Read tool to view and Edit tool to modify"
else
    # Read existing content
    CONTENT=$(cat "$FILE")

    # Create temp file with template + content
    {
        cat "$TEMPLATE"
        echo ""
        echo "$CONTENT"
    } > "${FILE}.tmp"

    # Replace original
    mv "${FILE}.tmp" "$FILE"

    echo "✅ Added frontmatter to $FILE"
    echo "Edit the YAML fields at the top of the file"
fi

Suggest to user: "Or use: /pandoc:frontmatter document.md"

5. Setup Bibliography

User asks: "How do I add citations?"

Workflow:

1. Create bibliography file:

   PLUGIN_DIR="${CLAUDE_SKILL_DIR}"
   BIB_TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/references.bib"
   
   cp "$BIB_TEMPLATE" references.bib
   echo "Created references.bib - edit to add your sources"
   

2. Copy CSL file (bundled with plugin):

   PLUGIN_DIR="${CLAUDE_SKILL_DIR}"
   
   # Choose one:
   cp "$PLUGIN_DIR/skills/pandoc/assets/csl/harvard.csl" .
   cp "$PLUGIN_DIR/skills/pandoc/assets/csl/apa.csl" .
   cp "$PLUGIN_DIR/skills/pandoc/assets/csl/ieee.csl" .
   

3. Update frontmatter: Use Edit tool to add to document:

   bibliography: references.bib
   csl: harvard.csl
   link-citations: true
   

4. Explain citation syntax:

   Use [@citekey] for citations
   Use @citekey for in-text citations
   

Note: Plugin includes Harvard, APA, and IEEE styles. For other styles, download from https://github.com/citation-style-language/styles

6. Restyle Document to Match Template

User asks: "Transform this document to match academic paper format"

Workflow using tools directly:

PLUGIN_DIR="${CLAUDE_SKILL_DIR}"
INPUT_FILE="document.md"
TARGET_STYLE="academic-paper"  # or thesis, article, etc.

# 1. Backup original
cp "$INPUT_FILE" "${INPUT_FILE}.bak"
echo "Backed up to ${INPUT_FILE}.bak"

# 2. Read current frontmatter
echo "Current frontmatter:"
sed -n '/^---$/,/^---$/p' "$INPUT_FILE"

# 3. Get target template
TEMPLATE="$PLUGIN_DIR/skills/pandoc/assets/templates/${TARGET_STYLE}.yaml"

if [[ -f "$TEMPLATE" ]]; then
    # 4. Extract content (everything after second ---)
    CONTENT=$(sed -n '/^---$/,/^---$/{/^---$/d;p};/^---$/,$p' "$INPUT_FILE" | tail -n +2)

    # 5. Combine template frontmatter + content
    {
        cat "$TEMPLATE"
        echo ""
        echo "$CONTENT"
    } > "${INPUT_FILE}.tmp"

    # 6. Replace original
    mv "${INPUT_FILE}.tmp" "$INPUT_FILE"

    echo "✅ Restyled to $TARGET_STYLE format"
    echo ""
    echo "Next steps:"
    echo "  1. Edit frontmatter fields (author, title, etc.)"
    echo "  2. Validate: Check document is ready"
    echo "  3. Convert: Generate output"
else
    echo "❌ Template not found: $TARGET_STYLE"
    echo "Available: academic-paper, thesis, article, presentation-beamer, presentation-reveal"
fi

Common use cases:

1. OCR/PDF → Academic:

   • Remove: processed_date, ocr_model, source_type
   • Add: author, bibliography, documentclass

2. Draft → Thesis:

   • Add: supervisor, institution, department
   • Add: toc, lof, lot

3. Blog → Paper:

   • Add: bibliography, csl, numbersections
   • Update: documentclass to report

Suggest to user: "Or use: /pandoc:restyle document.md academic-paper"

Error Diagnosis

Common Errors and Fixes

Missing bibliography file:

# Check if file exists
if [[ ! -f references.bib ]]; then
    echo "Bibliography file not found"
    echo "Create it with: /pandoc:template bibtex references.bib"
fi

YAML syntax errors:

# Run validation to see exact error
python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md
# Explains: tabs vs spaces, missing quotes, etc.

Missing LaTeX packages (for PDF):

echo "Install LaTeX packages:"
echo "  sudo dnf install texlive-scheme-medium"
echo "  # or"
echo "  sudo apt-get install texlive-latex-base texlive-latex-extra"

Unicode errors in PDF:

echo "Use XeLaTeX instead of pdflatex:"
pandoc document.md -o document.pdf --pdf-engine=xelatex

Format-Specific Guidance

PDF Conversion

• Default: pdflatex (included in validation/conversion workflow)
• Unicode: Use --pdf-engine=xelatex
• Custom margins: Add to frontmatter: geometry: margin=1.5in

HTML Conversion

pandoc document.md -o document.html \
    --standalone \
    --self-contained \
    --toc

DOCX Conversion

pandoc document.md -o document.docx --standalone

Presentations

# Beamer (PDF slides)
pandoc slides.md -o slides.pdf --to beamer

# reveal.js (web slides)
pandoc slides.md -o slides.html --to revealjs --standalone

Best Practices

1. Always validate before converting - Use validation script directly
2. Use templates - Copy from assets/templates/ directory
3. Check files early - Verify .bib, .csl, images exist
4. Use relative paths - Makes documents portable
5. Explain steps clearly - Show what tools you're using
6. Suggest user commands - Mention slash commands as convenient alternatives
7. Handle errors gracefully - Run validation, explain fixes

Available User Commands

The plugin provides these slash commands for users:

• /pandoc:template <type> [file] - Generate document templates
• /pandoc:validate <file> - Validate frontmatter and dependencies
• /pandoc:convert <input> <output> [options] - Convert with smart defaults
• /pandoc:frontmatter <file> [type] - Add/update frontmatter
• /pandoc:restyle <input> <target-style> - Transform document to match template style
• /pandoc:defaults <format> [file] - Generate defaults file

As the skill: Use the underlying tools (scripts, pandoc CLI) directly via Bash. Mention these commands as suggestions for the user.

Reference Documentation

Load these when needed for detailed information:

• references/conversion_guide.md - Format-specific conversion details
• references/yaml_reference.md - All YAML variables explained
• references/templates_guide.md - Template customization guide
• references/troubleshooting.md - Comprehensive error solutions

Quick Reference

Plugin directory:

PLUGIN_DIR="${CLAUDE_SKILL_DIR}"

Validation:

python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" file.md

Templates:

cp "$PLUGIN_DIR/skills/pandoc/assets/templates/academic-paper.yaml" output.md

Conversion (basic):

pandoc input.md -o output.pdf --pdf-engine=pdflatex --number-sections

Conversion (with citations):

pandoc input.md -o output.pdf --pdf-engine=pdflatex --citeproc --number-sections