@imontene/mdrender 1.0.0

package/dist/browser/cache.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Per-user folder where `mdrender setup` keeps its downloaded browser:
+ * %LOCALAPPDATA%\mdrender on Windows, ~/Library/Caches/mdrender on macOS and
+ * $XDG_CACHE_HOME/mdrender (or ~/.cache/mdrender) elsewhere. MDRENDER_CACHE_DIR overrides it.
+ */
+export declare function cacheDir(env?: Record<string, string | undefined>, platform?: NodeJS.Platform, home?: string): string;
+/** Small record written by `mdrender setup` pointing at the browser it installed. */
+export interface InstalledBrowserRecord {
+    executablePath: string;
+    buildId: string;
+    installedAt: string;
+}
+export declare const RECORD_FILE = "browser.json";
+/** The browser installed by `mdrender setup`, if it is still there. */
+export declare function installedBrowser(dir?: string): string | undefined;

package/dist/browser/cache.js

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Per-user folder where `mdrender setup` keeps its downloaded browser:
+ * %LOCALAPPDATA%\mdrender on Windows, ~/Library/Caches/mdrender on macOS and
+ * $XDG_CACHE_HOME/mdrender (or ~/.cache/mdrender) elsewhere. MDRENDER_CACHE_DIR overrides it.
+ */
+export function cacheDir(env = process.env, platform = process.platform, home = os.homedir()) {
+    if (env.MDRENDER_CACHE_DIR)
+        return path.resolve(env.MDRENDER_CACHE_DIR);
+    if (platform === "win32") {
+        return path.win32.join(env.LOCALAPPDATA ?? path.win32.join(home, "AppData", "Local"), "mdrender");
+    }
+    if (platform === "darwin")
+        return path.posix.join(home, "Library", "Caches", "mdrender");
+    return path.posix.join(env.XDG_CACHE_HOME ?? path.posix.join(home, ".cache"), "mdrender");
+}
+export const RECORD_FILE = "browser.json";
+/** The browser installed by `mdrender setup`, if it is still there. */
+export function installedBrowser(dir = cacheDir()) {
+    try {
+        const record = JSON.parse(readFileSync(path.join(dir, RECORD_FILE), "utf8"));
+        return existsSync(record.executablePath) ? record.executablePath : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/browser/detect.d.ts

@@ -0,0 +1,17 @@
+export interface DetectOptions {
+    platform?: NodeJS.Platform;
+    env?: Record<string, string | undefined>;
+    exists?: (file: string) => boolean;
+    /** Browser downloaded by `mdrender setup`; looked up in the cache folder by default. */
+    downloaded?: () => string | undefined;
+}
+/** Well-known Chromium-based browser locations for a platform, in order of preference. */
+export declare function browserCandidates(platform?: NodeJS.Platform, env?: Record<string, string | undefined>): string[];
+/**
+ * Find a Chromium-based browser executable.
+ *
+ * Order: the explicit path (`--browser`), then `MDRENDER_BROWSER`, then well-known locations,
+ * then the browser downloaded by `mdrender setup`.
+ * An explicit path or env var that does not exist is an error rather than silently ignored.
+ */
+export declare function findBrowser(explicit?: string, options?: DetectOptions): string;

package/dist/browser/detect.js

@@ -0,0 +1,90 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { BrowserNotFoundError } from "../errors.js";
+import { installedBrowser } from "./cache.js";
+/** Look up an environment variable case-insensitively (Windows env names are not case-sensitive). */
+function getEnv(env, name) {
+    if (env[name] !== undefined)
+        return env[name];
+    const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key ? env[key] : undefined;
+}
+const WINDOWS_APPS = [
+    "Google\\Chrome\\Application\\chrome.exe",
+    "Chromium\\Application\\chrome.exe",
+    "Microsoft\\Edge\\Application\\msedge.exe",
+    "BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+];
+const LINUX_COMMANDS = [
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+    "microsoft-edge",
+    "microsoft-edge-stable",
+    "brave-browser",
+];
+const LINUX_FIXED = [
+    "/opt/google/chrome/chrome",
+    "/opt/microsoft/msedge/msedge",
+    "/snap/bin/chromium",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+];
+const MAC_APPS = [
+    "/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",
+];
+/** Well-known Chromium-based browser locations for a platform, in order of preference. */
+export function browserCandidates(platform = process.platform, env = process.env) {
+    if (platform === "win32") {
+        const roots = ["ProgramFiles", "ProgramFiles(x86)", "LOCALAPPDATA"]
+            .map((name) => getEnv(env, name))
+            .filter((root) => Boolean(root));
+        return WINDOWS_APPS.flatMap((app) => roots.map((root) => path.win32.join(root, app)));
+    }
+    if (platform === "darwin") {
+        return MAC_APPS;
+    }
+    const dirs = (getEnv(env, "PATH") ?? "").split(":").filter(Boolean);
+    const fromPath = LINUX_COMMANDS.flatMap((cmd) => dirs.map((dir) => path.posix.join(dir, cmd)));
+    return [...new Set([...fromPath, ...LINUX_FIXED])];
+}
+function isFile(file) {
+    try {
+        return existsSync(file) && statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find a Chromium-based browser executable.
+ *
+ * Order: the explicit path (`--browser`), then `MDRENDER_BROWSER`, then well-known locations,
+ * then the browser downloaded by `mdrender setup`.
+ * An explicit path or env var that does not exist is an error rather than silently ignored.
+ */
+export function findBrowser(explicit, options = {}) {
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? isFile;
+    const requested = explicit ?? getEnv(env, "MDRENDER_BROWSER");
+    if (requested) {
+        if (exists(requested))
+            return requested;
+        const source = explicit ? "--browser" : "MDRENDER_BROWSER";
+        throw new BrowserNotFoundError(`browser not found at ${requested} (from ${source})`);
+    }
+    const found = browserCandidates(options.platform, env).find(exists);
+    if (found)
+        return found;
+    const downloaded = (options.downloaded ?? installedBrowser)();
+    if (downloaded)
+        return downloaded;
+    throw new BrowserNotFoundError("no Chromium-based browser found (Google Chrome, Chromium, Microsoft Edge or Brave).\n" +
+        "Run `mdrender setup` to download one, install one, or point to it with --browser <path>\n" +
+        "or the MDRENDER_BROWSER variable.");
+}
+//# sourceMappingURL=detect.js.map

package/dist/browser/setup.d.ts

@@ -0,0 +1,13 @@
+import { ExitCode } from "../exit-codes.js";
+import type { Io } from "../run.js";
+export interface SetupOptions {
+    io: Io;
+    /** Download even when a system browser is available. */
+    force?: boolean;
+    dir?: string;
+}
+/**
+ * Download Chrome Headless Shell (the official headless build of Chrome, ~100 MB) into the
+ * user's cache folder, for machines without Chrome, Edge or Chromium.
+ */
+export declare function setup({ io, force, dir, }: SetupOptions): Promise<ExitCode>;

package/dist/browser/setup.js

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { Browser, BrowserPlatform, detectBrowserPlatform, install, resolveBuildId, } from "@puppeteer/browsers";
+import { ExitCode } from "../exit-codes.js";
+import { cacheDir, RECORD_FILE } from "./cache.js";
+import { findBrowser } from "./detect.js";
+/**
+ * Download Chrome Headless Shell (the official headless build of Chrome, ~100 MB) into the
+ * user's cache folder, for machines without Chrome, Edge or Chromium.
+ */
+export async function setup({ io, force = false, dir = cacheDir(), }) {
+    let system;
+    try {
+        system = findBrowser();
+    }
+    catch {
+        // none installed: download one
+    }
+    if (system && !force) {
+        io.err(`A browser is already installed: ${system}\nNo download needed (use --force to download anyway).\n`);
+        io.out(`${system}\n`);
+        return ExitCode.Ok;
+    }
+    const platform = detectBrowserPlatform();
+    if (!platform || platform === BrowserPlatform.LINUX_ARM) {
+        io.err("error: Chrome Headless Shell is not published for this platform.\n" +
+            "Install Chromium with your package manager (e.g. `sudo apt install chromium`).\n");
+        return ExitCode.BrowserNotFound;
+    }
+    const browser = Browser.CHROMEHEADLESSSHELL;
+    let buildId;
+    let executablePath;
+    try {
+        io.err("Looking up the latest stable Chrome Headless Shell…\n");
+        buildId = await resolveBuildId(browser, platform, "stable");
+        io.err(`Downloading Chrome Headless Shell ${buildId} into ${dir}\n`);
+        let lastPercent = -1;
+        ({ executablePath } = await install({
+            browser,
+            buildId,
+            platform,
+            cacheDir: dir,
+            downloadProgressCallback: (done, total) => {
+                const percent = total ? Math.floor((done / total) * 100) : 0;
+                if (percent >= lastPercent + 10 || percent === 100) {
+                    lastPercent = percent;
+                    io.err(`  ${percent}%\n`);
+                }
+            },
+        }));
+    }
+    catch (error) {
+        io.err(`error: could not download the browser: ${error.message}\n` +
+            "Check your internet connection or proxy (HTTPS_PROXY), or install Chrome, Edge or\n" +
+            "Chromium yourself.\n");
+        return ExitCode.BrowserNotFound;
+    }
+    mkdirSync(dir, { recursive: true });
+    const record = {
+        executablePath,
+        buildId,
+        installedAt: new Date().toISOString(),
+    };
+    writeFileSync(path.join(dir, RECORD_FILE), JSON.stringify(record, null, 2));
+    io.err(`Installed: ${executablePath}\n`);
+    io.out(`${executablePath}\n`);
+    return ExitCode.Ok;
+}
+//# sourceMappingURL=setup.js.map

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+import { type Io } from "./run.js";
+export declare const defaultIo: Io;
+export interface MainOptions {
+    /** Stops --watch and preview (the CLI aborts it on Ctrl+C). */
+    signal?: AbortSignal;
+}
+/** Run the CLI and return the exit code instead of exiting, so it can be tested in-process. */
+export declare function main(argv: string[], io?: Io, { signal }?: MainOptions): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,194 @@
+import { Command, CommanderError, Option } from "commander";
+import { setup } from "./browser/setup.js";
+import { MdRenderError } from "./errors.js";
+import { ExitCode } from "./exit-codes.js";
+import { expandInputs, planOutputs } from "./inputs.js";
+import { MERMAID_THEMES, normalizeOptions, PAGE_SIZES } from "./options.js";
+import { preview } from "./preview.js";
+import { runJobs } from "./run.js";
+import { version } from "./version.js";
+import { watchAndConvert } from "./watch.js";
+/** Command-line flags that map to document options (camelCase = DocumentOptions key). */
+const DOCUMENT_FLAGS = [
+    "pageSize",
+    "margin",
+    "landscape",
+    "toc",
+    "tocDepth",
+    "header",
+    "footer",
+    "pageNumbers",
+    "css",
+    "theme",
+    "mermaidTheme",
+    "lang",
+    "title",
+];
+const toFlag = (key) => "--" + key.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+export const defaultIo = {
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+};
+const collect = (value, previous = []) => [...previous, value];
+/** Options shared by `mdrender` (render) and `mdrender preview`. */
+function addDocumentOptions(command) {
+    return command
+        .option("--page-size <size>", `paper size: ${PAGE_SIZES.join(", ")} (default: A4)`)
+        .option("--margin <margin>", 'page margins, e.g. "20mm" or "15mm 20mm" (default: 20mm)')
+        .option("--landscape", "landscape orientation")
+        .option("--toc", "insert a table of contents (or place it with [[toc]])")
+        .option("--toc-depth <n>", "deepest heading level in the table of contents (default: 3)")
+        .option("--header <text>", 'page header, e.g. "{title} | | {date}"')
+        .option("--footer <text>", 'page footer (default: "{page} / {pages}")')
+        .option("--no-page-numbers", "no default page-number footer")
+        .option("--theme <theme>", "light, dark, or a .css file replacing the theme (default: light)")
+        .option("--css <file>", "extra stylesheet (repeatable)", collect)
+        .option("--mermaid-theme <theme>", `Mermaid theme: ${MERMAID_THEMES.join(", ")} (default: neutral; dark with --theme dark)`)
+        .option("--lang <tag>", "document language, e.g. es or en (default: es)")
+        .option("--title <text>", "document title (shown as a title block)")
+        .option("--config <file>", "config file (default: nearest mdrender.config.json)")
+        .option("--no-config", "ignore mdrender.config.json files")
+        .option("--browser <path>", "Chrome, Edge or Chromium executable (default: auto-detect)")
+        .option("--allow-remote", "let the PDF load remote (http/https) images and stylesheets");
+}
+function configure(command, io) {
+    return command.exitOverride().configureOutput({ writeOut: io.out, writeErr: io.err });
+}
+function buildRenderProgram(io) {
+    const program = new Command()
+        .name("mdrender")
+        .description("Render Markdown files to PDF (or self-contained HTML) using the Inter typeface.")
+        .version(version, "-V, --version")
+        .argument("<inputs...>", "Markdown files, folders or glob patterns (e.g. docs/**/*.md)")
+        .option("-o, --output <path>", "output file, or folder for several inputs")
+        .addOption(new Option("-f, --format <format>", "output format").choices(["pdf", "html"]).default("pdf"))
+        .option("-w, --watch", "convert again whenever the inputs change")
+        .option("-q, --quiet", "only print warnings and errors")
+        .option("-v, --verbose", "also print config file, browser and timings");
+    addDocumentOptions(program).addHelpText("after", `
+Commands:
+  mdrender preview <file>  live HTML preview in the browser (see: mdrender preview --help)
+  mdrender setup           download a headless Chrome if no browser is installed
+
+Header/footer placeholders: {page} {pages} {title} {author} {date}; "|" separates
+left | center | right columns.
+
+Options can also be set in YAML front matter or in mdrender.config.json
+(command line > front matter > config file).`);
+    return configure(program, io);
+}
+function buildPreviewProgram(io) {
+    const program = new Command()
+        .name("mdrender preview")
+        .description("Live HTML preview of a Markdown file, reloaded on every change.")
+        .argument("<input>", "Markdown file")
+        .option("--port <port>", "port on 127.0.0.1 (default: a free port)")
+        .option("--no-open", "do not open the browser, only print the URL");
+    addDocumentOptions(program);
+    return configure(program, io);
+}
+/** Document options given explicitly on the command line (not commander defaults). */
+function cliOverrides(program) {
+    const raw = {};
+    for (const key of DOCUMENT_FLAGS) {
+        if (program.getOptionValueSource(key) === "cli")
+            raw[key] = program.getOptionValue(key);
+    }
+    return normalizeOptions(raw, "command line", process.cwd(), (key) => key === "pageNumbers" ? "--no-page-numbers" : toFlag(key));
+}
+function settings(program, options) {
+    return {
+        browser: options.browser,
+        config: options.config,
+        overrides: cliOverrides(program),
+        allowRemote: options.allowRemote ?? false,
+    };
+}
+async function parse(program, argv) {
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            // --help and --version are reported by commander as "errors" with exit code 0.
+            return error.exitCode === 0 ? ExitCode.Ok : ExitCode.Usage;
+        }
+        throw error;
+    }
+}
+function buildSetupProgram(io) {
+    const program = new Command()
+        .name("mdrender setup")
+        .description("Download Chrome Headless Shell (~100 MB) into the user cache folder, for machines\n" +
+        "without Chrome, Edge or Chromium. Does nothing when a browser is already installed.")
+        .option("--force", "download even if a browser is already installed");
+    return configure(program, io);
+}
+async function runSetup(argv, io) {
+    const program = buildSetupProgram(io);
+    const parsed = await parse(program, argv);
+    if (parsed !== undefined)
+        return parsed;
+    return setup({ io, force: Boolean(program.opts().force) });
+}
+async function runPreview(argv, io, signal) {
+    const program = buildPreviewProgram(io);
+    const parsed = await parse(program, argv);
+    if (parsed !== undefined)
+        return parsed;
+    const options = program.opts();
+    const port = options.port === undefined ? 0 : Number(options.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        io.err(`error: invalid port: ${options.port}\n`);
+        return ExitCode.Usage;
+    }
+    const [input] = expandInputs(program.args);
+    return preview({
+        input: input.file,
+        settings: settings(program, options),
+        io,
+        signal,
+        port,
+        open: options.open,
+    });
+}
+async function runRender(argv, io, signal) {
+    const program = buildRenderProgram(io);
+    const parsed = await parse(program, argv);
+    if (parsed !== undefined)
+        return parsed;
+    const options = program.opts();
+    const run = settings(program, options);
+    io = { ...io, quiet: options.quiet, verbose: options.verbose && !options.quiet };
+    if (options.watch) {
+        return watchAndConvert({
+            inputs: program.args,
+            format: options.format,
+            output: options.output,
+            settings: run,
+            io,
+            signal,
+        });
+    }
+    const jobs = planOutputs(expandInputs(program.args), options.format, options.output);
+    return runJobs(jobs, options.format, run, io);
+}
+/** Run the CLI and return the exit code instead of exiting, so it can be tested in-process. */
+export async function main(argv, io = defaultIo, { signal = new AbortController().signal } = {}) {
+    try {
+        if (argv[0] === "preview")
+            return await runPreview(argv.slice(1), io, signal);
+        if (argv[0] === "setup")
+            return await runSetup(argv.slice(1), io);
+        return await runRender(argv, io, signal);
+    }
+    catch (error) {
+        if (error instanceof MdRenderError) {
+            io.err(`error: ${error.message}\n`);
+            return error.exitCode;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import { type DocumentOptions } from "./options.js";
+export declare const CONFIG_FILE = "mdrender.config.json";
+/** Find `mdrender.config.json` in `startDir` or the nearest parent directory. */
+export declare function findConfigFile(startDir: string): string | undefined;
+/** Read and validate a config file. Relative paths inside it resolve against its folder. */
+export declare function loadConfig(file: string): Partial<DocumentOptions>;

package/dist/config.js

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { normalizeOptions, OptionsError } from "./options.js";
+export const CONFIG_FILE = "mdrender.config.json";
+/** Find `mdrender.config.json` in `startDir` or the nearest parent directory. */
+export function findConfigFile(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, CONFIG_FILE);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Read and validate a config file. Relative paths inside it resolve against its folder. */
+export function loadConfig(file) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new OptionsError(`${file}: ${error.message}`);
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new OptionsError(`${file}: the configuration must be a JSON object`);
+    }
+    return normalizeOptions(raw, file, path.dirname(file));
+}
+//# sourceMappingURL=config.js.map

package/dist/convert.d.ts

@@ -0,0 +1,64 @@
+import type { Diagnostic } from "./diagnostics.js";
+import { type DocumentOptions, type MermaidTheme } from "./options.js";
+import type { OutputFormat } from "./paths.js";
+import { BrowserSession } from "./render/browser.js";
+/** Settings shared by every file of a run (batch, watch or preview). */
+export interface RenderSettings {
+    /** Explicit browser executable. */
+    browser?: string;
+    /**
+     * Config file to use. Undefined: look for mdrender.config.json next to the input or in a
+     * parent folder. `false`: use no config file.
+     */
+    config?: string | false;
+    /** Options from the command line; they win over front matter and the config file. */
+    overrides?: Partial<DocumentOptions>;
+    /**
+     * Let the browser download http(s) resources (remote images, stylesheets) while printing.
+     * Command line only: a document cannot grant itself network access.
+     */
+    allowRemote?: boolean;
+}
+export interface ConvertOptions extends RenderSettings {
+    input: string;
+    output: string;
+    format: OutputFormat;
+    /** Reuse a browser across conversions; without it each conversion starts its own. */
+    browsers?: BrowserPool;
+}
+export interface ConvertResult {
+    output: string;
+    /** Problems found while rendering; the output is still written, with errors shown inline. */
+    diagnostics: Diagnostic[];
+    /** The effective options after merging config file, front matter and command line. */
+    options: DocumentOptions;
+    /** Config file that was applied, if any. */
+    configFile?: string;
+    /** Files the output depends on besides the Markdown (config file, stylesheets). */
+    dependencies: string[];
+}
+export interface RenderedDocument extends Omit<ConvertResult, "output"> {
+    html: string;
+    title: string;
+}
+/** Starts one browser on first use and keeps it for later conversions. */
+export declare class BrowserPool {
+    private readonly executable?;
+    /** Receives notes about the browser (which one started, sandbox fallback) for --verbose. */
+    private readonly log?;
+    private session?;
+    constructor(executable?: string | undefined, 
+    /** Receives notes about the browser (which one started, sandbox fallback) for --verbose. */
+    log?: ((message: string) => void) | undefined);
+    get(): Promise<BrowserSession>;
+    close(): Promise<void>;
+}
+/** Mermaid theme: explicit choice, else dark diagrams for the dark page theme. */
+export declare function effectiveMermaidTheme(options: DocumentOptions): MermaidTheme;
+/**
+ * Render a Markdown file to a complete HTML document. A browser is only started (through
+ * `browsers`) when the document has Mermaid diagrams.
+ */
+export declare function renderDocument(inputPath: string, settings: RenderSettings, browsers: BrowserPool): Promise<RenderedDocument>;
+/** Read a Markdown file and write it as a self-contained HTML document or a PDF. */
+export declare function convertFile(convert: ConvertOptions): Promise<ConvertResult>;