/md-to-pdf

name: md-to-pdf
description: 'Convert Markdown to styled PDFs with Mermaid diagrams, LaTeX/KaTeX math, tables, and code highlighting. Triggers on: "convert markdown to pdf", "make a pdf from this md", "export markdown as pdf", "pdf from markdown with equations".'
license: MIT. See LICENSE.txt for complete terms.
metadata:
  version: 1.2.2
  category: visualization
  tags: [pdf, markdown, mermaid, latex]
  difficulty: intermediate

Markdown to PDF Converter

Converts Markdown files to professionally styled PDFs with full rendering of Mermaid diagrams, LaTeX math (via KaTeX), tables, syntax-highlighted code blocks, and all standard Markdown features.

Architecture

Input .md file
     │
     ├─ Step 1: Extract ```mermaid blocks → render to SVG via mmdc (Mermaid CLI + Puppeteer)
     │          Replace mermaid code blocks with inline <svg> in the markdown source
     │
     ├─ Step 2: pandoc converts modified markdown → standalone HTML5
     │          (--katex flag preserves raw LaTeX in <span class="math ..."> elements)
     │
     ├─ Step 3: Node.js KaTeX server-side rendering
     │          Replaces math spans with fully rendered KaTeX HTML (no client-side JS needed)
     │
     ├─ Step 4: CSS injection
     │          KaTeX stylesheet (with local font paths) + professional document styles + optional custom CSS
     │
     └─ Step 5: Playwright (headless Chromium) prints final HTML → PDF
                 ↓
           Output .pdf file
````

## Supported Features

| Feature              | Rendering Engine                 | Notes                                                                 |
| -------------------- | -------------------------------- | --------------------------------------------------------------------- |
| Mermaid diagrams     | mmdc (mermaid-cli) via Puppeteer | flowchart, sequence, class, state, ER, gantt, pie, git, mindmap, etc. |
| LaTeX math (inline)  | KaTeX server-side                | `$E=mc^2$` syntax                                                     |
| LaTeX math (display) | KaTeX server-side                | `$$\int f(x) dx$$` syntax                                             |
| Tables               | pandoc + CSS                     | Full GFM pipe-table support with professional styling                 |
| Code blocks          | pandoc + CSS                     | Syntax highlighting via pandoc, monospace styling                     |
| Images               | pandoc + Playwright              | Local `file://` and remote `https://` images                          |
| Links                | pandoc                           | Rendered as styled text                                               |
| Lists / blockquotes  | pandoc                           | Ordered, unordered, nested, blockquotes                               |
| YAML frontmatter     | pandoc                           | `title` used as PDF title metadata                                    |
| Footnotes            | pandoc + CSS                     | `[^1]` syntax, rendered at page bottom                                |
| Definition lists     | pandoc + CSS                     | Term / definition pairs                                               |
| Strikethrough        | pandoc                           | `~~deleted~~` syntax                                                  |
| Horizontal rules     | pandoc + CSS                     | `---` rendered as styled separators                                   |

## Prerequisites

Run the setup checker before first use:

```bash
bash <SKILL_DIR>/scripts/setup.sh

This validates that all required tools are present and working. The standard Claude computer-use environment has everything pre-installed. For other environments, the required stack is:

| Dependency | Purpose | Install | | -------------------------------- | --------------- | ------------------------------------------------------- | | `pandoc` | Markdown → HTML | `apt install pandoc` | | `mmdc` (@mermaid-js/mermaid-cli) | Mermaid → SVG | `npm install -g @mermaid-js/mermaid-cli` | | `katex` (npm) | LaTeX → HTML | `npm install -g katex` | | `playwright` (Python) | HTML → PDF | `pip install playwright && playwright install chromium` | | Chrome/Chromium | Browser engine | Installed by Playwright or Puppeteer |

Usage

Basic

python3 <SKILL_DIR>/scripts/md_to_pdf.py <input.md> <output.pdf>

Full Options

python3 <SKILL_DIR>/scripts/md_to_pdf.py <input.md> <output.pdf> [OPTIONS]

| Parameter | Default | Description | | ----------------- | ------------ | ----------------------------------------------------------- | | `input` | _(required)_ | Path to input Markdown file | | `output` | _(required)_ | Path to output PDF file | | `--format` | `A4` | Page size: `A4`, `Letter`, `Legal`, `A3` | | `--margin` | `0.75in` | Margins — single value (uniform) or `top,right,bottom,left` | | `--no-mermaid` | `false` | Skip Mermaid rendering (keeps raw code blocks) | | `--no-math` | `false` | Skip KaTeX math rendering | | `--css` | _(none)_ | Path to additional custom CSS file to layer on top | | `--landscape` | `false` | Landscape orientation | | `--header-footer` | `false` | Show page numbers in footer (page / total) |

Examples

# Standard A4 conversion
python3 scripts/md_to_pdf.py report.md report.pdf

# US Letter, landscape, with pa