@imontene/mdrender 1.0.0

package/dist/render/mermaid.js

@@ -0,0 +1,91 @@
+import { MERMAID_JS, readTextAsset } from "../assets.js";
+import { mermaidPlaceholder } from "../markdown/mermaid.js";
+import { fontFaceCss } from "./fonts.js";
+import { escapeHtml } from "../html.js";
+export { MERMAID_THEMES } from "../options.js";
+/** Width of the text column on A4 with 20 mm margins. */
+const DEFAULT_WIDTH_PX = 642;
+let mermaidJs;
+/**
+ * Render Mermaid diagrams to SVG in a blank page that holds no user content: only the diagram
+ * sources are passed in, as data. Mermaid runs with `securityLevel: "strict"`.
+ */
+export async function renderMermaid(session, blocks, theme = "neutral", 
+/** Width of the text column, so diagrams are laid out at their printed size. */
+widthPx = DEFAULT_WIDTH_PX) {
+    mermaidJs ??= readTextAsset(MERMAID_JS);
+    const page = await session.newPage();
+    try {
+        await page.setContent(`<!doctype html><html><head><meta charset="utf-8"><style>${fontFaceCss()}
+body { margin: 0; width: ${widthPx}px; font-family: "Inter", sans-serif; }</style>
+</head><body></body></html>`);
+        await page.evaluate(mermaidJs);
+        return await page.evaluate(async (sources, theme) => {
+            // Runs in the browser. The project is compiled without DOM types, hence PageGlobals.
+            const { document, mermaid } = globalThis;
+            // Load the font weights Mermaid uses before it measures any text.
+            await Promise.all(["400", "600", "700"].map((w) => document.fonts.load(`${w} 16px Inter`)));
+            mermaid.initialize({
+                startOnLoad: false,
+                securityLevel: "strict",
+                theme,
+                fontFamily: "Inter, sans-serif",
+                themeVariables: { fontFamily: "Inter, sans-serif" },
+                htmlLabels: true,
+            });
+            const results = [];
+            for (const [i, source] of sources.entries()) {
+                try {
+                    const { svg } = await mermaid.render(`mermaid-${i + 1}`, source);
+                    results.push({ svg });
+                }
+                catch (error) {
+                    results.push({ error: String(error?.message ?? error) });
+                }
+            }
+            return results;
+        }, blocks.map((b) => b.source), theme);
+    }
+    finally {
+        await page.close();
+    }
+}
+/**
+ * One-line summary of a Mermaid error. Parse errors span several lines ("Parse error on line N:",
+ * a code excerpt, a caret, "Expecting ..."); the line number counts from the diagram, not the
+ * file, so the "Expecting ..." line is the useful part.
+ */
+function summarize(message) {
+    const lines = message
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const expecting = lines.find((l) => l.startsWith("Expecting"));
+    return expecting ?? lines[0] ?? "unknown error";
+}
+/**
+ * Replace the Mermaid placeholders in `html` with rendered SVGs, or with a visible error box.
+ * Returns the new HTML and one error diagnostic per failed diagram.
+ */
+export function fillMermaid(html, nonce, blocks, results) {
+    const diagnostics = [];
+    blocks.forEach((block, i) => {
+        const result = results[i] ?? { error: "diagram was not rendered" };
+        let replacement;
+        if ("svg" in result) {
+            replacement = result.svg;
+        }
+        else {
+            const message = result.error.trim();
+            diagnostics.push({
+                severity: "error",
+                message: `Mermaid: ${summarize(message)}`,
+                line: block.line,
+            });
+            replacement = `<pre class="mermaid-error"><strong>Mermaid error</strong>\n${escapeHtml(message)}\n\n${escapeHtml(block.source)}</pre>`;
+        }
+        html = html.replace(mermaidPlaceholder(nonce, i), () => replacement);
+    });
+    return { html, diagnostics };
+}
+//# sourceMappingURL=mermaid.js.map

package/dist/render/page.d.ts

@@ -0,0 +1,7 @@
+import type { PageSize } from "../options.js";
+export declare function lengthToPx(length: string): number;
+/** Width of the text column in CSS pixels, so diagrams are laid out at their printed size. */
+export declare function contentWidthPx(pageSize: PageSize, landscape: boolean, margin: {
+    left: string;
+    right: string;
+}): number;

