md-to-pdf

5.2.5 verified Sat Apr 25 auth: no javascript

md-to-pdf is a CLI tool for converting Markdown files to PDF using Marked (for HTML rendering) and Puppeteer (headless Chromium for PDF generation). Current stable version is 5.2.5 (last updated November 2023). It supports concurrent conversion of multiple files, watch mode, front-matter configuration, custom stylesheets/scripts, headers/footers, page breaks, syntax highlighting via highlight.js, and both CLI and programmatic API. Key differentiators include its hackability (~500 lines of TypeScript), stdio support, and optional HTML output. Note: v5.0.0 disabled JavaScript in front-matter by default to prevent RCE (security fix). Requires Node >=12.

Common errors

error Error: Cannot find module 'puppeteer' ↓

cause Puppeteer is a peer dependency and may not be installed automatically.

fix

Run npm install puppeteer in your project or install globally with npm i -g puppeteer.

error Error: Failed to launch the browser process! spawn /path/to/node_modules/puppeteer/.local-chromium/linux-.../chrome ENOENT ↓

cause Missing system dependencies for Chromium on Linux.

fix

Install required libraries: e.g.,

sudo apt-get install -y libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libdbus-1-3 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libcairo2

error TypeError: gray_matter_options is not iterable ↓

cause Using v5.0.0+ with gray-matter options that were previously valid but now require explicit 'null' to enable JS.

fix

Set gray_matter_options: undefined in programmatic API or pass --gray-matter-options 'null' in CLI to allow JavaScript execution.

error Error: marked_options.breaks must be a boolean ↓

cause Invalid type passed to marked options, often from JSON parsing (e.g., string instead of boolean).

fix

Ensure the value is correctly typed: in CLI use JSON string like --marked-options '{"breaks": true}', in programmatic API pass actual boolean.

Warnings

breaking v5.0.0 disables JavaScript engine in front-matter by default to prevent remote code execution (RCE). ↓

fix To enable JS in front-matter, pass `--gray-matter-options 'null'` on CLI or set `gray_matter_options: undefined` in programmatic options.

gotcha Puppeteer may not be bundled with the package; additional system dependencies may be required (e.g., libnss3, libnspr4 on Linux). ↓

fix Install Puppeteer's missing dependencies as per https://pptr.dev/troubleshooting#chrome-headless-doesnt-launch-on-unix

deprecated The `body-classes` option (plural) is deprecated; use `body-class` (singular) instead. ↓

fix Use `--body-class` in CLI or `body_class` in programmatic options.

gotcha Node 14 compatibility was broken in v5.2.3 due to use of `.replaceAll`, but fixed in v5.2.4. ↓

fix Upgrade to v5.2.4 or later, or set `--md-file-encoding` for certain edge cases.

breaking v5.1.0 changed the code highlighting option from overwriting `renderer.code` to using the `highlight` option in marked. ↓

fix Pass `highlight` function in `marked_options` instead of custom renderer.

Install

npm install md-to-pdf

yarn add md-to-pdf

pnpm add md-to-pdf

Imports

convertMdToPdf
wrong
```
const convertMdToPdf = require('md-to-pdf')
```
correct
```
import { convertMdToPdf } from 'md-to-pdf'
```
ESM import (package ships TypeScript types). The default export is not available; use named import. For CommonJS, use const { convertMdToPdf } = require('md-to-pdf').
convertMdToPdf (CommonJS)
wrong
```
const mdToPdf = require('md-to-pdf'); mdToPdf.convertMdToPdf()
```
correct
```
const { convertMdToPdf } = require('md-to-pdf')
```
Direct destructuring is the correct pattern. The module does not export a default object.
Options types
wrong
```
import { PdfOptions } from 'md-to-pdf'
```
correct
```
import type { PdfOptions, MarkedOptions } from 'md-to-pdf'
```
These are type-only exports. Use import type for TypeScript. Available since v5.0.

Quickstart

Demonstrates programmatic API: convert a markdown string to PDF with custom PDF options and CSS, then save to file.

import { convertMdToPdf } from 'md-to-pdf'
// For CommonJS: const { convertMdToPdf } = require('md-to-pdf')

async function main() {
  const pdf = await convertMdToPdf('# Hello, World!\n\nThis is a **markdown** string.', {
    pdf_options: { format: 'A4', margin: { top: '20mm', bottom: '20mm' } },
    css: 'body { font-family: Helvetica, Arial, sans-serif; }'
  })
  // pdf is a Buffer with the PDF content
  require('fs').writeFileSync('output.pdf', pdf)
}
main()