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.5.4)

• Massive Performance Boost: 5x faster single-file conversion via persistent Chromium daemon, local base64-bundled offline fonts (zero CDN latency), KaTeX lazy-loading, and regex optimization.
• Smaller Footprint: npm package size reduced by ~80% (sourcemaps disabled, minification enabled, KaTeX unbundled).
• Codebase Restructuring: CLI monolith split into focused command handlers, unused directories removed, and plugin layout rationalized.
• Enhanced Reliability: Security updates (Vitest ^3.2.0), deep configuration merge testing, and 60+ new core test paths.

Available (v0.5.4)

• Mermaid Syntax Tolerance (New in v0.5.4): Flawless native Mermaid compatibility by securely downgrading the embedded engine to v10.9.1 (Obsidian parity). Intelligently bridges the syntax gap using proper AST regex preprocessing (e.g. converting \" to #quot; and () to ()) so your complex Obsidian diagrams and mindmaps compile without crashing the headless Chromium renderer.
• Robust CLI Processing (New in v0.5.4): Added step-by-step per-file overwrite warnings, color-coded red terminal errors for deep plugin failures, and graceful batch interruptions using Ctrl+C.

Previous Versions

• Configuration (New in 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 (New in 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.
• Enterprise Robustness (v0.5.1): Resolved critical architectural constraints including Mermaid CSS leakage, PDF metadata processing performance, Obsidian circular embed protection, AST regex greedy matching, and native Node 18 runtime validation.
• 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

• Theming: Custom CSS themes and layout overrides.
• 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