package/dist/render/page.js

@@ -0,0 +1,23 @@
+/** Paper sizes in millimetres, portrait (width, height). */
+const PAPER_MM = {
+    A3: [297, 420],
+    A4: [210, 297],
+    A5: [148, 210],
+    Letter: [215.9, 279.4],
+    Legal: [215.9, 355.6],
+    Tabloid: [279.4, 431.8],
+};
+const PX_PER_UNIT = { px: 1, in: 96, cm: 96 / 2.54, mm: 96 / 25.4 };
+export function lengthToPx(length) {
+    const match = /^(\d+(?:\.\d+)?)(mm|cm|in|px)$/.exec(length);
+    if (!match)
+        throw new Error(`invalid length: ${length}`);
+    return Number(match[1]) * PX_PER_UNIT[match[2]];
+}
+/** Width of the text column in CSS pixels, so diagrams are laid out at their printed size. */
+export function contentWidthPx(pageSize, landscape, margin) {
+    const [width, height] = PAPER_MM[pageSize];
+    const paperPx = ((landscape ? height : width) * 96) / 25.4;
+    return Math.round(paperPx - lengthToPx(margin.left) - lengthToPx(margin.right));
+}
+//# sourceMappingURL=page.js.map

package/dist/render/template.d.ts

@@ -0,0 +1,22 @@
+import { escapeHtml } from "../html.js";
+export { escapeHtml };
+/** Stylesheets of a built-in theme ("light" or "dark"). */
+export declare function builtinThemeCss(theme: "light" | "dark"): string[];
+export interface DocumentParts {
+    title: string;
+    body: string;
+    /** Include KaTeX's stylesheet and fonts (only needed when the document has math). */
+    math?: boolean;
+    lang?: string;
+    /** Front matter metadata. With `showTitle`, rendered as a title block before the body. */
+    subtitle?: string;
+    author?: string;
+    date?: string;
+    showTitle?: boolean;
+    /** Theme stylesheet contents. Defaults to the built-in light theme. */
+    themeCss?: string[];
+    /** Extra stylesheet contents, applied after the theme. */
+    extraCss?: string[];
+}
+/** Wrap a rendered Markdown fragment in a complete, self-contained HTML document. */
+export declare function buildHtmlDocument(parts: DocumentParts): string;

package/dist/render/template.js

