Markdown to PDF

Overview

Renders a Markdown file to a print-quality PDF via headless Chromium. Mermaid diagrams come out as vector SVG, tables repeat their header row across page breaks, and every page gets a running header and Page N of M footer.

Oversized diagrams are the hard part, and the script handles them: a diagram taller than the page is sliced across consecutive pages, and one far wider than the page is wrapped into stacked left-to-right bands. Both keep labels readable instead of shrinking the figure into an unreadable sliver.

Rendering is local. The page runs under a Content Security Policy that lets only the renderer's own scripts run and blocks every external fetch, and the browser aborts any request that gets past it. Scripts, event handlers and remote resources in raw HTML are blocked and listed on stderr.

Usage

node ~/.claude/skills/markdown-to-pdf/md2pdf.js <input.md> [output.pdf] [options]

Use the path where the skill is installed if it is not under ~/.claude/skills.

Output defaults to the input path with .pdf substituted. Options:

The document title (browser tab, PDF metadata, left-hand running header) comes from the first # heading, falling back to the filename.

Mermaid diagrams are fenced code blocks with the info string mermaid, with backticks or tildes. Markdown images with a local path are read relative to the Markdown file and embedded. A missing local image, or an image with an http or https URL, stops the render with an error: download remote images first.

The script prints a line per oversized diagram saying how it was handled, and a blocked line per script or resource the page was not allowed to run or load. Relay anything still flagged as too small, and any blocked line, to the user.

First run installs markdown-it, mermaid, and playwright-core into the skill directory automatically. Chromium is found in this order: CHROME_PATH, the build pinned by playwright-core at Playwright's install path, the newest build in the Playwright cache, then system Chrome/Chromium.

After rendering, always verify

The command exits non-zero if a diagram fails, but it cannot see layout problems. Render pages to images and look at them:

pdftoppm -png -r 75 out.pdf /tmp/preview/p    # then Read the PNGs

Check: no diagram clipped at a page edge, no table or code block running off the right margin, no page of pure whitespace (a blank page means content was clipped, not merely pushed). Report the page count to the user.

Design notes (why it is built this way)

Each of these fixes a bug that is invisible until you look at rendered pages:

• Chrome clips; it does not slice or scroll. Anything overflowing the print margin box is silently cut: an SVG taller than the page loses its lower half, a long code line loses its right end. Hence white-space: pre-wrap on pre, and the diagram slicing/banding rather than plain scaling.
• Page margins are 6 mm; <main> is padded 10 mm. Body text keeps a readable measure while .mermaid-slot uses negative margins to reach nearly the full sheet. A diagram cannot be given more room by breaking out past the margins, because that region is clipped, so the margins themselves have to be narrow.
• Mermaid's inline width/max-width are stripped after render. Mermaid writes them on the <svg>, where they outrank the stylesheet and let wide flowcharts run off the page. The script removes them and scales via the viewBox.
• The viewport is set to the printed diagram width so mermaid measures label wrapping at the width the diagram will occupy in print.
• Slices and bands overlap (36 px / 110 px) so a node cut by a seam reappears whole on the adjacent slice.
• thead { display: table-header-group } repeats table headers on continuation pages; tr { break-inside: avoid } stops rows splitting mid-cell.

Common problems

Styling

report.css holds the print stylesheet: serif body, sans headings and tables, navy accent, banded rows, callout styling for blockquotes. Edit it to restyle; it applies to every document rendered by this skill.