Command line
For people who export from a terminal, a script or CI, and want every command and flag.
npx -y markdown-pdf-export report.mdThis writes report.pdf next to report.md and prints its path. npx -y downloads the package the first time and reuses it after that. After npm install -g markdown-pdf-export, the command is simply markdown-pdf-export. Node.js 20 or newer is needed.
Commands
| Command | What it does |
|---|---|
markdown-pdf-export <file.md> [options] | Export one file. |
markdown-pdf-export | In a terminal: a short menu (set up an editor, open Studio, check, help). |
markdown-pdf-export studio [--project] [--file <doc.md>] [--port <n>] [--no-open] | Open Studio. --project edits ./.markdown-pdf.json; --file previews your own document; --no-open only prints the link. |
markdown-pdf-export init [--look <n>] [--font <n>] [--template <n>] [--project] [--force] [--list] | Create the settings file. See Settings file. |
markdown-pdf-export setup [zed|vscode|cursor|claude-code|claude-desktop|all] [--write] | Print the editor task and assistant entries for the editors found. --write creates missing files and runs the editor's own command; it never changes an existing file. |
markdown-pdf-export doctor [file.md] [--json] | Check Node, the browser and the settings files. |
markdown-pdf-export install-browser | Download Chromium (about 200 MB). See Browser. |
markdown-pdf-export mcp | Run as an assistant tool server. See Assistant tools. |
markdown-pdf-export --help, --version | Show help or the version. |
Export options
Each option is also a settings key (written with _ instead of -). An option given on the command line wins over the settings files; front matter wins over both.
| Option | Value |
|---|---|
-o, --output, --output-path <file.pdf> | Output file. |
--page-format <name> | A4, Letter, Legal, Tabloid, Ledger, A0 to A6. |
--orientation <name> | portrait or landscape. |
--margin <size or json> | 20mm for all sides, or '{"top":"25mm"}'. |
--scale <n> | Zoom of the content, default 1. |
--page-ranges <ranges> | Pages to keep, for example '1-5, 8'. |
--print-background | Print background colours (on by default). |
--font-family <css> | Text font, as a CSS font list. |
--heading-font-family <css> | Title font. |
--stylesheet-path <file.css> | Your CSS, relative to the Markdown file. |
--include-default-styles | Use the built-in stylesheet (on by default). |
--highlight | Colour code blocks (on by default). |
--highlight-style <theme.css> | Code colour theme, for example monokai.css. |
--breaks | Every new line is a line break. |
--emoji | Turn :shortcodes: into emoji (on by default). |
--math | Draw $...$ maths with KaTeX. |
--math-options <json> | '{"macros":{"\\RR":"\\mathbb{R}"}}' |
--toc | Replace [[toc]] with a table of contents. |
--toc-options <json> | '{"level":[2,3],"list_type":"ol"}' |
--heading-anchors | Give headings ids for links. |
--header <json>, --footer <json> | Replace the header or footer, for example '{"center_text":"Page {page}"}'. |
--display-header-footer | Show the header and footer area. Not needed when a header or footer is set. |
--open-after-export | Open the PDF when done. |
--settings <file.json or json> | Use these settings instead of the user file. |
--watch | Export again when the file or a settings file changes. |
Yes/no options accept --toc, --toc=true, --toc=false and --no-toc. JSON values need single quotes in a POSIX shell.
What each option does in detail: All settings.
Where the PDF goes
Without -o, the PDF goes next to the Markdown file, or into output_directory when the settings set one (relative to the Markdown file). A relative -o path is also relative to the Markdown file's folder, not to the current folder. Missing folders are created.
--settings
--settings takes a JSON file or inline JSON. It replaces the user file (and MARKDOWN_PDF_SETTINGS); a project .markdown-pdf.json still applies on top. It reads the same keys as a settings file, presets look, font, heading_font and template included.
--watch
npx -y markdown-pdf-export notes.md --watch exports once, then again each time you save the Markdown file or a settings file it uses. Stop with Ctrl+C.
Environment variables
| Variable | Value |
|---|---|
MARKDOWN_PDF_SETTINGS | Inline JSON or a path to a JSON file, used instead of the user settings file. |
MARKDOWN_PDF_BROWSER | chrome, msedge, chromium, or the path to a browser. See Browser. |
MARKDOWN_PDF_DEBUG | 1 writes markdown-pdf-debug.log in the temporary folder; a file path writes there. |
Output and exit codes
On success, the only thing printed on standard output is the PDF path. Messages and errors go to standard error.
| Code | Meaning |
|---|---|
0 | Success. |
1 | The export failed (file not found, no browser, rendering error). doctor also returns 1 when something needs fixing. |
2 | Wrong usage: unknown option, bad value, missing file. |
Scripts
Export every Markdown file of a folder into build/:
mkdir -p build
for f in docs/*.md; do
npx -y markdown-pdf-export "$f" -o "$PWD/build/$(basename "${f%.md}").pdf"
doneCI
GitHub Actions on Ubuntu already has Google Chrome, so this is enough:
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npx -y markdown-pdf-export doctor || npx -y markdown-pdf-export install-browser
- run: npx -y markdown-pdf-export README.md -o "$PWD/dist/README.pdf"doctor fails when no browser is found, which triggers the download. Commit a .markdown-pdf.json to the repository so CI uses the same settings as you.
