@amitdevx/md2pdf
md2pdf is a production-grade Markdown-to-PDF rendering engine built on the Unified ecosystem (Remark/Rehype) for robust AST processing and Playwright for headless Chromium rendering. The result is a PDF that faithfully reflects modern web standards, featuring professional typography, precise margins, and correct pagination, without any browser installation friction for end users.
Version
Downloads
Build Status
License
Runtime
Installation
Global Installation
# Install globally
npm install -g @amitdevx/md2pdf
md2pdf init
Local Installation
# Or use locally within a project
npm install @amitdevx/md2pdf
npx md2pdf init
Practical Use Cases
README.md ➔ README.pdf
import { convert } from "@amitdevx/md2pdf";
const result = await convert({input: "./README.md", output: "./README.pdf",});Automated Release Notes
# GitHub Actions automated generation
md2pdf CHANGELOG.md --output release.pdfTechnical Documentation
md2pdf docs/architecture.md \--output build/architecture.pdf \--toc \--paper A4Resume Generation
md2pdf resume.md \--output resume.pdf \--margin 15mmRendering Pipeline
md2pdf Rendering Pipeline
Playwright-powered Markdown to PDF conversion flow
Key Features
- Extensible Plugin API (Markdown, HTML, Render, Theme, Export hooks)
- 7 professionally crafted built-in themes with strict Obsidian parity
- Native KaTeX Offline Math (mhchem)
- Mermaid & Architecture Diagrams
- Obsidian callouts, wiki-links, tags, embeds, highlights
- Batch processing with single Chromium instance
- Config file support (md2pdf.config.ts/json/yaml)
- md2pdf doctor & init diagnostic tooling
- GFM tables, strikethrough, task lists, footnotes
- Table of Contents with depth control
- Custom headers/footers with dynamic page numbers
- --json-errors & Structured error codes for CI
- JavaScript & TypeScript API
- Professional Typography & Syntax highlighting (Shiki)
Architecture Deep Dive
A detailed look into the underlying subsystems that power md2pdf's high-performance conversion pipeline.
Persistent Chromium Daemon
To optimize batch conversions, md2pdf utilizes a persistent Chromium daemon via Playwright. Instead of launching a new browser instance for every file, a single headless browser context is reused. This drastically reduces the overhead of parsing CSS and initializing V8, accelerating bulk document generation.
Incremental Content Caching
The incremental cache subsystem stores metadata in ~/.md2pdf-cache/index.json. By generating a SHA-256 hash of the Markdown AST and rendering options, the engine bypasses redundant PDF generations entirely if the source content remains unchanged, functioning similarly to a modern build system.
Extensible Plugin System
The architecture exposes a robust Plugin Registry allowing developers to hook directly into various lifecycle events: AST manipulation (Unified/Remark), HTML rendering (Rehype), and Playwright PDF generation limits. This enables custom tags, complex macros, and advanced layout overrides.
Heuristic Error Diagnostics
A heuristic diagnostic layer intercepts low-level Playwright and system errors (e.g., missing Linux shared libraries or sandbox restrictions) and translates them into actionable, human-readable instructions. This powers the md2pdf doctor command.
CLI Usage
Quick and powerful commands to generate PDFs directly from your terminal.
Single File
# Generate a PDF from a single file:
md2pdf README.md
Custom Output & TOC
# Generate a Table of Contents:
md2pdf input.md --output custom.pdf --toc
Paper Size & Margins
# Custom paper size/margins:
md2pdf input.md --paper Letter --margin 15mm
Page Breaks
# Break before H1 heading:
md2pdf input.md --h1-new-page
Batch Mode
# Convert multiple files:
md2pdf "docs/*.md" --output out_dir/
Config File
# Use JSON config:
md2pdf input.md --config md2pdf.config.json
Obsidian Vault
# Resolve local links:
md2pdf note.md --vault-root ./vault --resolve-links
CI / Errors
# Machine-readable output:
md2pdf input.md --json-errors
Debug & Verbose
# Verbose output:
md2pdf input.md --verbose
Rendered Output
Side-by-side comparison showcasing typography, syntax highlighting, and layout accuracy.
The **md2pdf** engine supports native mathematics & diagrams.
```mermaid
graph TD
AST --> Playwright
```
## Equation
$$
E = mc^2
$$
System Architecture
The md2pdf engine supports native mathematics & diagrams.
Equation
Diagnostics & Setup
Built-in tools to ensure your rendering environment is perfectly configured.
Initialization
# Initialize environment:
md2pdf init
System Health
# Check pipeline status:
md2pdf doctor
Debug Mode
# Print stack traces:
md2pdf input.md --debug
Library Usage
Embed the rendering engine directly in your Node.js applications.
import { convert } from '@amitdevx/md2pdf';
const result = await convert({
input: 'README.md',
output: 'README.pdf',
paper: 'A4',
margin: '20mm',
toc: true
});
console.log(`Render time: ${result.renderTimeMs}ms`);
| Option | Type | Description |
|---|---|---|
| math | boolean | Enable KaTeX/mhchem rendering |
| theme | string | Custom CSS theme path |
| mermaid.theme | string | default, dark, forest, neutral |
| pageBreaks | boolean | Force page breaks on headers |
| metadata | object | PDF Author, Title, Keywords |
| header / footer | string | Custom HTML templates |