Project Page  ·  npm  ·  GitHub

Convert Markdown to PDF with Mermaid diagrams, KaTeX math, Obsidian syntax, syntax highlighting, batch processing, and Table of Contents generation. Available as a CLI and Node.js API.

Overview

md2pdf is a Markdown-to-PDF rendering engine built on the Unified ecosystem (Remark/Rehype) and Playwright. It generates PDFs with correct pagination, margins, and typography using headless Chromium.

Features

For detailed release notes, visit the GitHub Releases page.

Core Capabilities

• Batch Processing: Convert multiple files concurrently (md2pdf *.md). Uses a persistent Chromium instance for faster processing.
• Incremental Cache: Caches output to speed up batch conversions. Skips unchanged files automatically. Control caching with --no-cache and --clear-cache.
• Plugin API: Extend functionality using MarkdownPlugin, HtmlPlugin, RenderPlugin, ThemePlugin, and ExportPlugin. See the Plugin Documentation.
• Theming: Includes 7 built-in themes (default, github, obsidian-light, obsidian-dark, dracula, nord, academic). Use --theme <name> to apply.
• Obsidian Parity: Supports native callouts, wiki-links ([[Link]]), tags, embeds (![[Image.png]]), highlights (==highlight==), and YAML frontmatter.
• Syntax Highlighting: Uses Shiki for syntax highlighting across 20+ languages.
• Mermaid Diagrams: Native diagram rendering from code blocks. Safe for concurrent multi-file processing.
• Math Rendering: Supports KaTeX for inline and display LaTeX equations.
• Configuration: Supports persistent configuration files (md2pdf.config.ts, json, yaml) and profiles. See the Configuration Guide.
• Diagnostics: Use md2pdf doctor and md2pdf init for environment setup and troubleshooting.

Installation

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

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

Note: Due to npm v12 allowScripts defaults, browser binaries are not downloaded automatically 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 using wildcards:

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

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:

md2pdf init

Check system health and pipeline status:

md2pdf doctor

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

md2pdf input.md --debug

Browser Compatibility

If Playwright fails to download its bundled browser, or you are running in a constrained environment like a Docker container, you can force md2pdf to use an existing system browser (e.g., Google Chrome or Chromium) in one of two ways:

1. CLI Flag: --browser /path/to/chrome
2. Environment Variables: MD2PDF_BROWSER=/path/to/chrome or CHROME_PATH=/path/to/chrome

If no path is provided, md2pdf will attempt to automatically discover Google Chrome, Microsoft Edge, or Chromium on your host system before falling back to Playwright's browser download.

Exit Codes

md2pdf uses standard exit codes to facilitate CI/CD integration:

• 0: Success (All files processed correctly).
• 1: Usage Error / Validation Error (e.g., missing files, invalid arguments, parsing failure).
• 2: Runtime Error (e.g., browser launch failed, configuration error).

Node.js API Usage

Embed the rendering engine 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