md2pdf

A fast Markdown-to-PDF converter written in Rust. Pagination, images, tables, links, Mermaid diagrams, and syntax highlighting — no Python, browser, or LaTeX required.

Install

Homebrew

Homebrew core ships a different Go-based md2pdf. Install this one with:

brew install 0xtlt/tap/md2pdf

If md2pdf --help mentions md2pdf.go, you have the wrong package:

brew uninstall md2pdf
brew install 0xtlt/tap/md2pdf

Binary

Download the archive for your platform from the latest release.

Cargo

cargo install --git https://github.com/0xtlt/md2pdf

Usage

md2pdf document.md
md2pdf document.md --output build/document.pdf
md2pdf document.md --code-theme light --accent '#2563EB'
md2pdf document.md --page-size letter --landscape
md2pdf presentation.md --slides --output presentation.pdf
md2pdf presentation.md --slides --slide-template dark -o presentation.pdf
cat document.md | md2pdf - --output document.pdf
md2pdf './**/*.md' --output-mode merge -o all.pdf
md2pdf 'docs/**/ADR-*.md' --output-mode zip -o docs.zip -j 4
md2pdf a.md b.md --output-mode files -o out/ --name-format '{stem}-{index}.pdf'

Option	Default	Description
SOURCE...	required	Markdown files, directories, or globs such as ./**/*.md (- for stdin)
-o, --output PATH	source with .pdf	Output PDF, zip path, or directory for per-file mode
--grep GLOB	**/*.md for directories	Optional extra filter when walking directories
--output-mode files|merge|zip	files	Per-file PDFs, one merged PDF, or a zip of PDFs
--name-format TEMPLATE	{stem}.pdf	Per-file / zip entry names ({stem}, {name}, {dir}, {index}, {ext})
-j, --jobs N	CPU count (1–8)	Parallel file conversions
--title TEXT	first # heading	PDF metadata title
--author TEXT	empty	PDF metadata author
--page-size a4|letter	a4	Page format
--landscape	off	Landscape orientation
--slides	off	Render a 16:9 deck; --- starts the next slide
--slide-template modern|minimal|dark	modern	Built-in slide design
--margin MM	17	Margins (8–45 mm)
--accent '#RRGGBB'	#C94C35	Heading color
--code-theme dark|light	dark	Code block theme
--line-numbers	off	Show code line numbers
--no-header	off	Hide page header
--page-break-before PREFIX	none	Page break before matching ##
--no-external	off	Do not download remote images
--allow-http	off	Allow cleartext http:// image downloads
-q, --quiet	off	Suppress success output and warnings

Run md2pdf --help for the full list.

Agent skill

This repository includes a skill that teaches Codex and other compatible agents to render Markdown documents, batch outputs, and 16:9 slide decks with md2pdf.

Install it in the current project:

npx skills add 0xtlt/md2pdf --skill render-markdown-pdf --agent codex

Add --global to install it globally. In Codex, invoke it explicitly with $render-markdown-pdf.

Mermaid diagrams

This compact technical deck combines slide separators, a Mermaid pipeline, and syntax-highlighted code. Save it as technical-deck.md:

# Rendering architecture

Markdown to widescreen PDF, entirely in process.

---

### RENDERING PIPELINE

## Embedded diagrams and code

```mermaid
flowchart LR
    Markdown --> Parser --> Typst --> PDF
```

```rust
fn main() {
    println!("16:9 slides");
}
```

Render it with:

md2pdf technical-deck.md --slides --slide-template modern -o technical-deck.pdf

Mermaid SVG canvases are transparent, so diagrams inherit the document page or slide-template background. In slide decks, wide pipelines scale up for room readability while tall and non-wide diagrams remain constrained to the slide. The dark slide template automatically uses Mermaid's complete dark palette. Gantt and timeline diagrams continue to use the full available width.

Features

• Typst PDF engine with embedded fonts
• TextMate syntax highlighting (dark / light)
• Transparent, page-aware Mermaid diagrams from mermaid / mmd fences
• Clickable links and local images
• Remote HTTPS images downloaded by default (--no-external to deny, --allow-http for cleartext HTTP)
• Multi-file conversion: merge, zip, or per-file output with parallel jobs
• A4 / Letter, portrait or landscape
• 16:9 slide decks with cover/content layouts and three built-in templates
• Custom title, author, header, footer, margins, and accent

Docs

• Markdown support
• Slide decks
• Syntax highlighting
• Architecture
• Contributing

License

MIT. Embedded DejaVu fonts: assets/fonts/LICENSE_DEJAVU.