Project Page  ·  npm  ·  GitHub

Convert Markdown to high-fidelity PDF: CLI tool and Node.js API powered by headless Chromium. Supports Mermaid diagrams, KaTeX math, Obsidian callouts and wiki-links, GFM tables, syntax highlighting via Shiki, batch conversion, custom themes, TOC generation, and PDF metadata injection.

Overview

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 — professional typography, precise margins, and correct pagination — without any browser installation friction for end users.

Features

For detailed release notes and changelogs, please visit the GitHub Releases page.

Available (v0.6.1)

• Theming System: Introducing 7 professionally crafted built-in themes (default, github, obsidian-light, obsidian-dark, dracula, nord, academic). Use --theme <name> to instantly transform your PDF's aesthetics. Includes printer-friendly styling for dark themes.
• Strict Obsidian Parity: Flawless visual alignment with Obsidian's native exports. Features perfect Lucide SVG callout icons with exact color matching, stripped ^block-identifiers, automatic H1 document title injection, and minimalist tables for obsidian-light/dark themes.
• Dynamic Syntax Highlighting: Massive parsing speedup. Shiki grammars are now dynamically detected and loaded on-the-fly, reducing compilation overhead by up to 10 seconds per file.
• Improved Layout Engine: Mermaid diagrams now naturally left-align (matching standard markdown flow), and large tables gracefully span across page breaks with repeating headers.

Previous Versions

• Performance & Core (v0.5.4): 5x faster single-file conversion via persistent Chromium daemon and local base64 offline fonts. Flawless Mermaid syntax tolerance bridging complex AST diagrams. Smaller npm footprint and graceful CLI interruptions.
• Configuration (v0.5.0): Advanced persistent configuration file support (md2pdf.config.ts, json, yaml), profiles (--profile), and fully typed programmatic definitions. See Configuration Guide.
• Batch Processing & Error Resilience (v0.5.1): Process multiple files at once (md2pdf *.md). Intelligently continues on conversion errors, emits rich JSON failure mappings, and fully resolves Windows pathing.
• Obsidian Compatibility (New in v0.4.1/v0.4.2): Native parsing and rendering for callouts, wiki-links ([[Link]]), tags, embeds (![[Image.png]]), highlight syntax (==highlight==), and YAML frontmatter.
• High-Fidelity Rendering: Utilizes Chromium via Playwright for native print CSS capabilities.
• Math Rendering (New in v0.3.0): Print-perfect LaTeX inline and display math via KaTeX. Full support for matrices, environments, and macros with zero-dependency embedded fonts.
• Unified Pipeline: Built entirely on remark and rehype ASTs for robustness.
• Professional Typography: Modular CSS system optimized for readability and print with Inter and JetBrains Mono.
• Syntax Highlighting: Integrated shiki plugin for syntax highlighting across 20+ languages.
• Mermaid Diagrams: Native diagram generation directly from code blocks with intrinsic SVG scaling and error reporting.
• Diagnostic Tooling: Run md2pdf doctor and md2pdf init for comprehensive pipeline debugging and auto-repair.
• GitHub Flavored Markdown: Natively supports GFM tables and strikethrough.
• Table of Contents: Auto-generate hyperlinked TOC with depth configuration.
• Footnotes: Standard GFM footnotes with bidirectional backlinks. Note: inline footnote syntax (^[...]) is not supported.
• Document Metadata: Automatically extracts YAML frontmatter to inject native PDF metadata properties.
• Headers, Footers & Page Breaks: Inject custom HTML headers/footers with dynamic page numbers and control pagination manually or automatically.

Coming Soon

• Plugin System: Extensible architecture for custom rendering logic.

Installation

# Install globally
npm install -g @amitdevx/md2pdf
md2pdf init

# Or use locally within a project
npm install @amitdevx/md2pdf
npx md2pdf init

Note: For security and compliance with npm v12 allowScripts defaults, we no longer automatically download browser binaries during install. You must run md2pdf init after installation to fetch the required Chromium dependencies.

CLI Usage

Generate a PDF from a single Markdown file:

md2pdf README.md

Process multiple files at once (Batch Mode) using wildcards (new in v0.5.1):

md2pdf "docs/*.md" --output out_dir/

(Batch mode intelligently reuses a single Chromium instance for 10x faster processing and sequential memory safety)

Specify a custom output path and generate a Table of Contents:

md2pdf input.md --output custom.pdf --toc

Convert with custom paper size and margins:

md2pdf input.md --paper Letter --margin 15mm

Force a page break before every H1 heading:

md2pdf input.md --h1-new-page

Environment Diagnostics & Setup

Initialize a new environment and download dependencies automatically:

md2pdf init

Check your system health and Playwright pipeline status:

md2pdf doctor

Print advanced internal variables and stack traces if an error occurs:

md2pdf input.md --debug

Note: Typography uses Inter and JetBrains Mono served from Google Fonts CDN. Internet access is required during conversion for correct typography. Offline environments will fall back to system fonts.

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`);

Development Setup

git clone https://github.com/amitdevx/md2pdf.git
cd md2pdf
npm install
npx md2pdf init

Contributing

Please refer to docs/contributing.md for our guidelines, branch naming conventions, and coding standards.

License

MIT License. See LICENSE for details.

Author

Amit Divekar — amitdevx.tech · Project Page · GitHub