md-pdf-studio
v2.9.0
Published
A powerful CLI tool and Manifest V3 Browser Extension to convert Markdown files, text, or web pages into beautifully styled PDFs with Mermaid diagrams, LaTeX math, TOC, and themes. The CLI also writes Word (.docx) and EPUB.
Maintainers
Readme
📄 convert-md-to-pdf
Repeatable document builds from Markdown: one command turns the
.mdfiles in a repo into PDF, Word (.docx), EPUB or static HTML, on your own machine or in a CI job. Theme, cover page, table of contents, page numbers, running header/footer and watermark are set in a project.mdpdfrcfile, in each file's YAML front matter or on the command line, so every build of a document uses the same settings, and any error ends the run with exit code 1 so the job fails. PDF uses an installed Chrome, Edge or Chromium (or the one given with--browser); HTML, Word and EPUB need no browser.
The second way in is a Browser Extension (Manifest V3): drop .md files into the popup, paste text, or convert the page you are on, then save it as PDF or static HTML. Both share the 7 preset themes and the open-source fonts, and both render Mermaid diagrams, LaTeX math, GitHub callout alerts and custom CSS.
Official builds are listed at vannt-dev.github.io/official.html; anything else is not published by vannt-dev.
✨ Features
- 🧩 Browser Extension (Manifest V3):
- Drag & drop single or multiple
.mdfiles directly into the popup. - Auto-saved draft text in popup & conversion history list with 1-click re-open.
- Convert active web page or GitHub raw Markdown files with 1 click.
- Context menu integration: Right-click selected Markdown text or any page -> "Convert to PDF".
- Full-page Print Preview with live theme switching, Font Selector, Auto TOC, Custom CSS, and native PDF/HTML export.
- Page numbers and a running header/footer, set in the popup (off by default).
- Drag & drop single or multiple
- 📑 Auto Cover Page Generator: Generate elegant document report cover pages via YAML Front Matter (
cover: true) or--coverflag. The author and date labels are in English, or in Vietnamese withlang: viin the front matter. - 🔢 Page Numbers & Running Header/Footer:
--page-numbersprints "Page 3 of 12" at the foot of each page (--page-numbers simpleprints "3").--header "text"and--footer "text"print a line of text at the top and foot of each page, with{title},{author},{date},{page}and{pages}filled in (--header "{title}"prints the document title,""prints nothing). Both need their text right after the flag:md2pdf --header README.mdis refused, becauseREADME.mdis an input file.--page-numberstakesfullorsimpleas its value and nothing else, somd2pdf --page-numbers README.mdconvertsREADME.md. With both a footer and page numbers, the footer text sits left and the numbers right. The cover page is printed without them, but counts as page 1. All off by default; front matter keysheader,footerandpageNumbersdo the same. PDF only (the CLI and the extension); Word and EPUB leave them out. - 💧 Watermark:
--watermark DRAFTprints the text large, faint and diagonal across the middle of every page, cover included; long text gets smaller so it still fits. Front matterwatermark: Internaldoes the same, and--watermark ""turns it off for one run. PDF and HTML; Word and EPUB leave it out. - 📌 Dotted Leader Line Table of Contents (TOC): Auto-generates publication-grade TOC with dotted leader lines (
...) and clickable anchor links (--toc). - 🎨 7 Preset Themes:
modern(default),dark,academic,github,ebook,cyberpunk, andminimal. - 🔤 Open-Source Font Selector: 100% free under SIL OFL / Apache 2.0 (
Inter,Roboto,Lora,Merriweather,JetBrains Mono,Fira Code). - ⚡ Live Watch Mode & HTML Export: Real-time auto-recompilation on file changes (
-w, --watch) and direct static HTML export (-f, --format html). - 🚀 CLI & Batch Conversion: Convert single files or batch process directories with wildcard patterns.
- 🎨 Custom CSS Injection: Inject custom branding CSS stylesheets (
-c, --css custom.css). - 📊 Mermaid Diagrams: Sequence diagrams (with auto note wrapping), flowcharts, class diagrams, and gantt charts.
- 🌈 Syntax Highlighting: Fenced code blocks that name a language (
```js,```python,```diff, …) are coloured at build time with highlight.js — no CDN, so it also works offline and in static HTML export. Colours follow the theme's code block background. Works in the CLI and in the extension preview. - 📐 LaTeX Math Support:
$...$in the text and$$...$$blocks are drawn with KaTeX. Prices stay text: no space just inside the dollars and no digit right after the closing one ($5 and $10is not math). Code blocks are left alone. The extension ships KaTeX and its fonts, so math works offline there. - 📝 Footnotes:
text[^1]with[^1]: the noteanywhere in the file. Notes are numbered in the order they are first referenced, gathered at the end of the document, and linked both ways. Works in the CLI and in the extension preview. - 📘 Word & EPUB Export (CLI):
-f docxwrites a Word document and-f epuban EPUB 3 e-book, straight from the Markdown and without a browser. Headings, lists (nested, numbered from any start, task lists), tables with their alignment, code blocks, quotes, footnotes, links and local images become the real thing in each format — Word styles you can restyle, a chapter per top-level heading and a navigation menu in the EPUB.--toc,--cover, page size, orientation and margins apply to Word;--tocand--coverto EPUB. Themes, custom CSS, Mermaid diagrams and KaTeX math are for PDF and HTML only: a diagram or formula is kept as its source. An image on the web is not downloaded — it is named in Word and becomes a link in the EPUB — and a link to a neighbouring file keeps its text only. - 🔖 PDF Bookmarks (CLI): The PDF gets an outline (bookmarks) built from its headings, nested by level, so a PDF viewer's sidebar can jump to any section. On by default;
--no-outlineoroutline: falsein the front matter leaves it out. The extension prints through the browser's print dialog, which does not add bookmarks. - 📎 File Includes (CLI): A line that holds only
@import "chapters/intro.md"is replaced by that file, relative to the file the line is in. A Markdown file is inserted as Markdown (without its front matter) and may import further files; any other file —@import "src/app.js"— is inserted as a code block labelled with its extension. Lines inside a code block are left alone, a missing file or files that import each other stop the conversion with the file and line, and watch mode follows the imported files.--no-includeturns it off. - 🔒 Strict Mode (CLI):
--strictrefuses a document with broken references instead of writing a file with holes in it: a picture that cannot be loaded (a missing or unreadable file, by relative path, absolute path orfile:///address; for PDF also a web picture that does not answer), a link to a local file that does not exist, a link to an#anchorno heading has, and a footnote reference without a note. Every problem is listed with its file and line, also in imported files; that file is not written, the other inputs are still checked and converted, and the run ends with exit code 1. Works for PDF, HTML, Word and EPUB;"strict": truein.mdpdfrcturns it on for a repo. Code blocks and formulas are not searched. The anchors are those of the output: in PDF and HTML headings get them from--toc. - 💡 GitHub Callout Box Alerts: Support for
> [!NOTE],> [!TIP],> [!WARNING],> [!IMPORTANT], and> [!CAUTION]. - 💻 ASCII UI Mockups: Styled dark-theme boxes for terminal output & ASCII wireframe mockups.
🌐 Extension Installation & Usage
🛒 Direct Install from Chrome Web Store (Recommended)
You can install the official published extension directly with 1-click: 👉 Install Markdown to PDF Converter on Chrome Web Store
🛠️ Developer Unpacked Installation (Local Build):
- Clone or download this repository:
git clone https://github.com/vannt-dev/convert-md-to-pdf.git - Open your browser and navigate to
chrome://extensions(oredge://extensions). - Enable Developer mode (toggle in the top-right corner).
- Click Load unpacked (Tải tiện ích đã giải nén).
- Select the
extensiondirectory inside this repository (or loaddist/extension-latest.zip). - The Markdown to PDF Converter icon will appear in your browser toolbar!
💻 CLI Installation & Usage
Global Installation via npm / npx
The CLI is published on npm as md-pdf-studio:
npm install -g md-pdf-studioor run directly with npx:
npx md-pdf-studio input.mdA global install provides the md-pdf-studio command and the md2pdf and convert-md-to-pdf aliases.
PDF output uses a locally installed Google Chrome, Microsoft Edge or Chromium.
The npm package named
convert-md-to-pdfis an unrelated project; installmd-pdf-studiofor this tool.
CLI Examples:
# Convert a Markdown file with Cover Page, Auto TOC & Cyberpunk Theme
npx md-pdf-studio input.md --cover --toc -t cyberpunk --font "Fira Code" -o output.pdf
# Watch file and auto-recompile on save
npx md-pdf-studio input.md -w -f html
# Batch convert multiple files to an output directory
npx md-pdf-studio file1.md file2.md -o output_dir/
# Convert entire directory of .md files
npx md-pdf-studio ./docs/ -o ./dist/
# Word document with a cover page and a table of contents
npx md-pdf-studio report.md -f docx --cover --toc
# EPUB e-book, one chapter per top-level heading
npx md-pdf-studio book.md -f epub -o book.epub
# Markdown from stdin ("-"): the output file must be named with -o
cat notes.md | npx md-pdf-studio - -o notes.pdfWith - as the input, the Markdown is read from stdin. It has no file name, so -o <file> must name the output file, and - must be the only input (no --watch). Relative paths in it (pictures, @import) are resolved from the current folder, as if the Markdown were a file there.
A book kept as one file per chapter is one document with includes:
---
title: Handbook
toc: true
---
# Handbook
@import "chapters/01-intro.md"
@import "chapters/02-setup.md"
## Example config
@import "examples/config.yml"🛠️ CLI Options
| Flag | Alias | Description | Default |
| :--- | :--- | :--- | :--- |
| -o, --output <path>| | Output file path or target directory | Auto-derived |
| -f, --format <format>| | Output format: pdf, html, docx, epub | pdf |
| -w, --watch | | Live watch input file and auto-recompile on change | false |
| -t, --theme <theme> | | Theme: modern, dark, academic, github, ebook, cyberpunk, minimal | modern |
| --font <font> | | Font family: Inter, Roboto, Lora, Merriweather, JetBrains Mono, Fira Code | Inter |
| --cover | | Auto-generate document report Cover Page | false |
| --toc | | Auto-generate Table of Contents with Dotted Leader Lines | false |
| --page-numbers [style] | | Page numbers at the foot of each page: full ("Page 3 of 12") or simple ("3"); any other next argument stays an input | off (full when given alone) |
| --header <text> | | Running header; {title}, {author}, {date}, {page}, {pages} are filled in; "" for none | off |
| --footer <text> | | Running footer, same placeholders; "" for none | off |
| --watermark <text> | | Faint diagonal text across every page, e.g. DRAFT; "" for none | off |
| -p, --page-size <size>| | Paper size: A4, Letter, A3, Legal | A4 |
| -l, --landscape | | Use landscape page orientation | false |
| -m, --margin <margin>| | Custom page margin (e.g. 14mm 12mm 16mm 12mm) | 14mm 12mm 16mm 12mm |
| -c, --css <path> | | Custom CSS stylesheet file path to inject | |
| -k, --keep-html | | Keep temporary HTML file after conversion | false |
| --no-mermaid | | Disable Mermaid diagram rendering | false |
| --no-katex | | Disable KaTeX math formula rendering | false |
| --no-highlight | | Disable syntax highlighting of code blocks | false |
| --no-include | | Leave @import "file" lines as they are instead of inserting the file | false |
| --no-outline | | Leave out the PDF bookmarks (outline) made from the headings | false |
| --strict | | Fail, writing nothing, when a picture, a linked local file, an #anchor or a footnote is missing | false |
| -b, --browser <path> | | Chrome, Edge or Chromium executable to print the PDF with | Found automatically |
| --config <path> | | Project config file to read (see below) | .mdpdfrc or .mdpdfrc.json, if found |
| --no-config | | Read no project config file | |
Project config (.mdpdfrc)
A repo can keep its build settings in a .mdpdfrc (or .mdpdfrc.json) file, so every run, on a laptop or in CI, uses the same ones without repeating the flags. The file is plain JSON; its keys are the long option names in camelCase:
{
"format": "pdf",
"output": "dist",
"theme": "github",
"toc": true,
"pageNumbers": "simple",
"footer": "{title}",
"watermark": "DRAFT"
}Keys: output, format, theme, font, cover, pageSize, landscape, margin, toc, pageNumbers, header, footer, watermark, css, keepHtml, mermaid, katex, highlight, include, outline, strict, browser. Paths (output, css, browser) are relative to the config file's folder.
- Where it is found: in the current folder, else in the nearest parent folder, stopping at the repository root (the folder that holds
.git). In one folder.mdpdfrcis used before.mdpdfrc.json.--config <path>reads another file instead;--no-configreads none. - Which setting wins: command-line flags, then the file's front matter, then
.mdpdfrc, then the built-in defaults. So.mdpdfrcsets the repo's defaults, one document can change them in its front matter, and a flag changes them for one run. - Mistakes: an unknown key is ignored with a warning. A file that is not valid JSON, or a value of the wrong kind (
"toc": "yes"), stops the run with exit code 1.
📄 Front Matter Options
You can specify conversion settings directly inside your .md files using YAML Front Matter. A flag given on the command line wins over the front matter, and the front matter wins over .mdpdfrc (see Project config):
---
title: "Quarterly Financial Report"
subtitle: "Q3 Fiscal Summary"
author: "Engineering Team"
date: "2026-08-11"
cover: true
toc: true
theme: github
font: Inter
pageSize: A4
landscape: false
highlight: true
# document language (default en): cover labels and the page's lang
lang: en
# running header and footer; header: true also means the title
header: "{title}"
footer: "Engineering Team"
# full ("Page 3 of 12"), simple ("3") or false
pageNumbers: full
# faint diagonal text on every page
watermark: DRAFT
---
# Document Executive Summary
...🌿 Branching & Automated Release Workflow
🔀 Branching Strategy
main: The default branch. Changes arrive through pull requests from short-lived feature branches, and pushing a version tagv*frommaintriggers a release.
🚀 Automated Release Pipeline
Whenever a version tag v* is pushed, GitHub Actions (.github/workflows/release.yml) builds from that tag and automatically:
- Checks that the tag matches the version in
package.jsonandextension/manifest.json, then runs the full unit test suite (npm test). - Bundles cross-platform extension zip artifacts (
dist/extension-vX.Y.Z.zip). - Auto-generates release notes from commit history.
- Publishes a new official GitHub Release with downloadable ZIP binaries attached!
- Publishes
md-pdf-studioto npm with provenance, through npm trusted publishing (no token secret). A version already on npm is skipped.
To release an existing tag again (for example after a failed run), run the workflow manually with tag_name.
💡 1-Click CLI Release Command
You can also bump version and trigger a release with a single CLI command:
npm run release <version|patch|minor|major>
# Example: npm run release 1.2.0Please review our Git Commit & Push Workflow Guide (GIT_WORKFLOW.md) for conventional commit guidelines and pre-commit checks.
📁 Project Architecture
convert-md-to-pdf/
├── bin/
│ └── cli.js # CLI executable with watch & format options
├── src/
│ ├── cli/ # Command line helpers: option checks, .mdpdfrc config file
│ ├── core/ # Shared modular conversion engine
│ │ ├── themes/ # Modular Theme CSS collection
│ │ │ ├── index.js # Theme registry & font override builder
│ │ │ ├── cover.js # Cover page CSS
│ │ │ ├── modern.js # Modern blue theme
│ │ │ ├── dark.js # Dark slate theme
│ │ │ ├── academic.js # Academic serif theme
│ │ │ ├── github.js # GitHub light theme
│ │ │ ├── ebook.js # E-Book paper theme
│ │ │ ├── cyberpunk.js # Cyberpunk neon dark theme
│ │ │ └── minimal.js # Minimal monochrome theme
│ │ ├── frontmatter.js # YAML front matter parser
│ │ ├── include.js # @import "file" expansion
│ │ ├── docmodel.js # Format-neutral document model (blocks of flat runs)
│ │ ├── docx.js # Word (.docx) writer
│ │ ├── epub.js # EPUB 3 writer
│ │ ├── images.js # Local image reading & sizes
│ │ ├── zip.js # ZIP container writer for docx/epub
│ │ ├── cover.js # Cover page generator
│ │ ├── toc.js # Dotted leader line TOC generator
│ │ ├── sanitizer.js # HTML sanitizer & escaping
│ │ ├── utils.js # Preprocessors & helper re-exports
│ │ ├── parser.js # Pipeline parser (Markdown -> HTML)
│ │ ├── templates.js # HTML document template builder
│ │ ├── pagemarks.js # Page numbers & running header/footer CSS (shared with the extension)
│ │ └── index.js # Main library API entrypoint
│ ├── cli/ # Command line option checks (options.js)
│ └── browser/ # Headless browser rendering engine
│ └── renderer.js # Runs installed Chrome/Edge headless (--print-to-pdf) & PDF worker pool
├── extension/ # Browser Extension (Manifest V3)
│ ├── manifest.json
│ ├── background/ # Service worker & context menus
│ ├── content/ # Content script for raw MD pages
│ ├── popup/ # Extension Popup UI (Batch file, Paste, Page, History)
│ ├── preview/ # Print Preview & PDF/HTML export page
│ ├── lib/ # Vendor libraries (marked, mermaid, katex) & code shared with the CLI
│ └── icons/ # Extension icons (16, 48, 128)
├── tests/ # Standalone test suite (`npm test`)
│ └── index.test.js
├── dist/ # Built Chrome Extension zip artifacts
├── examples/ # Usage examples & custom CSS templates
├── package.json
├── README.md
├── PRIVACY_POLICY.md
└── GIT_WORKFLOW.md📝 License
Distributed under the MIT License. See LICENSE for details.
