playbooks

home / skills / jrajasekera / claude-skills / pandoc-converter

pandoc-converter skill

/pandoc-converter

This skill converts documents between formats using Pandoc, simplifying file format swaps like markdown to PDF or CSV to HTML.

npx playbooks add skill jrajasekera/claude-skills --skill pandoc-converter

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.7 KB
---
name: pandoc-converter
description: Convert documents between formats using Pandoc. Use when the user asks to convert files between formats like markdown, docx, html, pdf, latex, epub, rtf, csv, xlsx, or pptx. Triggers on requests like "convert this to Word", "export as PDF", "turn this markdown into HTML", or "convert the CSV to a table".
---

# Pandoc Converter

Convert documents between common formats using Pandoc.

## Quick Start

```bash
# Basic conversion (format auto-detected from extensions)
python scripts/convert.py input.md output.docx

# Specify output format only
python scripts/convert.py document.md --to html

# Check if Pandoc is installed
python scripts/convert.py --check

# List supported formats
python scripts/convert.py --formats
```

## Supported Formats

**Document formats (read/write):** markdown, html, docx, latex, epub, rtf, pptx, pdf  
**Data formats (read only):** csv, tsv, xlsx  
**Markdown variants:** gfm (GitHub), commonmark

For detailed compatibility, see `references/format-compatibility.md`.

## Common Conversions

| From | To | Command |
|------|-----|---------|
| Markdown | Word | `python scripts/convert.py doc.md doc.docx` |
| Markdown | PDF | `python scripts/convert.py doc.md doc.pdf` |
| Markdown | HTML | `python scripts/convert.py doc.md doc.html` |
| Word | Markdown | `python scripts/convert.py doc.docx doc.md` |
| CSV | HTML table | `python scripts/convert.py data.csv data.html` |
| LaTeX | PDF | `python scripts/convert.py paper.tex paper.pdf` |

## Options

| Option | Description |
|--------|-------------|
| `--from <fmt>` | Override input format detection |
| `--to <fmt>` | Specify output format (if no output file) |
| `--standalone` | Include document headers/footers |
| `--toc` | Add table of contents |
| `--pdf-engine <eng>` | PDF engine: pdflatex, xelatex, lualatex |

Additional Pandoc options pass through directly.

## Workflow

1. **Check installation:** Run `python scripts/convert.py --check`
2. **If not installed:** Follow the installation instructions provided
3. **Convert:** Run the conversion with input and output files
4. **Present result:** Provide the converted file to the user

## Installation (if needed)

The script provides installation guidance, but here's a summary:

```bash
# macOS
brew install pandoc

# Ubuntu/Debian  
sudo apt-get install pandoc

# For PDF output, also install LaTeX:
# macOS: brew install --cask mactex-no-gui
# Ubuntu: sudo apt-get install texlive-xetex
```

## Limitations

- **CSV/TSV/XLSX:** Input only (converts to tables in other formats)
- **PDF output:** Requires LaTeX installation
- **PPTX:** Text extraction works; complex layouts may simplify
- **Complex formatting:** Some features may not transfer between formats

Overview

This skill converts documents between common formats using Pandoc, exposing a simple command-line wrapper for predictable results. It supports conversions among markdown, docx, html, pdf, latex, epub, rtf, pptx, and more, and passes additional Pandoc options through for advanced control. Use it to automate format changes, export clean HTML, generate PDFs, or turn data files into tables. The tool includes checks for Pandoc and guidance for PDF engine requirements.

How this skill works

The converter inspects file extensions to auto-detect input and output formats, or you can override detection with --from and --to flags. It invokes Pandoc under the hood and forwards extra options directly, enabling features like standalone documents, table of contents, and specific PDF engines. The script can list supported formats and verify that Pandoc is installed before running conversions.

When to use it

  • You need to change a document from Markdown to Word, PDF, HTML, or LaTeX.
  • You want to export a Word or Markdown document as a styled PDF (LaTeX required).
  • You need to convert CSV/TSV/XLSX into an HTML table or embed data into docs.
  • You want to batch-convert many files with consistent Pandoc options.
  • You need quick format checks or to see which formats Pandoc supports.

Best practices

  • Run the --check command first to ensure Pandoc and required engines are installed.
  • Specify --from or --to when automatic detection might be ambiguous.
  • Use --standalone and --toc for complete documents with headers and a table of contents.
  • For PDF output, install a LaTeX engine (xelatex or pdflatex) and test with a small file first.
  • Keep a version-controlled source (e.g., Markdown) and regenerate derived formats as needed.

Example use cases

  • Convert a README.md into a Word document for corporate review: python scripts/convert.py README.md README.docx
  • Export a blog post from markdown to HTML with a table of contents: python scripts/convert.py post.md post.html --standalone --toc
  • Turn research LaTeX into a PDF using xelatex: python scripts/convert.py paper.tex paper.pdf --pdf-engine xelatex
  • Generate an EPUB from a collection of markdown chapters for e-reader distribution.
  • Transform a CSV dataset into an HTML table for quick reporting: python scripts/convert.py data.csv data.html

FAQ

Do I need Pandoc installed separately?

Yes. The script calls Pandoc. Run the script with --check to verify installation and follow the provided platform-specific install commands if missing.

Can it produce PDFs without extra software?

PDF output normally requires a LaTeX engine (xelatex, pdflatex, or lualatex). Install a suitable TeX distribution to ensure reliable PDF generation.