pandoc

What this skill does

# Pandoc Document Conversion

## Quick Example

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
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:**
   ```bash
   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):**
   ```bash
   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:
   ```yaml
   bibliography: references.bib
   csl: harvard.csl
   link-citations: true
   ```

4. **Explain citation syntax:**
   ```markdown
   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:**

```bash
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 b