@imontene/mdrender 1.0.0

package/dist/convert.js

@@ -0,0 +1,167 @@
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { findBrowser } from "./browser/detect.js";
+import { findConfigFile, loadConfig } from "./config.js";
+import { extractFrontMatter } from "./frontmatter.js";
+import { strings } from "./i18n.js";
+import { renderMarkdown } from "./markdown/index.js";
+import { buildToc, tocPlaceholder } from "./markdown/toc.js";
+import { mergeOptions, normalizeOptions, OptionsError, parseMargin, } from "./options.js";
+import { BrowserSession } from "./render/browser.js";
+import { DEFAULT_FOOTER, headerFooterTemplate } from "./render/header-footer.js";
+import { fillMermaid, renderMermaid } from "./render/mermaid.js";
+import { contentWidthPx } from "./render/page.js";
+import { buildHtmlDocument, builtinThemeCss } from "./render/template.js";
+/** Starts one browser on first use and keeps it for later conversions. */
+export class BrowserPool {
+    executable;
+    log;
+    session;
+    constructor(executable, 
+    /** Receives notes about the browser (which one started, sandbox fallback) for --verbose. */
+    log) {
+        this.executable = executable;
+        this.log = log;
+    }
+    get() {
+        if (!this.session) {
+            const executablePath = findBrowser(this.executable);
+            this.log?.(`browser: ${executablePath}`);
+            this.session = BrowserSession.open(executablePath, undefined, () => this.log?.("browser: sandbox unavailable on this system, running without it"));
+        }
+        // A failed start is not cached: the next conversion tries again.
+        this.session.catch(() => (this.session = undefined));
+        return this.session;
+    }
+    async close() {
+        const session = await this.session?.catch(() => undefined);
+        this.session = undefined;
+        await session?.close();
+    }
+}
+function readStylesheet(file) {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        throw new OptionsError(`stylesheet not found: ${file}`);
+    }
+}
+function themeStylesheets(theme) {
+    return theme === "light" || theme === "dark" ? builtinThemeCss(theme) : [readStylesheet(theme)];
+}
+/** Mermaid theme: explicit choice, else dark diagrams for the dark page theme. */
+export function effectiveMermaidTheme(options) {
+    return options.mermaidTheme ?? (options.theme === "dark" ? "dark" : "neutral");
+}
+/**
+ * Render a Markdown file to a complete HTML document. A browser is only started (through
+ * `browsers`) when the document has Mermaid diagrams.
+ */
+export async function renderDocument(inputPath, settings, browsers) {
+    const input = path.resolve(inputPath);
+    const baseDir = path.dirname(input);
+    const source = await readFile(input, "utf8");
+    const frontMatter = extractFrontMatter(source, input);
+    const configFile = settings.config === false
+        ? undefined
+        : settings.config
+            ? path.resolve(settings.config)
+            : findConfigFile(baseDir);
+    const options = mergeOptions(configFile ? loadConfig(configFile) : {}, normalizeOptions(frontMatter.data, `${input} (front matter)`, baseDir), settings.overrides ?? {});
+    const margin = parseMargin(options.margin);
+    const themeCss = themeStylesheets(options.theme);
+    const extraCss = options.css.map(readStylesheet);
+    const md = renderMarkdown(frontMatter.body, { baseDir, lang: options.lang });
+    const diagnostics = [...md.diagnostics];
+    const title = options.title ?? md.title ?? path.parse(input).name;
+    // Table of contents: at the [[toc]] marker, or at the start with --toc.
+    let body = md.html;
+    const toc = buildToc(md.headings, options.tocDepth, strings(options.lang).toc);
+    if (md.hasTocMarker) {
+        body = body.replace(tocPlaceholder(md.nonce), () => toc);
+    }
+    else if (options.toc) {
+        body = toc + body;
+    }
+    // Mermaid needs a real DOM to lay out diagrams, also for HTML output.
+    if (md.mermaid.length > 0) {
+        const session = await browsers.get();
+        const width = contentWidthPx(options.pageSize, options.landscape, margin);
+        const theme = effectiveMermaidTheme(options);
+        const results = await renderMermaid(session, md.mermaid, theme, width);
+        const filled = fillMermaid(body, md.nonce, md.mermaid, results);
+        body = filled.html;
+        diagnostics.push(...filled.diagnostics);
+    }
+    const html = buildHtmlDocument({
+        title,
+        body,
+        math: md.hasMath,
+        lang: options.lang,
+        subtitle: options.subtitle,
+        author: options.author,
+        date: options.date,
+        showTitle: options.title !== undefined,
+        themeCss,
+        extraCss,
+    });
+    diagnostics.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+    const dependencies = [
+        ...(configFile ? [configFile] : []),
+        ...(options.theme.endsWith(".css") ? [options.theme] : []),
+        ...options.css,
+    ];
+    return { html, title, diagnostics, options, configFile, dependencies };
+}
+/** Read a Markdown file and write it as a self-contained HTML document or a PDF. */
+export async function convertFile(convert) {
+    const output = path.resolve(convert.output);
+    const browsers = convert.browsers ?? new BrowserPool(convert.browser);
+    try {
+        const doc = await renderDocument(convert.input, convert, browsers);
+        const { options } = doc;
+        await mkdir(path.dirname(output), { recursive: true });
+        if (convert.format === "pdf") {
+            const margin = parseMargin(options.margin);
+            const values = { title: doc.title, author: options.author, date: options.date };
+            const footer = options.footer ?? (options.pageNumbers ? DEFAULT_FOOTER : undefined);
+            const hasHeaderFooter = options.header !== undefined || footer !== undefined;
+            const session = await browsers.get();
+            const { blocked } = await session.printPdf(doc.html, {
+                output,
+                format: options.pageSize,
+                landscape: options.landscape,
+                margin,
+                headerTemplate: hasHeaderFooter
+                    ? headerFooterTemplate(options.header, values, margin)
+                    : undefined,
+                footerTemplate: hasHeaderFooter ? headerFooterTemplate(footer, values, margin) : undefined,
+                allowRemote: convert.allowRemote,
+            });
+            for (const url of blocked) {
+                const hint = /^https?:/i.test(url) ? " (use --allow-remote to download it)" : "";
+                doc.diagnostics.push({
+                    severity: "warning",
+                    message: `resource not loaded: ${url}${hint}`,
+                });
+            }
+        }
+        else {
+            await writeFile(output, doc.html, "utf8");
+        }
+        return {
+            output,
+            diagnostics: doc.diagnostics,
+            options,
+            configFile: doc.configFile,
+            dependencies: doc.dependencies,
+        };
+    }
+    finally {
+        if (!convert.browsers)
+            await browsers.close();
+    }
+}
+//# sourceMappingURL=convert.js.map