@@ -0,0 +1,54 @@
+import { readTextAsset } from "../assets.js";
+import { escapeHtml } from "../html.js";
+import { fontFaceCss } from "./fonts.js";
+import { katexCss } from "./katex.js";
+import { version } from "../version.js";
+export { escapeHtml };
+const builtinCss = new Map();
+function asset(name) {
+    let css = builtinCss.get(name);
+    if (css === undefined) {
+        css = readTextAsset(`mdrender/assets/${name}`);
+        builtinCss.set(name, css);
+    }
+    return css;
+}
+/** Stylesheets of a built-in theme ("light" or "dark"). */
+export function builtinThemeCss(theme) {
+    return theme === "dark" ? [asset("theme.css"), asset("theme-dark.css")] : [asset("theme.css")];
+}
+function titleBlock({ title, subtitle, author, date }) {
+    const meta = [author, date].filter(Boolean).map((part) => escapeHtml(part));
+    return [
+        `<header class="doc-header">`,
+        `<h1 class="doc-title">${escapeHtml(title)}</h1>`,
+        subtitle ? `<p class="doc-subtitle">${escapeHtml(subtitle)}</p>` : "",
+        meta.length ? `<p class="doc-meta">${meta.join(" · ")}</p>` : "",
+        `</header>`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+/** Wrap a rendered Markdown fragment in a complete, self-contained HTML document. */
+export function buildHtmlDocument(parts) {
+    const { title, body, math = false, lang, author, extraCss = [] } = parts;
+    const themeCss = parts.themeCss ?? builtinThemeCss("light");
+    const styles = [fontFaceCss(), ...(math ? [katexCss()] : []), ...themeCss, ...extraCss];
+    return `<!doctype html>
+<html${lang ? ` lang="${escapeHtml(lang)}"` : ""}>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="mdrender ${escapeHtml(version)}">
+${author ? `<meta name="author" content="${escapeHtml(author)}">\n` : ""}<title>${escapeHtml(title)}</title>
+${styles.map((css) => `<style>\n${css}\n</style>`).join("\n")}
+</head>
+<body>
+<main class="markdown-body">
+${parts.showTitle ? titleBlock(parts) + "\n" : ""}${body}
+</main>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=template.js.map

package/dist/run.d.ts

@@ -0,0 +1,26 @@
+import { BrowserPool, type RenderSettings } from "./convert.js";
+import { ExitCode } from "./exit-codes.js";
+import type { Job } from "./inputs.js";
+import type { OutputFormat } from "./paths.js";
+export interface Io {
+    out: (text: string) => void;
+    err: (text: string) => void;
+    /** Only warnings and errors: no output paths, summaries or progress. */
+    quiet?: boolean;
+    /** Also report the config file, browser and time of each conversion. */
+    verbose?: boolean;
+}
+/** Progress messages (stderr), silenced by --quiet. */
+export declare const info: (io: Io, text: string) => void;
+/** Display path: relative to the working directory when inside it. */
+export declare function displayPath(file: string, cwd?: string): string;
+/**
+ * Convert one file, report its diagnostics and return its exit code. Expected failures (bad
+ * options, render errors) are reported, not thrown, so a batch can go on with the next file.
+ */
+export declare function runJob(job: Job, format: OutputFormat, settings: RenderSettings, browsers: BrowserPool, io: Io): Promise<{
+    code: ExitCode;
+    dependencies: string[];
+}>;
+/** Convert every job with one shared browser. The exit code is the most severe one. */
+export declare function runJobs(jobs: Job[], format: OutputFormat, settings: RenderSettings, io: Io, browsers?: BrowserPool): Promise<ExitCode>;

package/dist/run.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { BrowserPool, convertFile } from "./convert.js";
+import { formatDiagnostic } from "./diagnostics.js";
+import { MdRenderError } from "./errors.js";
+import { ExitCode } from "./exit-codes.js";
+/** Progress messages (stderr), silenced by --quiet. */
+export const info = (io, text) => {
+    if (!io.quiet)
+        io.err(text);
+};
+/** Display path: relative to the working directory when inside it. */
+export function displayPath(file, cwd = process.cwd()) {
+    const relative = path.relative(cwd, file);
+    return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : file;
+}
+/**
+ * Convert one file, report its diagnostics and return its exit code. Expected failures (bad
+ * options, render errors) are reported, not thrown, so a batch can go on with the next file.
+ */
+export async function runJob(job, format, settings, browsers, io) {
+    const started = Date.now();
+    try {
+        const result = await convertFile({ ...settings, ...job, format, browsers });
+        for (const diagnostic of result.diagnostics) {
+            io.err(`${formatDiagnostic(diagnostic, displayPath(job.input))}\n`);
+        }
+        if (io.verbose && result.configFile)
+            io.err(`config: ${result.configFile}\n`);
+        if (!io.quiet)
+            io.out(`${result.output}\n`);
+        if (io.verbose)
+            io.err(`${displayPath(job.input)}: ${Date.now() - started} ms\n`);
+        // The file is still written (errors are shown inline) but the run counts as failed.
+        const failed = result.diagnostics.some((d) => d.severity === "error");
+        return { code: failed ? ExitCode.Render : ExitCode.Ok, dependencies: result.dependencies };
+    }
+    catch (error) {
+        if (error instanceof MdRenderError) {
+            io.err(`error: ${displayPath(job.input)}: ${error.message}\n`);
+            return { code: error.exitCode, dependencies: [] };
+        }
+        throw error;
+    }
+}
+/** Convert every job with one shared browser. The exit code is the most severe one. */
+export async function runJobs(jobs, format, settings, io, browsers = new BrowserPool(settings.browser, (message) => {
+    if (io.verbose)
+        io.err(`${message}\n`);
+})) {
+    let worst = ExitCode.Ok;
+    let failed = 0;
+    try {
+        for (const job of jobs) {
+            const { code } = await runJob(job, format, settings, browsers, io);
+            if (code !== ExitCode.Ok)
+                failed++;
+            worst = Math.max(worst, code);
+            // Without a browser no other PDF can be produced either.
+            if (code === ExitCode.BrowserNotFound)
+                break;
+        }
+    }
+    finally {
+        await browsers.close();
+    }
+    if (jobs.length > 1) {
+        info(io, `${jobs.length} files, ${jobs.length - failed} ok, ${failed} with errors\n`);
+    }
+    return worst;
+}
+//# sourceMappingURL=run.js.map

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const version: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { PACKAGE_JSON, readTextAsset } from "./assets.js";
+export const version = JSON.parse(readTextAsset(PACKAGE_JSON))
+    .version;
+//# sourceMappingURL=version.js.map

package/dist/watch.d.ts

@@ -0,0 +1,25 @@
+import { type RenderSettings } from "./convert.js";
+import { ExitCode } from "./exit-codes.js";
+import { type OutputFormat } from "./paths.js";
+import { type Io } from "./run.js";
+export interface WatchOptions {
+    inputs: string[];
+    format: OutputFormat;
+    output?: string;
+    settings: RenderSettings;
+    io: Io;
+    /** Watching stops when this signal aborts (Ctrl+C in the CLI). */
+    signal: AbortSignal;
+    cwd?: string;
+    /** Wait for changes to settle before re-rendering (ms). */
+    debounceMs?: number;
+}
+/** Paths to watch for the command-line inputs: files, folders, or a glob's base folder. */
+export declare function watchRoots(inputs: string[], cwd: string): string[];
+/**
+ * Convert the inputs, then convert again whenever they change, until `signal` aborts.
+ *
+ * A changed Markdown file is re-rendered alone; any other change (config file, stylesheet,
+ * image) re-renders everything. New files under watched folders or globs are picked up.
+ */
+export declare function watchAndConvert(options: WatchOptions): Promise<ExitCode>;

package/dist/watch.js

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { watch } from "chokidar";
+import { isDynamicPattern } from "tinyglobby";
+import { BrowserPool } from "./convert.js";
+import { MdRenderError } from "./errors.js";
+import { ExitCode } from "./exit-codes.js";
+import { expandInputs, planOutputs } from "./inputs.js";
+import { isMarkdownFile } from "./paths.js";
+import { displayPath, info, runJob } from "./run.js";
+/** Paths to watch for the command-line inputs: files, folders, or a glob's base folder. */
+export function watchRoots(inputs, cwd) {
+    return inputs.map((input) => {
+        const resolved = path.resolve(cwd, input);
+        if (existsSync(resolved))
+            return resolved;
+        const pattern = input.replace(/\\/g, "/");
+        if (!isDynamicPattern(pattern))
+            return resolved;
+        const fixed = [];
+        for (const part of pattern.split("/")) {
+            if (isDynamicPattern(part))
+                break;
+            fixed.push(part);
+        }
+        return path.resolve(cwd, fixed.join("/") || ".");
+    });
+}
+const time = () => new Date().toTimeString().slice(0, 8);
+/**
+ * Convert the inputs, then convert again whenever they change, until `signal` aborts.
+ *
+ * A changed Markdown file is re-rendered alone; any other change (config file, stylesheet,
+ * image) re-renders everything. New files under watched folders or globs are picked up.
+ */
+export async function watchAndConvert(options) {
+    const { format, settings, io, signal, cwd = process.cwd() } = options;
+    const browsers = new BrowserPool(settings.browser, (message) => {
+        if (io.verbose)
+            io.err(`${message}\n`);
+    });
+    const dependencies = new Set();
+    let jobs = [];
+    let watcher = undefined;
+    const plan = () => planOutputs(expandInputs(options.inputs, cwd), format, options.output, cwd);
+    const convert = async (selected) => {
+        for (const job of selected) {
+            info(io, `[${time()}] ${displayPath(job.input, cwd)}\n`);
+            const result = await runJob(job, format, settings, browsers, io);
+            // Also watch the config files and stylesheets the documents use.
+            for (const dep of result.dependencies) {
+                if (!dependencies.has(dep)) {
+                    dependencies.add(dep);
+                    watcher?.add(dep);
+                }
+            }
+            if (result.code === ExitCode.BrowserNotFound)
+                return;
+        }
+    };
+    try {
+        jobs = plan();
+    }
+    catch (error) {
+        if (error instanceof MdRenderError) {
+            io.err(`error: ${error.message}\n`);
+            return error.exitCode;
+        }
+        throw error;
+    }
+    // Do not react to our own output files (e.g. HTML written next to the Markdown).
+    const outputs = () => new Set(jobs.map((j) => j.output));
+    watcher = watch(watchRoots(options.inputs, cwd), {
+        ignoreInitial: true,
+        ignored: (file) => {
+            const name = path.basename(file);
+            return name === "node_modules" || (name.startsWith(".") && name !== ".");
+        },
+        awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 },
+    });
+    await new Promise((resolve) => watcher.once("ready", () => resolve()));
+    await convert(jobs);
+    info(io, `Watching for changes (Ctrl+C to stop)…\n`);
+    const pending = new Set();
+    let timer;
+    let running = Promise.resolve();
+    const flush = () => {
+        const changed = [...pending];
+        pending.clear();
+        running = running.then(async () => {
+            try {
+                jobs = plan();
+            }
+            catch (error) {
+                if (error instanceof MdRenderError) {
+                    io.err(`error: ${error.message}\n`);
+                    return;
+                }
+                throw error;
+            }
+            const all = changed.some((file) => !isMarkdownFile(file) || dependencies.has(file));
+            const selected = all ? jobs : jobs.filter((job) => changed.includes(job.input));
+            await convert(selected);
+        });
+    };
+    watcher.on("all", (event, file) => {
+        const resolved = path.resolve(file);
+        if (event === "unlink" || event === "unlinkDir" || event === "addDir")
+            return;
+        if (outputs().has(resolved))
+            return;
+        pending.add(resolved);
+        clearTimeout(timer);
+        timer = setTimeout(flush, options.debounceMs ?? 150);
+    });
+    await new Promise((resolve) => {
+        if (signal.aborted)
+            resolve();
+        else
+            signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+    clearTimeout(timer);
+    await running.catch(() => undefined);
+    await watcher.close();
+    await browsers.close();
+    return ExitCode.Ok;
+}
+//# sourceMappingURL=watch.js.map

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@imontene/mdrender",
+  "version": "1.0.0",
+  "description": "Command-line app for Windows and Linux that renders Markdown — with LaTeX equations and Mermaid diagrams — to PDF and HTML using the Inter typeface",
+  "keywords": [
+    "markdown",
+    "pdf",
+    "html",
+    "mermaid",
+    "katex",
+    "latex",
+    "cli",
+    "inter",
+    "converter"
+  ],
+  "homepage": "https://github.com/imontene/MD_reder#readme",
+  "bugs": {
+    "url": "https://github.com/imontene/MD_reder/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/imontene/MD_reder.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mdrender": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
+    "dev": "tsx src/bin.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
+    "build:exe": "npm run build && node scripts/build-sea.mjs",
+    "prepublishOnly": "npm run check && npm run build",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@fontsource/jetbrains-mono": "^5.3.0",
+    "@puppeteer/browsers": "^3.2.3",
+    "chokidar": "^5.0.0",
+    "commander": "^15.0.0",
+    "highlight.js": "^11.12.0",
+    "inter-ui": "^4.1.1",
+    "katex": "^0.19.0",
+    "markdown-it": "^15.0.2",
+    "markdown-it-anchor": "^10.0.0",
+    "markdown-it-footnote": "^4.0.0",
+    "mermaid": "^12.1.0",
+    "puppeteer-core": "^25.12.0",
+    "tinyglobby": "^0.2.17",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.5",
+    "@vitest/coverage-v8": "^5.0.3",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.12.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.13.0",
+    "pdfjs-dist": "^6.4.299",
+    "postject": "^1.0.0-alpha.6",
+    "prettier": "^3.9.9",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.0",
+    "vitest": "^5.0.3"
+  }
+}