npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

Readme

📄 convert-md-to-pdf

Repeatable document builds from Markdown: one command turns the .md files 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 .mdpdfrc file, 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.

Chrome Web Store Chrome Web Store users npm version npm downloads Browser Extension License Official vannt-dev build


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 .md files 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).
  • 📑 Auto Cover Page Generator: Generate elegant document report cover pages via YAML Front Matter (cover: true) or --cover flag. The author and date labels are in English, or in Vietnamese with lang: vi in the front matter.
  • 🔢 Page Numbers & Running Header/Footer: --page-numbers prints "Page 3 of 12" at the foot of each page (--page-numbers simple prints "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.md is refused, because README.md is an input file. --page-numbers takes full or simple as its value and nothing else, so md2pdf --page-numbers README.md converts README.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 keys header, footer and pageNumbers do the same. PDF only (the CLI and the extension); Word and EPUB leave them out.
  • 💧 Watermark: --watermark DRAFT prints the text large, faint and diagonal across the middle of every page, cover included; long text gets smaller so it still fits. Front matter watermark: Internal does 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, and minimal.
  • 🔤 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 $10 is 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 note anywhere 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 docx writes a Word document and -f epub an 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; --toc and --cover to 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-outline or outline: false in 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-include turns it off.
  • 🔒 Strict Mode (CLI): --strict refuses 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 or file:/// 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 #anchor no 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": true in .mdpdfrc turns 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):

  1. Clone or download this repository:
    git clone https://github.com/vannt-dev/convert-md-to-pdf.git
  2. Open your browser and navigate to chrome://extensions (or edge://extensions).
  3. Enable Developer mode (toggle in the top-right corner).
  4. Click Load unpacked (Tải tiện ích đã giải nén).
  5. Select the extension directory inside this repository (or load dist/extension-latest.zip).
  6. 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-studio

or run directly with npx:

npx md-pdf-studio input.md

A 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-pdf is an unrelated project; install md-pdf-studio for 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.pdf

With - 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 .mdpdfrc is used before .mdpdfrc.json. --config <path> reads another file instead; --no-config reads none.
  • Which setting wins: command-line flags, then the file's front matter, then .mdpdfrc, then the built-in defaults. So .mdpdfrc sets 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 tag v* from main triggers a release.

🚀 Automated Release Pipeline

Whenever a version tag v* is pushed, GitHub Actions (.github/workflows/release.yml) builds from that tag and automatically:

  1. Checks that the tag matches the version in package.json and extension/manifest.json, then runs the full unit test suite (npm test).
  2. Bundles cross-platform extension zip artifacts (dist/extension-vX.Y.Z.zip).
  3. Auto-generates release notes from commit history.
  4. Publishes a new official GitHub Release with downloadable ZIP binaries attached!
  5. Publishes md-pdf-studio to 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.0

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