@threepenny/md2pdf 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Threepenny Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# md2pdf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert Markdown to beautifully styled PDFs. This is the rendering engine and macOS command-line tool behind **[md2pdf.me](https://md2pdf.me)**, the free online converter.
+
+- **Just want a PDF?** Use [md2pdf.me](https://md2pdf.me): nothing to install, and your text never leaves your browser.
+- **On a Mac and comfortable with a terminal?** Install the command-line tool below. It adds a Finder right-click action and a keyboard shortcut.
+- **Building something?** Use the renderer and styles as a dependency, to make PDFs ([Using the renderer](#using-the-renderer)) or to show Markdown in your own pages ([Embedding in a web page](#embedding-in-a-web-page)).
+
+Supports GitHub-flavored Markdown: tables, task lists, footnotes, emoji shortcodes, syntax-highlighted code, raw HTML, GitHub alerts and Obsidian callouts (`> [!NOTE]`, `> [!tip] Custom title`), Obsidian wikilinks and embeds (`[[Note|alias]]` prints as plain text, `![[image.png]]` as an image, and an embedded note as a placeholder naming it), YAML front matter (left out of the PDF; its `title:` names the document when there is no `#` heading), and page breaks (`<div class="page-break"></div>`). Six print styles are included: `github`, `classic`, `academic`, `modern`, `report` and `resume`.
+
+# Command-line tool (macOS)
+
+Markdown is rendered to HTML with [markdown-it](https://github.com/markdown-it/markdown-it) and printed to PDF by headless Chrome.
+
+## Install
+
+Requires Node.js and Google Chrome (Chromium, Edge or Brave also work).
+
+```sh
+./install.sh
+```
+
+This installs:
+
+- `~/.local/bin/md2pdf` — the command-line tool
+- **Convert to PDF** Quick Action — right-click any `.md` file in Finder → **Quick Actions → Convert to PDF**
+- **⌃⌥⌘P** keyboard shortcut — select `.md` files in Finder and press it
+
+Re-run `install.sh` if you move this folder or remove the Node version it was installed with. `./uninstall.sh` removes all of it.
+
+To use a different shortcut, pass it when installing (`@` ⌘, `~` ⌥, `^` ⌃, `$` ⇧), or set it to empty to skip:
+
+```sh
+MD2PDF_SHORTCUT='@$p' ./install.sh   # ⇧⌘P
+MD2PDF_SHORTCUT= ./install.sh        # no shortcut
+```
+
+You can also change it later in **System Settings → Keyboard → Keyboard Shortcuts → Services → Files and Folders → Convert to PDF**.
+
+## Usage
+
+```sh
+md2pdf notes.md                 # → notes.pdf next to notes.md
+md2pdf *.md                     # convert several at once
+md2pdf notes.md -o ~/out.pdf    # choose the output path
+md2pdf notes.md -p A4           # page size (default: Letter)
+md2pdf notes.md --open          # open the PDF when done
+md2pdf notes.md -s classic      # use a specific style
+md2pdf notes.md --css my.css    # layer extra CSS on top of the style
+md2pdf notes.md --html          # also write the intermediate HTML (for tweaking CSS)
+```
+
+From Finder, a single file opens in Preview when done; multiple files show a notification.
+
+## Styles
+
+| Style     | Look |
+| --------- | ---- |
+| `github`  | GitHub's Markdown rendering: sans-serif, boxed tables, GitHub syntax colors |
+| `classic` | Book-like: Iowan Old Style serif, justified text, small-caps headings, ruled tables, page numbers |
+| `academic` | Journal article: Palatino, numbered sections (1, 1.1, 1.1.1), booktabs tables, journal-style footnotes |
+| `modern`  | Clean sans-serif (Avenir Next / Segoe UI), generous whitespace, one blue accent |
+| `report`  | Business or technical report: title block from the first heading, running header with the title, "Page N of M" footers, gridded tables |
+| `resume`  | Compact and one-page friendly: the first heading is your name, the paragraph after it your contact line, `##` headings are ruled section dividers |
+
+Switch the default style — used by the Finder Quick Action, the keyboard shortcut and the `md2pdf` command:
+
+```sh
+./set-style.sh            # list styles (* marks the default)
+./set-style.sh classic    # make classic the default
+```
+
+The choice is saved in `~/.config/md2pdf/config.json`. Use `md2pdf -s <style>` to override it for one conversion.
+
+### Adding a style
+
+Styles are registered in the `STYLES` map in `bin/md2pdf.js`; each is a list of CSS files inlined into the page in order. A style has two files:
+
+- `styles/<name>.css`, the on-screen look. The content is wrapped in `<article class="markdown-body">`, and every rule must be scoped to it: no `:root`, `html`, `body` or `@page` rules, so the style can be embedded in other pages.
+- `styles/print/<name>.css`, the print-only rules: `@page` margins, running headers and page numbers, and `html, body` margins.
+
+Register it in `STYLES` and add its page margin to `pageMargins` in `lib/styles.js`, and it's available to `-s` and `set-style.sh`. Use `md2pdf --html` to get the intermediate HTML for tweaking in a browser. For one-off tweaks, `--css` is enough.
+
+The text of the document's first `#` heading (empty if there is none) is available to page margin boxes as `var(--document-title)`, e.g. `@top-left { content: var(--document-title); }`, as the `report` style does.
+
+A style declares the [shared variables](#variables) in its first rule, `:where(.markdown-body) { … }`, with a comment saying what each one does there, and uses them for every size, gap, color and font they name. Spacing follows two patterns: `line-height: calc(1 + 0.55 * var(--md2pdf-leading))` and `margin: calc(1.8em * var(--md2pdf-space)) 0 …`. `npm test` checks that each variable is declared and changes the document. Page margins aren't included: they stay in the style's `@page` rule, in `styles/print/<name>.css`.
+
+# Using the renderer
+
+The Markdown renderer and the styles are on npm as `@threepenny/md2pdf`. They can also be installed straight from a GitHub release tag (`npm install github:jbrecht/md2pdf#<tag>`).
+
+```sh
+npm install @threepenny/md2pdf highlight.js
+```
+
+To make a printable page, pass `buildDocument` a style's on-screen and print stylesheets, in that order:
+
+```js
+import hljs from 'highlight.js';
+import { createRenderer, buildDocument, titleOf } from '@threepenny/md2pdf/render';
+
+const md = createRenderer({ hljs });
+const html = buildDocument({
+  bodyHtml: md.render(markdown),
+  title: titleOf(markdown, 'document'),
+  css: classicCss + printCss, // the text of styles/classic.css and styles/print/classic.css
+  pageSize: 'A4',
+});
+```
+
+| Export | What it is |
+| ------ | ---------- |
+| `@threepenny/md2pdf/render` | `createRenderer({ hljs, math?, html? })`, `buildDocument(...)`, `titleOf(markdown, fallback)` (the first `#` heading, else the front matter's `title:`, else the fallback), `escapeHtml(s)`, `cssString(s)`, `headingText(html)` |
+| `@threepenny/md2pdf/styles` | `pageMargins`: each style's `@page` margin at default spacing, e.g. `pageMargins.classic` is `'1in 1.1in 0.9in'` |
+| `@threepenny/md2pdf/styles/<name>.css` | Each style's on-screen look, scoped to `.markdown-body`. For `github`, load `github-markdown-css/github-markdown-light.css` first |
+| `@threepenny/md2pdf/styles/print/<name>.css` | Each style's print rules: page margins, running headers and page numbers. Load it after the on-screen file, only in a page that holds nothing but the document |
+
+`createRenderer` takes the highlight.js instance to use (so you can pass a smaller bundle such as `highlight.js/lib/common`) and, optionally, `math: { texmath, katex }` from `markdown-it-texmath` and `katex` to render `\( \)`, `\[ \]`, `$` and `$$` formulas; formulas also need KaTeX's stylesheet, `katex/dist/katex.min.css`. Raw HTML in the Markdown is passed through unless you pass `html: false`, which escapes it; page breaks (`<div class="page-break"></div>`) are raw HTML, so they then print as text.
+
+### Variables
+
+Every style takes the same variables, set on the `.markdown-body` element. A `--css` file for the CLI can set them too, e.g. `.markdown-body { --md2pdf-leading: 0.8; --md2pdf-space: 0.75; }` to tighten a document. Each style's file lists its defaults.
+
+| Variable | What it sets |
+| -------- | ------------ |
+| `--md2pdf-font-size` | The body text size; headings and smaller text scale with it. An absolute length (`pt`, `px` or `rem`), since `em` and `%` would compound. 11pt, or 10.5pt in `modern` and `report` and 10pt in `resume` |
+| `--md2pdf-leading` | Line spacing: scales each line height's excess over 1. 1 as designed |
+| `--md2pdf-space` | The vertical gaps between blocks. 1 as designed |
+| `--md2pdf-background` | The document's background, white |
+| `--md2pdf-text` | Body text |
+| `--md2pdf-muted` | Secondary text, such as footnotes and captions |
+| `--md2pdf-accent` | The accent color: links, headings, list markers or callouts, depending on the style |
+| `--md2pdf-rule` | Rules, borders and table lines (every style but `github`) |
+| `--md2pdf-surface` | A tinted background: inline code and code blocks in `classic` and `modern`, and callouts too in `classic`; inline code, quotes and table headings in `report`. The other styles don't use it |
+| `--md2pdf-font` | The body font |
+| `--md2pdf-heading-font` | The heading font: the body font, except in `report`, where it's Helvetica and also sets callout titles and tables |
+| `--md2pdf-code-font` | The code font |
+
+The styles are designed for light pages; a dark page isn't supported. Page headers and footers in a PDF keep the style's own fonts and colors.
+
+### Upgrading from 1.x
+
+- The variables are renamed (`--leading` is now `--md2pdf-leading`; the body font, `--serif` or in `modern` and `resume` `--sans`, is `--md2pdf-font`; `report`'s `--sans` is `--md2pdf-heading-font`; and so on) and must be set on `.markdown-body`. A value set on `:root`, as the 1.x README suggested, no longer reaches the document.
+- The print rules moved to `styles/print/<name>.css`. Pass `buildDocument` both files, or PDFs lose their margins, running headers and page numbers.
+- The package is `@threepenny/md2pdf`, so imports change from `md2pdf/…` to `@threepenny/md2pdf/…`, unless you install it under its old name (`npm install md2pdf@npm:@threepenny/md2pdf`).
+- The `github` style includes highlight.js's GitHub theme, so you no longer need to load `highlight.js/styles/github.css`.
+
+## Embedding in a web page
+
+Used inside your own pages, md2pdf is a Markdown-to-HTML renderer rather than a PDF exporter: you get its callouts, wikilinks, math, code highlighting and styles, styled to match your site. A style's on-screen stylesheet only styles the element you render into, `class="markdown-body"`. It sets nothing on `:root`, `html` or `body` and has no `@page` rules, so the rest of your page looks and prints as before. Leave out the print stylesheet: it would take over your page's printing.
+
+To see it working, run `npm run demo` in this repo and open http://localhost:3900/demo/. The [demo](demo/index.html) is one static page: an editor, a style picker, and controls that override the size, spacing and accent of its one document. It needs no build step. An import map loads the renderer's dependencies from a CDN instead, so it needs a network connection. It does need a web server, because browsers won't load JavaScript modules from a page opened as a file.
+
+With a bundler such as Vite:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Notes</title>
+  <link rel="stylesheet" href="/node_modules/@threepenny/md2pdf/styles/classic.css">
+  <style>
+    /* Your site's look: on .markdown-body for every document, or on one of them. */
+    .markdown-body { --md2pdf-font-size: 12pt; --md2pdf-font: Georgia, serif; }
+    #rendered-notes { --md2pdf-accent: #0b5394; --md2pdf-space: 0.75; }
+  </style>
+</head>
+<body>
+  <h1>My site</h1>
+  <article id="rendered-notes" class="markdown-body"></article>
+  <script type="module">
+    import hljs from 'highlight.js/lib/common';
+    import { createRenderer } from '@threepenny/md2pdf/render';
+
+    // html: false escapes raw HTML, for Markdown you didn't write yourself.
+    const md = createRenderer({ hljs, html: false });
+    const markdown = '# Notes\n\n> [!tip] Rendered by md2pdf\n> With **callouts**, `code` and [[wikilinks]].\n\n<b>Escaped</b>';
+    document.getElementById('rendered-notes').innerHTML = md.render(markdown);
+  </script>
+</body>
+</html>
+```
+
+Set the [variables](#variables) on the `.markdown-body` element itself, with any selector or inline (`<article class="markdown-body" style="--md2pdf-font-size: 10pt">`). The style declares its defaults with no specificity, so your rule wins wherever it appears. A value set on `:root` or another element around the document doesn't reach it. One page can hold several documents in the same style, each with its own overrides, but not two different styles.
+
+The document paints its own background, so on a page that isn't white, give it some padding. Your page's own CSS still applies inside the document, for whatever the style doesn't set: a global `strong { color: #c00 }` reddens bold text in the document too. A highlight.js theme on your page is the exception: the styles keep it out of the document's code blocks. Headings get ids from their text (`# Notes` becomes `id="notes"`) so `[[#Notes]]` links work, so give your own elements ids that a heading won't produce.
+
+For Markdown you didn't write, render with `html: false` and also run the output through a sanitizer such as DOMPurify before inserting it. `html: false` escapes raw HTML, and markdown-it refuses `javascript:`, `vbscript:`, `file:` and non-image `data:` URLs in links and images. Neither is enough alone yet ([#32](https://github.com/jbrecht/md2pdf/issues/32)):
+
+- If other code on your page uses markdown-it-task-lists with `labelAfter`, that plugin's shared settings let raw HTML through md2pdf's task-list items.
+- Headings become element ids (`# config` gives `id="config"`), which can shadow globals or ids your own scripts rely on.
+- Images load from any URL the author chooses. A Content Security Policy's `img-src` limits that.
+- With math enabled, a formula can draw outside the document, so clip the element you render into (`overflow: hidden`).
+
+# Development
+
+```sh
+npm install
+npm test      # end-to-end tests against test/fixtures
+npm run demo  # the embedding demo, at http://localhost:3900/demo/
+```
+
+Set `CHROME_PATH` to use a specific browser binary.
+
+# License
+
+[MIT](LICENSE) © 2026 Threepenny Labs LLC

package/bin/md2pdf.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// md2pdf: convert Markdown files to PDF using headless Chrome.
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { createRequire } from 'node:module';
+
+import hljs from 'highlight.js';
+import { buildDocument, createRenderer, titleOf } from '../lib/render.js';
+
+const require = createRequire(import.meta.url);
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Each style is a list of CSS files inlined into the page, in order: its on-screen styles, then its
+// print rules. To add a style, add both files, register it here and add its page margin to lib/styles.js;
+// set-style.sh picks it up.
+const styleFiles = (name, ...before) => [...before, join(ROOT, 'styles', `${name}.css`), join(ROOT, 'styles', 'print', `${name}.css`)];
+const STYLES = {
+  github: styleFiles('github', require.resolve('github-markdown-css/github-markdown-light.css')),
+  classic: styleFiles('classic'),
+  academic: styleFiles('academic'),
+  modern: styleFiles('modern'),
+  report: styleFiles('report'),
+  resume: styleFiles('resume'),
+};
+const FALLBACK_STYLE = 'github';
+
+// Settings shared by the CLI, Finder Quick Action and keyboard shortcut.
+const CONFIG_PATH =
+  process.env.MD2PDF_CONFIG ??
+  join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'md2pdf', 'config.json');
+
+const CHROME_CANDIDATES = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+];
+
+const usage = (defaultStyle) => `Usage: md2pdf [options] <file.md>...
+       md2pdf --set-style <name>
+       md2pdf --list-styles
+
+Converts each Markdown file to a PDF saved next to it.
+
+Options:
+  -o, --output <file>    Output path (only with a single input file)
+  -s, --style <name>     Style to use (${Object.keys(STYLES).join(', ')}; default: ${defaultStyle})
+      --css <file>       Extra CSS file applied after the style
+  -p, --page-size <size> Letter, A4, Legal, ... (default: Letter)
+      --open             Open the PDF when done
+      --html             Also write the intermediate .html (for debugging styles)
+      --set-style <name> Make <name> the default style (also used by the Finder Quick Action)
+      --list-styles      List styles, marking the default
+  -h, --help             Show this help
+
+Environment:
+  CHROME_PATH            Path to a Chrome/Chromium binary to use
+  MD2PDF_CONFIG          Config file (default: ${CONFIG_PATH})`;
+
+function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch (err) {
+    console.error(`md2pdf: ignoring unreadable config ${CONFIG_PATH}: ${err.message}`);
+    return {};
+  }
+}
+
+function writeConfig(config) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+function unknownStyle(name) {
+  console.error(`md2pdf: unknown style "${name}". Available: ${Object.keys(STYLES).join(', ')}`);
+  process.exit(2);
+}
+
+function findChrome() {
+  if (process.env.CHROME_PATH) return process.env.CHROME_PATH;
+  const found = CHROME_CANDIDATES.find((p) => existsSync(p));
+  if (!found) throw new Error('Could not find Chrome. Install Google Chrome or set CHROME_PATH.');
+  return found;
+}
+
+function buildHtml({ markdown, title, baseDir, style, extraCss, pageSize }) {
+  const css = [...STYLES[style], ...(extraCss ? [extraCss] : [])]
+    .map((f) => readFileSync(f, 'utf8'))
+    .join('\n');
+  return buildDocument({
+    bodyHtml: createRenderer({ hljs }).render(markdown),
+    title,
+    css,
+    pageSize,
+    // <base> makes relative image/link paths resolve against the Markdown file's folder.
+    head: `<base href="${pathToFileURL(baseDir + '/').href}">`,
+  });
+}
+
+function runChrome(chrome, htmlPath, pdfPath) {
+  // A throwaway profile keeps headless Chrome separate from any Chrome you have open.
+  const profile = mkdtempSync(join(tmpdir(), 'md2pdf-chrome-'));
+  const args = [
+    '--headless',
+    '--disable-gpu',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--allow-file-access-from-files',
+    `--user-data-dir=${profile}`,
+    '--no-pdf-header-footer',
+    '--virtual-time-budget=10000',
+    `--print-to-pdf=${pdfPath}`,
+    pathToFileURL(htmlPath).href,
+  ];
+  return new Promise((resolvePromise, reject) => {
+    const proc = spawn(chrome, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    proc.stderr.on('data', (d) => (stderr += d));
+    proc.on('error', reject);
+    proc.on('close', (code) => {
+      rmSync(profile, { recursive: true, force: true });
+      if (code === 0 && existsSync(pdfPath)) resolvePromise();
+      else reject(new Error(`Chrome failed (exit ${code}):\n${stderr.trim()}`));
+    });
+  });
+}
+
+async function convert(input, opts, chrome) {
+  const inputPath = resolve(input);
+  if (!existsSync(inputPath)) throw new Error(`No such file: ${input}`);
+  const markdown = readFileSync(inputPath, 'utf8');
+  const stem = basename(inputPath, extname(inputPath));
+  const pdfPath = resolve(opts.output ?? join(dirname(inputPath), `${stem}.pdf`));
+  const title = titleOf(markdown, stem);
+
+  const html = buildHtml({
+    markdown,
+    title,
+    baseDir: dirname(inputPath),
+    style: opts.style,
+    extraCss: opts.css && resolve(opts.css),
+    pageSize: opts['page-size'],
+  });
+
+  const workDir = mkdtempSync(join(tmpdir(), 'md2pdf-'));
+  try {
+    const htmlPath = join(workDir, `${stem}.html`);
+    writeFileSync(htmlPath, html);
+    if (opts.html) writeFileSync(pdfPath.replace(/\.pdf$/i, '') + '.html', html);
+    await runChrome(chrome, htmlPath, pdfPath);
+  } finally {
+    rmSync(workDir, { recursive: true, force: true });
+  }
+  return pdfPath;
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      allowPositionals: true,
+      options: {
+        output: { type: 'string', short: 'o' },
+        style: { type: 'string', short: 's' },
+        css: { type: 'string' },
+        'page-size': { type: 'string', short: 'p', default: 'Letter' },
+        open: { type: 'boolean' },
+        html: { type: 'boolean' },
+        'set-style': { type: 'string' },
+        'list-styles': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+      },
+    });
+  } catch (err) {
+    console.error(`md2pdf: ${err.message}\n\nRun md2pdf --help for usage.`);
+    process.exit(2);
+  }
+  const { values: opts, positionals: files } = parsed;
+  const config = readConfig();
+  const defaultStyle = STYLES[config.style] ? config.style : FALLBACK_STYLE;
+
+  if (opts['set-style'] !== undefined) {
+    if (!STYLES[opts['set-style']]) unknownStyle(opts['set-style']);
+    writeConfig({ ...config, style: opts['set-style'] });
+    console.log(`Default style is now "${opts['set-style']}".`);
+    process.exit(0);
+  }
+  if (opts['list-styles']) {
+    for (const name of Object.keys(STYLES)) console.log(`${name === defaultStyle ? '*' : ' '} ${name}`);
+    process.exit(0);
+  }
+  if (opts.help || files.length === 0) {
+    console.log(usage(defaultStyle));
+    process.exit(opts.help ? 0 : 2);
+  }
+  if (config.style && !STYLES[config.style]) {
+    console.error(`md2pdf: config style "${config.style}" no longer exists; using ${FALLBACK_STYLE}`);
+  }
+  opts.style ??= defaultStyle;
+  if (!STYLES[opts.style]) unknownStyle(opts.style);
+  if (opts.output && files.length > 1) {
+    console.error('md2pdf: --output can only be used with a single input file');
+    process.exit(2);
+  }
+
+  const chrome = findChrome();
+  let failed = 0;
+  for (const file of files) {
+    try {
+      const pdf = await convert(file, opts, chrome);
+      console.log(pdf);
+      if (opts.open) spawn('open', [pdf], { stdio: 'ignore', detached: true }).unref();
+    } catch (err) {
+      failed++;
+      console.error(`md2pdf: ${file}: ${err.message}`);
+    }
+  }
+  process.exit(failed ? 1 : 0);
+}
+
+main();

package/lib/callouts.js

@@ -0,0 +1,73 @@
+// GitHub alerts and Obsidian callouts: a blockquote whose first line is `[!type]` becomes a titled box,
+// <div class="markdown-alert markdown-alert-{family}">, the markup github.com uses for alerts.
+// Obsidian's optional title follows the marker; its fold markers ([!note]- and [!note]+) are ignored,
+// since a PDF can't fold.
+
+// Each type belongs to one of GitHub's five alert families, or to quote. Unknown types look like notes.
+const FAMILIES = {
+  note: ['note', 'info', 'todo', 'abstract', 'summary', 'tldr'],
+  tip: ['tip', 'hint', 'success', 'check', 'done'],
+  important: ['important', 'example'],
+  warning: ['warning', 'attention', 'question', 'help', 'faq'],
+  caution: ['caution', 'danger', 'error', 'failure', 'fail', 'missing', 'bug'],
+  quote: ['quote', 'cite'],
+};
+const FAMILY_OF = Object.fromEntries(
+  Object.entries(FAMILIES).flatMap(([family, types]) => types.map((type) => [type, family])),
+);
+
+// Octicons 19 (MIT, github.com/primer/octicons): the icons GitHub shows on alerts, plus quote.
+const ICONS = {
+  note: 'M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z',
+  tip: 'M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z',
+  important: 'M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
+  warning: 'M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
+  caution: 'M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z',
+  quote: 'M1.75 2.5h10.5a.75.75 0 0 1 0 1.5H1.75a.75.75 0 0 1 0-1.5Zm4 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5Zm0 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5ZM2.5 7.75v6a.75.75 0 0 1-1.5 0v-6a.75.75 0 0 1 1.5 0Z',
+};
+
+// `[!type]`, an optional fold marker, then an optional title, on the blockquote's first line.
+const MARKER = /^\[!([\w-]+)\][+-]?(?:[ \t]+(.*))?$/;
+
+export default function callouts(md) {
+  // Runs before inline parsing, so the title can be given its own inline token and still get Markdown.
+  md.core.ruler.before('inline', 'callouts', (state) => {
+    const tokens = state.tokens;
+    for (let i = 0; i < tokens.length; i++) {
+      const open = tokens[i];
+      if (open.type !== 'blockquote_open' || tokens[i + 1]?.type !== 'paragraph_open') continue;
+      const inline = tokens[i + 2];
+      const [first, ...rest] = inline.content.split('\n');
+      const marker = first.match(MARKER);
+      if (!marker) continue;
+
+      const type = marker[1].toLowerCase();
+      const family = FAMILY_OF[type] ?? 'note';
+      const close = tokens.slice(i + 1).find((t) => t.type === 'blockquote_close' && t.level === open.level);
+      open.tag = close.tag = 'div';
+      open.attrSet('class', `markdown-alert markdown-alert-${family}`);
+      open.attrSet('data-callout', type);
+
+      const titleOpen = new state.Token('callout_title_open', 'p', 1);
+      titleOpen.meta = { family };
+      const title = new state.Token('inline', '', 0);
+      title.content = marker[2]?.trim() || type[0].toUpperCase() + type.slice(1);
+      title.children = [];
+      const titleClose = new state.Token('callout_title_close', 'p', -1);
+      for (const t of [titleOpen, title, titleClose]) {
+        t.block = true;
+        t.level = open.level + (t.type === 'inline' ? 2 : 1);
+        t.map = inline.map && [inline.map[0], inline.map[0] + 1];
+      }
+
+      // The rest of the first paragraph is the body; a callout with only a title has none.
+      inline.content = rest.join('\n');
+      if (inline.map) tokens[i + 1].map = inline.map = [inline.map[0] + 1, inline.map[1]];
+      tokens.splice(i + 1, inline.content ? 0 : 3, titleOpen, title, titleClose);
+    }
+  });
+
+  md.renderer.rules.callout_title_open = (tokens, idx) =>
+    `<p class="markdown-alert-title"><svg class="octicon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="${ICONS[tokens[idx].meta.family]}"></path></svg>`;
+  md.renderer.rules.callout_title_close = () => '</p>\n';
+}

package/lib/render.js

@@ -0,0 +1,110 @@
+// Markdown → HTML rendering shared by the CLI and the md2pdf.me website.
+
+import MarkdownIt from 'markdown-it';
+import anchor from 'markdown-it-anchor';
+import footnote from 'markdown-it-footnote';
+import taskLists from 'markdown-it-task-lists';
+import { full as emoji } from 'markdown-it-emoji';
+import callouts from './callouts.js';
+import wikilinks from './wikilinks.js';
+
+// YAML front matter: a `---` line at the very start of the document, closed by another `---` line.
+const FRONT_MATTER = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/;
+
+// Leaves front matter (Obsidian, Jekyll, Hugo) out of the output instead of rendering it as a rule and a heading.
+function frontMatter(md) {
+  md.block.ruler.before('table', 'front_matter', (state, startLine, endLine, silent) => {
+    if (startLine !== 0) return false;
+    const block = state.src.match(FRONT_MATTER)?.[0];
+    if (!block) return false;
+    if (!silent) state.line = block.replace(/\n$/, '').split('\n').length;
+    return true;
+  });
+}
+
+// Heading ids, which [[#Heading]] links must match.
+const slugify = (s) => s.trim().toLowerCase().replace(/[^\w\- ]+/g, '').replace(/\s/g, '-');
+
+export const escapeHtml = (s) =>
+  s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+// `hljs` is passed in so the CLI can use every language while the website
+// ships the smaller common-languages bundle. `math` ({ texmath, katex }) is optional:
+// the website loads it on demand when a document contains formulas. `html: false` escapes raw HTML in
+// the Markdown instead of passing it through; use it for Markdown you didn't write.
+export function createRenderer({ hljs, math, html = true }) {
+  const md = new MarkdownIt({
+    html,
+    linkify: true,
+    typographer: true,
+    highlight(code, lang) {
+      code = code.replace(/\n$/, '');
+      const body =
+        lang && hljs.getLanguage(lang)
+          ? hljs.highlight(code, { language: lang, ignoreIllegals: true }).value
+          : escapeHtml(code);
+      return `<pre><code class="hljs${lang ? ` language-${escapeHtml(lang)}` : ''}">${body}</code></pre>`;
+    },
+  });
+  md.use(anchor, { slugify })
+    .use(footnote)
+    .use(taskLists, { label: true })
+    .use(emoji)
+    .use(callouts)
+    .use(wikilinks, { slugify })
+    .use(frontMatter);
+  if (math) {
+    md.use(math.texmath, {
+      engine: math.katex,
+      // ChatGPT writes \( \) and \[ \]; many others use $ and $$.
+      delimiters: ['brackets', 'dollars', 'beg_end'],
+      // Require a space before an opening $ so prices like "$5 and $10" stay text.
+      outerSpace: true,
+      katexOptions: { throwOnError: false, output: 'html' },
+    });
+  }
+  return md;
+}
+
+// The document title: the first level-one heading, else the front matter's `title:`, else the fallback.
+export function titleOf(markdown, fallback) {
+  const [block, yaml = ''] = markdown.match(FRONT_MATTER) ?? [''];
+  const heading = markdown.slice(block.length).match(/^#\s+(.+)$/m)?.[1].trim();
+  const title = yaml.match(/^title:[ \t]*(.+?)[ \t]*$/m)?.[1].replace(/^(["'])(.*)\1$/, '$2').trim();
+  return heading || title || fallback;
+}
+
+// A quoted CSS string, safe inside a <style> element.
+export const cssString = (s) =>
+  `"${s.replace(/[\\"]/g, '\\$&').replace(/[\0-\x1f\x7f<]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `)}"`;
+
+// The text of the first <h1> in rendered HTML, or '' if there is none.
+export function headingText(html) {
+  const inner = html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/)?.[1] ?? '';
+  const text = inner.replace(/<[^>]*>/g, '');
+  return text.replace(/&(lt|gt|quot|amp);/g, (_, e) => ({ lt: '<', gt: '>', quot: '"', amp: '&' })[e]).trim();
+}
+
+// A complete printable HTML document. `css` is the style's on-screen stylesheet followed by its print
+// stylesheet.
+// Styles can show the first heading in a running header with `content: var(--document-title)`.
+export function buildDocument({ bodyHtml, title, css, pageSize = 'Letter', head = '' }) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+${head}
+<style>
+${css}
+@page { size: ${pageSize}; }
+:root { --document-title: ${cssString(headingText(bodyHtml))}; }
+</style>
+</head>
+<body>
+<article class="markdown-body">
+${bodyHtml}
+</article>
+</body>
+</html>`;
+}

package/lib/styles.js

@@ -0,0 +1,11 @@
+// Facts about each style that code needs without reading its CSS.
+
+// Each style's page margin at default spacing: the `margin` of the `@page` rule in styles/print/<name>.css.
+export const pageMargins = {
+  github: '0.75in 0.7in',
+  classic: '1in 1.1in 0.9in',
+  academic: '1in 1.15in',
+  modern: '0.9in 1in',
+  report: '1in 1in 0.9in',
+  resume: '0.6in 0.7in',
+};