Skip to content

Advanced: settings, options and details for people who want full control. Most people only need Studio.

Command line ​

For people who export from a terminal, a script or CI, and want every command and flag.

sh
npx -y markdown-pdf-export report.md

This 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 ​

CommandWhat it does
markdown-pdf-export <file.md> [options]Export one file.
markdown-pdf-exportIn 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-browserDownload Chromium (about 200 MB). See Browser.
markdown-pdf-export mcpRun as an assistant tool server. See Assistant tools.
markdown-pdf-export --help, --versionShow 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.

OptionValue
-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-backgroundPrint 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-stylesUse the built-in stylesheet (on by default).
--highlightColour code blocks (on by default).
--highlight-style <theme.css>Code colour theme, for example monokai.css.
--breaksEvery new line is a line break.
--emojiTurn :shortcodes: into emoji (on by default).
--mathDraw $...$ maths with KaTeX.
--math-options <json>'{"macros":{"\\RR":"\\mathbb{R}"}}'
--tocReplace [[toc]] with a table of contents.
--toc-options <json>'{"level":[2,3],"list_type":"ol"}'
--heading-anchorsGive headings ids for links.
--header <json>, --footer <json>Replace the header or footer, for example '{"center_text":"Page {page}"}'.
--display-header-footerShow the header and footer area. Not needed when a header or footer is set.
--open-after-exportOpen the PDF when done.
--settings <file.json or json>Use these settings instead of the user file.
--watchExport 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 ​

VariableValue
MARKDOWN_PDF_SETTINGSInline JSON or a path to a JSON file, used instead of the user settings file.
MARKDOWN_PDF_BROWSERchrome, msedge, chromium, or the path to a browser. See Browser.
MARKDOWN_PDF_DEBUG1 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.

CodeMeaning
0Success.
1The export failed (file not found, no browser, rendering error). doctor also returns 1 when something needs fixing.
2Wrong usage: unknown option, bad value, missing file.

Scripts ​

Export every Markdown file of a folder into build/:

sh
mkdir -p build
for f in docs/*.md; do
  npx -y markdown-pdf-export "$f" -o "$PWD/build/$(basename "${f%.md}").pdf"
done

CI ​

GitHub Actions on Ubuntu already has Google Chrome, so this is enough:

yaml
- 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.

Released under the MIT License.