---
name: md-to-pdf
description: Convert Markdown files to professionally styled PDFs with full Mermaid diagram support. Chains mmdc (Mermaid CLI) for diagram rendering with pandoc + tectonic for PDF generation. Use this skill when the user wants to generate PDFs from Markdown documentation, render Mermaid diagrams in documents, or batch-convert a directory of Markdown files to PDF.
---

# Markdown to PDF Skill

**For Claude Code AI Assistant**

This skill converts Markdown files to PDF with automatic Mermaid diagram rendering. It chains two tools in the correct order:

1. **mmdc** (@mermaid-js/mermaid-cli) — extracts and renders ```` ```mermaid ```` code blocks to PNGs
2. **pandoc** + **tectonic** — converts the processed Markdown (with rendered diagram images and linked images) to PDF

## Purpose

Produce print-ready PDFs from Markdown documentation that contains:
- Mermaid diagrams (flowcharts, sequence diagrams, ERDs, etc.)
- Linked images (relative or absolute paths)
- Tables, code blocks, YAML front matter
- Table of contents with section numbering

## Pipeline

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  input.md    │────▶│   mmdc       │────▶│   pandoc     │────▶ output.pdf
│              │     │  (mermaid    │     │  + tectonic  │
│ ```mermaid   │     │   → PNG)     │     │  (md → PDF)  │
│ ![](img.png) │     └──────────────┘     └──────────────┘
└──────────────┘
```

Step by step:

1. Read the Markdown file line by line
2. When a ```` ```mermaid ```` block is found, extract its content to a `.mmd` temp file
3. Run `mmdc -i diagram.mmd -o diagram.png` to render it as a high-resolution PNG
4. Replace the mermaid code block with `![Diagram N](path/to/diagram.png)`
5. Resolve relative image paths to absolute so pandoc can find them
6. Write the processed Markdown to a temp file
7. Run pandoc with tectonic as the PDF engine, passing `--resource-path` for image resolution

## Available Commands

### 1. Convert a Single File

```bash
md-to-pdf.sh convert <input.md> [output.pdf] [--style <header.tex>]
```

Converts one Markdown file to PDF.

**Arguments**:
- `input.md` — the Markdown file to convert (required)
- `output.pdf` — output path (default: same name with `.pdf` extension)
- `--style <header.tex>` — custom LaTeX header for styling (fonts, colors, margins)

**Examples**:
```bash
# Basic conversion
md-to-pdf.sh convert docs/guide.md

# Specify output path
md-to-pdf.sh convert README.md output/readme.pdf

# With custom styling
md-to-pdf.sh convert docs/manual.md --style docs/custom-header.tex
```

### 2. Batch Convert a Directory

```bash
md-to-pdf.sh batch <directory> [--style <header.tex>] [--outdir <output_dir>]
```

Converts all `.md` files in a directory to PDFs.

**Arguments**:
- `directory` — directory containing `.md` files (required)
- `--style <header.tex>` — custom LaTeX header applied to all files
- `--outdir <dir>` — output directory for PDFs (default: same as input)

**Examples**:
```bash
# Convert all manuals
md-to-pdf.sh batch docs/manuals/

# Output to a separate directory
md-to-pdf.sh batch docs/manuals/ --outdir docs/pdfs/

# With custom branding
md-to-pdf.sh batch docs/ --style branding-header.tex --outdir output/
```

### 3. Check Dependencies

```bash
md-to-pdf.sh check
```

Verifies all required tools are installed and reports their versions.

## Mermaid Diagram Support

Any fenced code block with the `mermaid` language tag is automatically rendered:

````markdown
```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```
````

The rendered PNG replaces the code block in the final PDF. If rendering fails for a specific diagram, the original code block is preserved as-is.

### Supported Diagram Types

All diagram types supported by @mermaid-js/mermaid-cli work:
- Flowcharts (`flowchart TD/LR`)
- Sequence diagrams (`sequenceDiagram`)
- Class diagrams (`classDiagram`)
- Entity-relationship diagrams (`erDiagram`)
- Gantt charts (`gantt`)
- State diagrams (`stateDiagram-v2`)
- Pie charts, git graphs, mindmaps, etc.

## Image Handling

The skill handles images referenced in Markdown:

- **Relative paths** (`![](screenshots/img.png)`) are resolved to absolute paths so pandoc can locate them regardless of working directory
- **Absolute paths** are passed through unchanged
- **Remote URLs** (`![](https://...)`) are passed to pandoc which handles downloading them

## PDF Styling

### Default Style

Out of the box, PDFs include:
- 1-inch margins on all sides
- 11pt font size
- Colored hyperlinks (blue)
- Syntax-highlighted code blocks (tango theme)
- Auto-generated table of contents
- Numbered sections

### Custom LaTeX Header

For branded PDFs, create a LaTeX header file and pass it with `--style`:

```latex
% custom-header.tex
\usepackage{fancyhdr}
\usepackage{xcolor}

% Define brand colors
\definecolor{brandblue}{HTML}{3B82F6}
\definecolor{brandgray}{HTML}{6B7280}

% Custom header/footer
\pagestyle{fancy}
\fancyhf{}
\fancyhead[L]{\textcolor{brandgray}{\small Company Name}}
\fancyhead[R]{\textcolor{brandgray}{\small \leftmark}}
\fancyfoot[C]{\textcolor{brandgray}{\small Page \thepage}}

% Custom title style
\usepackage{titling}
\pretitle{\begin{center}\LARGE\bfseries\color{brandblue}}
\posttitle{\end{center}\vskip 0.5em}
```

### YAML Front Matter

Pandoc recognizes YAML metadata at the top of Markdown files:

```yaml
---
title: User Manual
subtitle: Version 2.0
author: Engineering Team
date: 2026-02-27
---
```

## Dependencies

| Tool | Version | Install |
|------|---------|---------|
| pandoc | 3.0+ | `brew install pandoc` |
| tectonic | 0.14+ | `brew install tectonic` |
| mmdc | 11.0+ | `npm install -g @mermaid-js/mermaid-cli` |

Run `md-to-pdf.sh check` to verify all dependencies.

## Error Handling

- **Missing dependencies**: Reports which tools are missing with install instructions
- **Failed mermaid render**: Warns and preserves the original code block (does not abort)
- **Missing images**: Pandoc warns but continues generating the PDF
- **Unterminated mermaid block**: Warns and outputs the block as-is

## Typical Workflow

```bash
# 1. Verify setup
md-to-pdf.sh check

# 2. Convert a single doc
md-to-pdf.sh convert docs/architecture.md

# 3. Batch convert all manuals with branding
md-to-pdf.sh batch docs/manuals/ \
  --style docs/manuals/brand-header.tex \
  --outdir docs/pdfs/
```

## Integration with Manual Screenshot Workflow

This skill pairs with the Playwright screenshot capture workflow:

```bash
# 1. Capture screenshots (Playwright)
cd pms-web
npx playwright test e2e/manuals/ --config e2e/manuals/playwright.manuals.config.ts

# 2. Generate PDFs from manuals (this skill)
md-to-pdf.sh batch docs/manuals/ --outdir docs/pdfs/
```

The manuals reference screenshots via relative paths like `![Dashboard](screenshots/front-desk/01-dashboard.png)` which the skill resolves automatically.

## Version

1.0.0