package/dist/diagnostics.d.ts

@@ -0,0 +1,8 @@
+export interface Diagnostic {
+    severity: "warning" | "error";
+    message: string;
+    /** 1-based line in the Markdown source, when known. */
+    line?: number;
+}
+/** `file:line: message`, the conventional compiler-style location prefix. */
+export declare function formatDiagnostic(diagnostic: Diagnostic, file?: string): string;

package/dist/diagnostics.js

@@ -0,0 +1,6 @@
+/** `file:line: message`, the conventional compiler-style location prefix. */
+export function formatDiagnostic(diagnostic, file) {
+    const location = [file, diagnostic.line].filter((part) => part !== undefined).join(":");
+    return `${diagnostic.severity}: ${location ? `${location}: ` : ""}${diagnostic.message}`;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import { ExitCode } from "./exit-codes.js";
+/** An expected failure with a user-facing message and a specific exit code. */
+export declare class MdRenderError extends Error {
+    readonly exitCode: ExitCode;
+    constructor(message: string, exitCode: ExitCode);
+}
+export declare class BrowserNotFoundError extends MdRenderError {
+    constructor(message: string);
+}
+export declare class RenderError extends MdRenderError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,21 @@
+import { ExitCode } from "./exit-codes.js";
+/** An expected failure with a user-facing message and a specific exit code. */
+export class MdRenderError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = new.target.name;
+    }
+}
+export class BrowserNotFoundError extends MdRenderError {
+    constructor(message) {
+        super(message, ExitCode.BrowserNotFound);
+    }
+}
+export class RenderError extends MdRenderError {
+    constructor(message) {
+        super(message, ExitCode.Render);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/exit-codes.d.ts

@@ -0,0 +1,8 @@
+/** Process exit codes, as documented in docs/PLAN_MAESTRO.md §3. */
+export declare const ExitCode: {
+    readonly Ok: 0;
+    readonly Usage: 1;
+    readonly Render: 2;
+    readonly BrowserNotFound: 3;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/exit-codes.js

@@ -0,0 +1,8 @@
+/** Process exit codes, as documented in docs/PLAN_MAESTRO.md §3. */
+export const ExitCode = {
+    Ok: 0,
+    Usage: 1,
+    Render: 2,
+    BrowserNotFound: 3,
+};
+//# sourceMappingURL=exit-codes.js.map

package/dist/frontmatter.d.ts

@@ -0,0 +1,10 @@
+export interface FrontMatter {
+    data: Record<string, unknown>;
+    /**
+     * The Markdown without the front matter block. The block is replaced by empty lines so that
+     * line numbers in diagnostics still match the original file.
+     */
+    body: string;
+}
+/** Split a leading YAML front matter block (`---` ... `---`) from the Markdown source. */
+export declare function extractFrontMatter(source: string, file?: string): FrontMatter;

package/dist/frontmatter.js

@@ -0,0 +1,26 @@
+import { parse } from "yaml";
+import { OptionsError } from "./options.js";
+const BLOCK = /^---[ \t]*\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/;
+/** Split a leading YAML front matter block (`---` ... `---`) from the Markdown source. */
+export function extractFrontMatter(source, file = "front matter") {
+    const text = source.replace(/^\uFEFF/, "");
+    const match = BLOCK.exec(text);
+    if (!match)
+        return { data: {}, body: text };
+    let data;
+    try {
+        data = parse(match[1]) ?? {};
+    }
+    catch (error) {
+        throw new OptionsError(`${file}: invalid YAML front matter: ${error.message}`);
+    }
+    if (typeof data !== "object" || Array.isArray(data)) {
+        throw new OptionsError(`${file}: front matter must be a set of "key: value" pairs`);
+    }
+    const lines = match[0].split("\n").length - 1;
+    return {
+        data: data,
+        body: "\n".repeat(lines) + text.slice(match[0].length),
+    };
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/html.d.ts

@@ -0,0 +1,2 @@
+/** Escape text for use in HTML content and attribute values. */
+export declare function escapeHtml(text: string): string;

package/dist/html.js

@@ -0,0 +1,12 @@
+const ENTITIES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+/** Escape text for use in HTML content and attribute values. */
+export function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => ENTITIES[c]);
+}
+//# sourceMappingURL=html.js.map

package/dist/i18n.d.ts

@@ -0,0 +1,9 @@
+export type AlertType = "note" | "tip" | "important" | "warning" | "caution";
+export interface Strings {
+    toc: string;
+    alerts: Record<AlertType, string>;
+}
+/** Default document language: Spanish. English and others are available with `lang`. */
+export declare const DEFAULT_LANG = "es";
+/** UI strings for a BCP 47 language tag ("es-AR" uses "es"); Spanish as fallback. */
+export declare function strings(lang: string): Strings;

package/dist/i18n.js

@@ -0,0 +1,59 @@
+const STRINGS = {
+    en: {
+        toc: "Contents",
+        alerts: {
+            note: "Note",
+            tip: "Tip",
+            important: "Important",
+            warning: "Warning",
+            caution: "Caution",
+        },
+    },
+    es: {
+        toc: "Contenido",
+        alerts: {
+            note: "Nota",
+            tip: "Consejo",
+            important: "Importante",
+            warning: "Advertencia",
+            caution: "Precaución",
+        },
+    },
+    pt: {
+        toc: "Sumário",
+        alerts: {
+            note: "Nota",
+            tip: "Dica",
+            important: "Importante",
+            warning: "Aviso",
+            caution: "Cuidado",
+        },
+    },
+    fr: {
+        toc: "Sommaire",
+        alerts: {
+            note: "Remarque",
+            tip: "Astuce",
+            important: "Important",
+            warning: "Avertissement",
+            caution: "Attention",
+        },
+    },
+    de: {
+        toc: "Inhalt",
+        alerts: {
+            note: "Hinweis",
+            tip: "Tipp",
+            important: "Wichtig",
+            warning: "Warnung",
+            caution: "Vorsicht",
+        },
+    },
+};
+/** Default document language: Spanish. English and others are available with `lang`. */
+export const DEFAULT_LANG = "es";
+/** UI strings for a BCP 47 language tag ("es-AR" uses "es"); Spanish as fallback. */
+export function strings(lang) {
+    return STRINGS[lang.toLowerCase().split("-")[0]] ?? STRINGS[DEFAULT_LANG];
+}
+//# sourceMappingURL=i18n.js.map

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { findBrowser, browserCandidates } from "./browser/detect.js";
+export { main } from "./cli.js";
+export { CONFIG_FILE, findConfigFile, loadConfig } from "./config.js";
+export { BrowserPool, convertFile, renderDocument, type ConvertOptions, type ConvertResult, type RenderSettings, } from "./convert.js";
+export { formatDiagnostic, type Diagnostic } from "./diagnostics.js";
+export { BrowserNotFoundError, MdRenderError, RenderError } from "./errors.js";
+export { ExitCode } from "./exit-codes.js";
+export { renderMarkdown, type MarkdownResult } from "./markdown/index.js";
+export { extractFrontMatter } from "./frontmatter.js";
+export { DEFAULT_OPTIONS, mergeOptions, normalizeOptions, OptionsError, type DocumentOptions, } from "./options.js";
+export { expandInputs, planOutputs, type InputFile, type Job } from "./inputs.js";
+export { isMarkdownFile, type OutputFormat } from "./paths.js";
+export { preview } from "./preview.js";
+export { runJobs } from "./run.js";
+export { watchAndConvert } from "./watch.js";
+export { buildHtmlDocument } from "./render/template.js";
+export { version } from "./version.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+export { findBrowser, browserCandidates } from "./browser/detect.js";
+export { main } from "./cli.js";
+export { CONFIG_FILE, findConfigFile, loadConfig } from "./config.js";
+export { BrowserPool, convertFile, renderDocument, } from "./convert.js";
+export { formatDiagnostic } from "./diagnostics.js";
+export { BrowserNotFoundError, MdRenderError, RenderError } from "./errors.js";
+export { ExitCode } from "./exit-codes.js";
+export { renderMarkdown } from "./markdown/index.js";
+export { extractFrontMatter } from "./frontmatter.js";
+export { DEFAULT_OPTIONS, mergeOptions, normalizeOptions, OptionsError, } from "./options.js";
+export { expandInputs, planOutputs } from "./inputs.js";
+export { isMarkdownFile } from "./paths.js";
+export { preview } from "./preview.js";
+export { runJobs } from "./run.js";
+export { watchAndConvert } from "./watch.js";
+export { buildHtmlDocument } from "./render/template.js";
+export { version } from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/inputs.d.ts

@@ -0,0 +1,26 @@
+import { type OutputFormat } from "./paths.js";
+/** A Markdown file to convert, with the folder its output path is relative to. */
+export interface InputFile {
+    file: string;
+    /** Directory or glob base the file was found under; undefined for files named directly. */
+    root?: string;
+}
+/**
+ * Expand command-line inputs into Markdown files: files as given, folders searched recursively
+ * (skipping hidden folders and node_modules), and glob patterns (`docs/**\/*.md`) expanded here
+ * so they also work in Windows shells, which do not expand them.
+ */
+export declare function expandInputs(inputs: string[], cwd?: string): InputFile[];
+export interface Job {
+    input: string;
+    output: string;
+}
+/**
+ * Decide each output path.
+ *
+ * - No `output`: next to each Markdown file.
+ * - One input file and `output` is not a folder: `output` is the file to write.
+ * - Otherwise `output` is a folder; files found under a folder or glob keep their relative
+ *   path inside it, so `docs/a/x.md` → `out/a/x.pdf`.
+ */
+export declare function planOutputs(inputs: InputFile[], format: OutputFormat, output?: string, cwd?: string): Job[];

package/dist/inputs.js

@@ -0,0 +1,118 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { globSync, isDynamicPattern } from "tinyglobby";
+import { OptionsError } from "./options.js";
+import { isMarkdownFile } from "./paths.js";
+/** Folders never searched when an input is a directory or a glob. */
+const SKIPPED_DIRS = new Set(["node_modules"]);
+function walk(dir, found) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith(".") || SKIPPED_DIRS.has(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            walk(full, found);
+        else if (entry.isFile() && isMarkdownFile(entry.name))
+            found.push(full);
+    }
+}
+/** Leading part of a glob without wildcards, e.g. "docs/" for "docs/**\/*.md". */
+function globBase(pattern) {
+    const parts = pattern.split("/");
+    const fixed = [];
+    for (const part of parts.slice(0, -1)) {
+        if (isDynamicPattern(part))
+            break;
+        fixed.push(part);
+    }
+    return fixed.join("/") || ".";
+}
+/**
+ * Expand command-line inputs into Markdown files: files as given, folders searched recursively
+ * (skipping hidden folders and node_modules), and glob patterns (`docs/**\/*.md`) expanded here
+ * so they also work in Windows shells, which do not expand them.
+ */
+export function expandInputs(inputs, cwd = process.cwd()) {
+    const files = [];
+    for (const input of inputs) {
+        const resolved = path.resolve(cwd, input);
+        if (existsSync(resolved)) {
+            if (statSync(resolved).isDirectory()) {
+                const found = [];
+                walk(resolved, found);
+                if (found.length === 0)
+                    throw new OptionsError(`no Markdown files in folder: ${input}`);
+                files.push(...found.sort().map((file) => ({ file, root: resolved })));
+            }
+            else if (isMarkdownFile(resolved)) {
+                files.push({ file: resolved });
+            }
+            else {
+                throw new OptionsError(`input is not a Markdown file (.md, .markdown): ${input}`);
+            }
+            continue;
+        }
+        const pattern = input.replace(/\\/g, "/");
+        if (isDynamicPattern(pattern)) {
+            const matches = globSync(pattern, {
+                cwd,
+                absolute: true,
+                onlyFiles: true,
+                ignore: ["**/node_modules/**", "**/.*/**"],
+            })
+                .filter(isMarkdownFile)
+                .map((file) => path.resolve(file))
+                .sort();
+            if (matches.length === 0)
+                throw new OptionsError(`no Markdown files match: ${input}`);
+            const root = path.resolve(cwd, globBase(pattern));
+            files.push(...matches.map((file) => ({ file, root })));
+            continue;
+        }
+        throw new OptionsError(`input file not found: ${input}`);
+    }
+    // The same file may be reached twice (e.g. a folder and a glob): keep the first.
+    const seen = new Set();
+    return files.filter(({ file }) => !seen.has(file) && seen.add(file));
+}
+/**
+ * Decide each output path.
+ *
+ * - No `output`: next to each Markdown file.
+ * - One input file and `output` is not a folder: `output` is the file to write.
+ * - Otherwise `output` is a folder; files found under a folder or glob keep their relative
+ *   path inside it, so `docs/a/x.md` → `out/a/x.pdf`.
+ */
+export function planOutputs(inputs, format, output, cwd = process.cwd()) {
+    const ext = `.${format}`;
+    const outDir = output !== undefined ? path.resolve(cwd, output) : undefined;
+    const several = inputs.length > 1 || inputs[0]?.root !== undefined;
+    const looksLikeFile = output !== undefined && /\.(pdf|html?)$/i.test(output);
+    const outputIsDir = outDir !== undefined &&
+        (/[\\/]$/.test(output) ||
+            (existsSync(outDir) ? statSync(outDir).isDirectory() : several && !looksLikeFile));
+    if (outDir && !outputIsDir) {
+        if (several) {
+            throw new OptionsError(`with several input files, --output must be a folder: ${output}`);
+        }
+        return [{ input: inputs[0].file, output: outDir }];
+    }
+    const jobs = inputs.map(({ file, root }) => {
+        const name = path.parse(file).name + ext;
+        if (!outDir)
+            return { input: file, output: path.join(path.dirname(file), name) };
+        const relativeDir = root ? path.relative(root, path.dirname(file)) : "";
+        return { input: file, output: path.join(outDir, relativeDir, name) };
+    });
+    const targets = new Map();
+    for (const job of jobs) {
+        const key = process.platform === "win32" ? job.output.toLowerCase() : job.output;
+        const other = targets.get(key);
+        if (other) {
+            throw new OptionsError(`${other} and ${job.input} would both be written to ${job.output}`);
+        }
+        targets.set(key, job.input);
+    }
+    return jobs;
+}
+//# sourceMappingURL=inputs.js.map

package/dist/markdown/alerts.d.ts

@@ -0,0 +1,6 @@
+import type { MarkdownIt } from "markdown-it";
+/**
+ * GitHub alerts: a blockquote whose first line is `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`,
+ * `[!WARNING]` or `[!CAUTION]` becomes a styled callout with a title.
+ */
+export declare function alerts(md: MarkdownIt): void;

package/dist/markdown/alerts.js

@@ -0,0 +1,35 @@
+import { DEFAULT_LANG, strings } from "../i18n.js";
+const MARKER = /^\[!(note|tip|important|warning|caution)\][ \t]*$/i;
+/**
+ * GitHub alerts: a blockquote whose first line is `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`,
+ * `[!WARNING]` or `[!CAUTION]` becomes a styled callout with a title.
+ */
+export function alerts(md) {
+    md.core.ruler.after("inline", "github_alerts", (state) => {
+        const tokens = state.tokens;
+        const titles = strings(state.env.lang ?? DEFAULT_LANG).alerts;
+        for (let i = 0; i + 2 < tokens.length; i++) {
+            const open = tokens[i];
+            const inline = tokens[i + 2];
+            if (open.type !== "blockquote_open" || tokens[i + 1].type !== "paragraph_open")
+                continue;
+            const first = inline.children?.[0];
+            const match = first?.type === "text" ? MARKER.exec(first.content) : null;
+            if (!match)
+                continue;
+            const type = match[1].toLowerCase();
+            open.attrJoin("class", `markdown-alert markdown-alert-${type}`);
+            // Drop the marker (and the line break after it); drop the paragraph if nothing is left.
+            const children = inline.children;
+            children.splice(0, children[1]?.type === "softbreak" ? 2 : 1);
+            inline.content = inline.content.replace(/^[^\n]*\n?/, "");
+            if (children.length === 0) {
+                tokens.splice(i + 1, 3);
+            }
+            const title = new state.Token("html_block", "", 0);
+            title.content = `<p class="markdown-alert-title">${titles[type]}</p>\n`;
+            tokens.splice(i + 1, 0, title);
+        }
+    });
+}
+//# sourceMappingURL=alerts.js.map

package/dist/markdown/env.d.ts

@@ -0,0 +1,29 @@
+import type { Env, MarkdownIt, Token } from "markdown-it";
+import type { Diagnostic } from "../diagnostics.js";
+export interface MermaidBlock {
+    source: string;
+    /** 1-based source line of the opening fence. */
+    line?: number;
+}
+/** Per-document state shared by the Markdown plugins during one render. */
+export interface RenderEnv extends Env {
+    /** Directory that relative image paths are resolved against (the .md file's folder). */
+    baseDir: string;
+    diagnostics: Diagnostic[];
+    /** Mermaid diagrams found in the document, rendered later in a browser. */
+    mermaid: MermaidBlock[];
+    /** Random token that makes Mermaid placeholders impossible to forge from Markdown. */
+    nonce: string;
+    /** KaTeX macros, shared by every formula so `\newcommand`/`\def` work across the document. */
+    macros: Record<string, string | object>;
+    /** Set when the document contains at least one formula. */
+    hasMath: boolean;
+    /** Document language, for translated labels (alert titles). */
+    lang: string;
+    /** Set when the document places its table of contents with a `[[toc]]` marker. */
+    hasTocMarker: boolean;
+}
+/** 1-based line of a token, from markdown-it's 0-based `[start, end)` line map. */
+export declare function tokenLine(token: Token): number | undefined;
+/** Copy each inline token's line map to its children so inline errors can report a line. */
+export declare function inlineChildLines(md: MarkdownIt): void;

package/dist/markdown/env.js

@@ -0,0 +1,16 @@
+/** 1-based line of a token, from markdown-it's 0-based `[start, end)` line map. */
+export function tokenLine(token) {
+    return token.map ? token.map[0] + 1 : undefined;
+}
+/** Copy each inline token's line map to its children so inline errors can report a line. */
+export function inlineChildLines(md) {
+    md.core.ruler.push("inline_child_lines", (state) => {
+        for (const token of state.tokens) {
+            if (token.type !== "inline" || !token.map)
+                continue;
+            for (const child of token.children ?? [])
+                child.map ??= token.map;
+        }
+    });
+}
+//# sourceMappingURL=env.js.map

package/dist/markdown/highlight.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Syntax highlighting for fenced code with a language (` ```ts `). highlight.js's "common" set
+ * covers ~35 popular languages. Unknown or missing languages are shown as plain text: no
+ * auto-detection, so output never changes with heuristics.
+ */
+export declare function highlightCode(code: string, lang: string): string;