mermaid-md-pdf-cli

mermaid-md-pdf-cli is a command-line tool that converts Markdown files into PDF documents, including Mermaid diagrams rendered through a headless browser.

If you are using the package from npx, start with the usage examples below.

If you are an AI agent, prefer the JSON help and report modes so you can inspect arguments and outputs mechanically.

Usage

Run the CLI with npx:

npx mermaid-md-pdf-cli --help

Convert a single Markdown file:

npx mermaid-md-pdf-cli --input sample/Gantt_Sample.md --output sample/Gantt_Sample.pdf

Convert from stdin and redirect PDF bytes from stdout:

cat sample/Gantt_Sample.md | npx mermaid-md-pdf-cli > sample/Gantt_Sample.pdf

Convert every Markdown file in a directory while preserving the relative folder structure:

npx mermaid-md-pdf-cli --input docs --output dist

Generate a conversion plan without writing PDFs:

npx mermaid-md-pdf-cli --input docs --plan --report-format json

AI Agent Usage

Use these options when another tool or agent needs to understand the CLI without parsing prose.

• --help-format json: returns the command schema, option types, defaults, and constraints as JSON.
• --report-format json: returns machine-readable execution results.
• --plan: lists target files and output paths without rendering PDFs.

Recommended flow for agents:

npx mermaid-md-pdf-cli --help-format json
npx mermaid-md-pdf-cli --input docs --plan --report-format json
npx mermaid-md-pdf-cli --input docs --report-format json

Installation

npm install
npm run build

To run conversion directly from the built dist output, use:

node ./dist/src/index.js --input sample/Gantt_Sample.md --output sample/Gantt_Sample.pdf

Configuration

The CLI supports the following options:

• --input <path>: Markdown file or directory to convert. Required.
• --output <path>: Output PDF file or directory. If omitted, PDF bytes are written to stdout.
• --plan: Print the planned conversions without rendering PDFs.
• --report-format <text|json>: Select the report format.
• --help-format <text|json>: Print help output as JSON for automated use.
• --timeout <ms>: PDF rendering timeout. Default: 30000.
• --format <A4|Letter>: Paper size. Default: A4.
• --landscape: Render the PDF in landscape orientation.
• --scale <number>: Page scale. Default: 1.
• --margin-top, --margin-right, --margin-bottom, --margin-left: CSS margin values. Default: 10mm.
• --title <text>: PDF document title metadata.
• --author <text>: PDF document author metadata.
• --toc: Generate a table of contents from headings.
• --toc-depth <n>: Maximum heading depth to include in TOC. Default: 3.
• --toc-title <text>: TOC heading text. Default: Contents.
• --watch: Keep watching input changes and rerun conversion automatically.
• --theme <themeOrCssPath>: Theme input. You can pass a built-in theme name like default or a .css file path. Repeatable.
• --css <cssText>: Inline CSS text appended after --theme styles.

Shorthand aliases are also available:

• -i: --input
• -o: --output
• -p: --plan
• -r: --report-format
• -j: --help-format
• -t: --timeout
• -f: --format
• -l: --landscape
• -s: --scale

If you need to point Puppeteer to a specific browser binary, set PUPPETEER_EXECUTABLE_PATH.

Mermaid runtime is bundled in the package, so converting documents with Mermaid does not require external network access at runtime.

Examples

The repository includes a sample file you can use to verify the renderer:

npx mermaid-md-pdf-cli --input sample/Gantt_Sample.md --output sample/Gantt_Sample.pdf

Apply the default theme and additional inline CSS:

npx mermaid-md-pdf-cli --input sample/Gantt_Sample.md --output sample/Gantt_Sample.pdf --theme default --css "body { color: tomato; }"

Apply multiple themes in appearance order:

npx mermaid-md-pdf-cli --input sample/Gantt_Sample.md --output sample/Gantt_Sample.pdf --theme default --theme ./styles/print.css

Generate TOC and metadata:

npx mermaid-md-pdf-cli --input sample/Gantt_Sample.md --output sample/Gantt_Sample.pdf --title "Project Plan" --author "Alice" --toc --toc-depth 2 --toc-title "Contents"

Run in watch mode and reconvert on file changes:

npx mermaid-md-pdf-cli --input docs --output dist --watch

--watch cannot be combined with stream mode (stdin input, omitted --output, or --output -).

For folder inputs, output paths keep the source directory layout. By default, PDFs are written under <input>/_pdf/.

Support

TODO: add the project issue tracker, discussion board, or maintainer contact here.

Contributing

Contributions are welcome.

• Open an issue or submit a pull request for changes.
• Run the test and lint suite before sending patches:

npm test
npm run test:e2e
npm run lint
npm run type-check

License

See LICENSE for license terms.