@imontene/mdrender 1.0.0

package/dist/markdown/highlight.js

@@ -0,0 +1,17 @@
+import hljs from "highlight.js/lib/common";
+import { escapeHtml } from "../html.js";
+/**
+ * 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 function highlightCode(code, lang) {
+    const language = lang.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+    if (language && hljs.getLanguage(language)) {
+        const { value } = hljs.highlight(code, { language, ignoreIllegals: true });
+        return `<pre class="hljs"><code class="language-${escapeHtml(language)}">${value}</code></pre>`;
+    }
+    // Empty string: markdown-it falls back to its default escaped <pre><code> block.
+    return "";
+}
+//# sourceMappingURL=highlight.js.map

package/dist/markdown/images.d.ts

@@ -0,0 +1,9 @@
+import type { MarkdownIt } from "markdown-it";
+/** Resolve an image `src` to a local file path, or undefined for remote/data URLs. */
+export declare function localImagePath(src: string, baseDir: string): string | undefined;
+/**
+ * Embed local images as data URIs so the output is self-contained and the browser never needs
+ * file system access: Markdown images (`![alt](img.png)`) and `<img src="img.png">` in raw HTML.
+ * Remote images are left untouched.
+ */
+export declare function inlineLocalImages(md: MarkdownIt): void;

package/dist/markdown/images.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { tokenLine } from "./env.js";
+const MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+};
+/** Resolve an image `src` to a local file path, or undefined for remote/data URLs. */
+export function localImagePath(src, baseDir) {
+    if (/^data:/i.test(src))
+        return undefined;
+    if (/^file:/i.test(src))
+        return fileURLToPath(src);
+    // Any other URL scheme (http:, https:, ...) but not a Windows drive letter like C:\
+    if (/^[a-z][a-z0-9+.-]+:/i.test(src) && !/^[a-z]:[\\/]/i.test(src))
+        return undefined;
+    const withoutQuery = src.replace(/[?#].*$/, "");
+    let decoded = withoutQuery;
+    try {
+        decoded = decodeURI(withoutQuery);
+    }
+    catch {
+        // keep the raw path if it is not valid percent-encoding
+    }
+    return path.resolve(baseDir, decoded);
+}
+function toDataUri(file) {
+    const mime = MIME_TYPES[path.extname(file).toLowerCase()];
+    if (!mime)
+        return undefined;
+    return `data:${mime};base64,${readFileSync(file).toString("base64")}`;
+}
+function warn(env, message, line) {
+    env.diagnostics.push({ severity: "warning", message, line });
+}
+/**
+ * Replace a local image reference by a data URI. Returns the new src, or undefined to keep the
+ * original (remote URL, data URI, or a problem that was reported as a warning).
+ */
+function embed(src, env, line) {
+    const file = localImagePath(src, env.baseDir);
+    if (!file)
+        return undefined;
+    if (!existsSync(file) || !statSync(file).isFile()) {
+        warn(env, `image not found: ${src}`, line);
+        return undefined;
+    }
+    const dataUri = toDataUri(file);
+    if (!dataUri)
+        warn(env, `unsupported image type: ${src}`, line);
+    return dataUri;
+}
+const HTML_IMG_SRC = /(<img\b[^>]*?\bsrc\s*=\s*)(["'])(.*?)\2/gi;
+/**
+ * Embed local images as data URIs so the output is self-contained and the browser never needs
+ * file system access: Markdown images (`![alt](img.png)`) and `<img src="img.png">` in raw HTML.
+ * Remote images are left untouched.
+ */
+export function inlineLocalImages(md) {
+    const fallback = md.renderer.rules.image;
+    md.renderer.rules.image = (tokens, idx, options, rawEnv, self) => {
+        const env = rawEnv;
+        const token = tokens[idx];
+        const src = String(token.attrGet("src") ?? "");
+        const dataUri = src && env?.baseDir ? embed(src, env, tokenLine(token)) : undefined;
+        if (dataUri)
+            token.attrSet("src", dataUri);
+        return fallback(tokens, idx, options, env, self);
+    };
+    for (const rule of ["html_block", "html_inline"]) {
+        const original = md.renderer.rules[rule];
+        md.renderer.rules[rule] = (tokens, idx, options, rawEnv, self) => {
+            const env = rawEnv;
+            const token = tokens[idx];
+            if (env?.baseDir && /<img\b/i.test(token.content)) {
+                token.content = token.content.replace(HTML_IMG_SRC, (match, prefix, quote, src) => {
+                    const dataUri = embed(md.utils.unescapeAll(src), env, tokenLine(token));
+                    return dataUri ? `${prefix}${quote}${dataUri}${quote}` : match;
+                });
+            }
+            return original(tokens, idx, options, env, self);
+        };
+    }
+}
+//# sourceMappingURL=images.js.map

package/dist/markdown/index.d.ts

@@ -0,0 +1,27 @@
+import { type MarkdownIt } from "markdown-it";
+import type { Diagnostic } from "../diagnostics.js";
+import { type MermaidBlock } from "./env.js";
+import { type Heading } from "./toc.js";
+export interface MarkdownResult {
+    /** HTML fragment for the document body; Mermaid diagrams are still placeholders. */
+    html: string;
+    /** Text of the first level-1 heading, if any. */
+    title?: string;
+    diagnostics: Diagnostic[];
+    /** Mermaid sources, in document order, to render with `fillMermaid`. */
+    mermaid: MermaidBlock[];
+    /** Token identifying this render's placeholders (Mermaid diagrams, table of contents). */
+    nonce: string;
+    hasMath: boolean;
+    headings: Heading[];
+    /** The document has a `[[toc]]` marker (its placeholder is in `html`). */
+    hasTocMarker: boolean;
+}
+export interface MarkdownOptions {
+    /** Directory used to resolve relative image paths. Defaults to the current directory. */
+    baseDir?: string;
+    /** Document language for translated labels. Defaults to Spanish. */
+    lang?: string;
+}
+export declare function createMarkdown(): MarkdownIt;
+export declare function renderMarkdown(source: string, options?: MarkdownOptions): MarkdownResult;

package/dist/markdown/index.js

@@ -0,0 +1,69 @@
+import { randomBytes } from "node:crypto";
+import markdownIt, {} from "markdown-it";
+import anchor from "markdown-it-anchor";
+import footnote from "markdown-it-footnote";
+import { DEFAULT_LANG } from "../i18n.js";
+import { alerts } from "./alerts.js";
+import { inlineChildLines } from "./env.js";
+import { highlightCode } from "./highlight.js";
+import { inlineLocalImages } from "./images.js";
+import { math } from "./math.js";
+import { mermaid } from "./mermaid.js";
+import { taskLists } from "./task-lists.js";
+import { collectHeadings, tocMarker } from "./toc.js";
+export function createMarkdown() {
+    const md = markdownIt({
+        html: true,
+        linkify: true,
+        typographer: false,
+        highlight: highlightCode,
+    });
+    md.use(anchor, { tabIndex: false });
+    md.use(footnote);
+    md.use(taskLists);
+    md.use(alerts);
+    md.use(tocMarker);
+    md.use(inlineChildLines);
+    md.use(inlineLocalImages);
+    md.use(math);
+    md.use(mermaid);
+    return md;
+}
+let shared;
+export function renderMarkdown(source, options = {}) {
+    const md = (shared ??= createMarkdown());
+    const env = {
+        baseDir: options.baseDir ?? process.cwd(),
+        diagnostics: [],
+        mermaid: [],
+        nonce: randomBytes(8).toString("hex"),
+        macros: {},
+        hasMath: false,
+        lang: options.lang ?? DEFAULT_LANG,
+        hasTocMarker: false,
+    };
+    const tokens = md.parse(source, env);
+    let title;
+    const h1 = tokens.findIndex((t) => t.type === "heading_open" && t.tag === "h1");
+    if (h1 !== -1) {
+        title = tokens[h1 + 1]?.children
+            ?.filter((t) => t.type === "text" || t.type === "code_inline")
+            .map((t) => t.content)
+            .join("")
+            .trim();
+    }
+    const html = md.renderer.render(tokens, md.options, env);
+    // Separate diagnostics: headings are rendered a second time for the table of contents.
+    const headings = collectHeadings(md, tokens, { ...env, diagnostics: [] });
+    return {
+        html,
+        title: title || undefined,
+        diagnostics: env.diagnostics,
+        mermaid: env.mermaid,
+        nonce: env.nonce,
+        hasMath: env.hasMath,
+        headings,
+        hasTocMarker: env.hasTocMarker,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/markdown/math.d.ts

@@ -0,0 +1,9 @@
+import type { MarkdownIt, Token } from "markdown-it";
+import { type RenderEnv } from "./env.js";
+/** Render TeX with KaTeX; on failure record an error and show the source highlighted instead. */
+export declare function renderTex(tex: string, displayMode: boolean, env: RenderEnv, token: Token): string;
+/**
+ * LaTeX math rendered at build time with KaTeX (no JavaScript needed in the output):
+ * `$inline$`, `$$display$$` blocks and ```` ```math ```` fences (GitHub syntax).
+ */
+export declare function math(md: MarkdownIt): void;

package/dist/markdown/math.js

@@ -0,0 +1,147 @@
+import katex from "katex";
+import { escapeHtml } from "../html.js";
+import { tokenLine } from "./env.js";
+const DOLLAR = 0x24;
+const BACKSLASH = 0x5c;
+const isWhitespace = (ch) => ch === undefined || /\s/.test(ch);
+const isDigit = (ch) => ch !== undefined && ch >= "0" && ch <= "9";
+/** Index of the next `$` (or `$$`) at or after `from` that is not backslash-escaped, or -1. */
+function findClosing(src, from, delimiter) {
+    for (let i = from; i < src.length; i++) {
+        if (src.charCodeAt(i) === BACKSLASH) {
+            i++;
+            continue;
+        }
+        if (src.startsWith(delimiter, i))
+            return i;
+    }
+    return -1;
+}
+/**
+ * Inline math: `$...$` and `$$...$$` inside a paragraph.
+ *
+ * Follows Pandoc's rules so prices like "$5 and $10" stay text: the opening `$` must not be
+ * followed by whitespace, and the closing `$` must not be preceded by whitespace nor followed by
+ * a digit.
+ */
+function mathInline(state, silent) {
+    const { src, pos } = state;
+    if (src.charCodeAt(pos) !== DOLLAR)
+        return false;
+    const display = src.charCodeAt(pos + 1) === DOLLAR;
+    const delimiter = display ? "$$" : "$";
+    const start = pos + delimiter.length;
+    if (!display && isWhitespace(src[start]))
+        return false;
+    const end = findClosing(src, start, delimiter);
+    if (end === -1 || end === start)
+        return false;
+    if (!display && (isWhitespace(src[end - 1]) || isDigit(src[end + 1])))
+        return false;
+    if (!silent) {
+        const token = state.push(display ? "math_inline_display" : "math_inline", "math", 0);
+        token.content = src.slice(start, end);
+        token.markup = delimiter;
+    }
+    state.pos = end + delimiter.length;
+    return true;
+}
+/** Block math: a paragraph opened by `$$`, on one line (`$$ x $$`) or spanning several. */
+function mathBlock(state, startLine, endLine, silent) {
+    let pos = state.bMarks[startLine] + state.tShift[startLine];
+    let max = state.eMarks[startLine];
+    if (state.sCount[startLine] - state.blkIndent >= 4)
+        return false;
+    if (!state.src.startsWith("$$", pos))
+        return false;
+    pos += 2;
+    let firstLine = state.src.slice(pos, max);
+    let lastLine = "";
+    let nextLine = startLine;
+    let found = false;
+    if (firstLine.trim().endsWith("$$")) {
+        // Single line: $$ ... $$
+        firstLine = firstLine.trim().slice(0, -2);
+        found = true;
+    }
+    else {
+        while (++nextLine < endLine) {
+            pos = state.bMarks[nextLine] + state.tShift[nextLine];
+            max = state.eMarks[nextLine];
+            if (pos < max && state.sCount[nextLine] < state.blkIndent)
+                break;
+            const text = state.src.slice(pos, max).trimEnd();
+            if (text.endsWith("$$")) {
+                lastLine = text.slice(0, -2);
+                found = true;
+                break;
+            }
+        }
+    }
+    if (!found)
+        return false;
+    if (silent)
+        return true;
+    const body = nextLine === startLine
+        ? firstLine
+        : [
+            firstLine,
+            state.getLines(startLine + 1, nextLine, state.tShift[startLine], false),
+            lastLine,
+        ].join("\n");
+    const token = state.push("math_block", "math", 0);
+    token.block = true;
+    token.content = body.trim();
+    token.map = [startLine, nextLine + 1];
+    token.markup = "$$";
+    state.line = nextLine + 1;
+    return true;
+}
+/** Render TeX with KaTeX; on failure record an error and show the source highlighted instead. */
+export function renderTex(tex, displayMode, env, token) {
+    env.hasMath = true;
+    try {
+        return katex.renderToString(tex, {
+            displayMode,
+            throwOnError: true,
+            output: "html",
+            strict: "ignore",
+            trust: false,
+            globalGroup: true,
+            macros: env.macros,
+        });
+    }
+    catch (error) {
+        const message = error instanceof katex.ParseError ? error.rawMessage : String(error);
+        env.diagnostics.push({
+            severity: "error",
+            message: `LaTeX: ${message}`,
+            line: tokenLine(token),
+        });
+        const tag = displayMode ? "div" : "span";
+        return `<${tag} class="math-error" title="${escapeHtml(message)}">${escapeHtml(tex)}</${tag}>`;
+    }
+}
+/**
+ * LaTeX math rendered at build time with KaTeX (no JavaScript needed in the output):
+ * `$inline$`, `$$display$$` blocks and ```` ```math ```` fences (GitHub syntax).
+ */
+export function math(md) {
+    md.inline.ruler.after("escape", "math_inline", mathInline);
+    md.block.ruler.before("fence", "math_block", mathBlock, {
+        alt: ["paragraph", "reference", "blockquote", "list"],
+    });
+    const rules = md.renderer.rules;
+    rules.math_inline = (tokens, idx, _options, env) => renderTex(tokens[idx].content, false, env, tokens[idx]);
+    rules.math_inline_display = (tokens, idx, _options, env) => renderTex(tokens[idx].content, true, env, tokens[idx]);
+    rules.math_block = (tokens, idx, _options, env) => `<div class="math-display">${renderTex(tokens[idx].content, true, env, tokens[idx])}</div>\n`;
+    const fence = rules.fence;
+    rules.fence = (tokens, idx, options, env, self) => {
+        const token = tokens[idx];
+        if (token.info.trim().toLowerCase() === "math") {
+            return `<div class="math-display">${renderTex(token.content, true, env, token)}</div>\n`;
+        }
+        return fence(tokens, idx, options, env, self);
+    };
+}
+//# sourceMappingURL=math.js.map

package/dist/markdown/mermaid.d.ts

@@ -0,0 +1,8 @@
+import type { MarkdownIt } from "markdown-it";
+/** Placeholder left in the HTML for diagram `index`; replaced once the browser renders it. */
+export declare function mermaidPlaceholder(nonce: string, index: number): string;
+/**
+ * ```` ```mermaid ```` fences are collected into `env.mermaid` and replaced by a placeholder.
+ * Rendering needs a real DOM, so it happens later in the browser (see render/mermaid.ts).
+ */
+export declare function mermaid(md: MarkdownIt): void;

package/dist/markdown/mermaid.js

@@ -0,0 +1,22 @@
+import { tokenLine } from "./env.js";
+/** Placeholder left in the HTML for diagram `index`; replaced once the browser renders it. */
+export function mermaidPlaceholder(nonce, index) {
+    return `<!--mermaid:${nonce}:${index}-->`;
+}
+/**
+ * ```` ```mermaid ```` fences are collected into `env.mermaid` and replaced by a placeholder.
+ * Rendering needs a real DOM, so it happens later in the browser (see render/mermaid.ts).
+ */
+export function mermaid(md) {
+    const fence = md.renderer.rules.fence;
+    md.renderer.rules.fence = (tokens, idx, options, rawEnv, self) => {
+        const token = tokens[idx];
+        if (token.info.trim().toLowerCase() !== "mermaid") {
+            return fence(tokens, idx, options, rawEnv, self);
+        }
+        const env = rawEnv;
+        const index = env.mermaid.push({ source: token.content, line: tokenLine(token) }) - 1;
+        return `<figure class="mermaid-diagram">${mermaidPlaceholder(env.nonce, index)}</figure>\n`;
+    };
+}
+//# sourceMappingURL=mermaid.js.map

package/dist/markdown/task-lists.d.ts

@@ -0,0 +1,6 @@
+import type { MarkdownIt } from "markdown-it";
+/**
+ * GFM task lists: `- [ ] todo` / `- [x] done` become disabled checkboxes.
+ * Adds `task-list-item` to the <li> and `contains-task-list` to the parent list, like GitHub.
+ */
+export declare function taskLists(md: MarkdownIt): void;

package/dist/markdown/task-lists.js

@@ -0,0 +1,40 @@
+const TASK_MARKER = /^\[([ xX])\](?:[ \u00a0]|$)/;
+/**
+ * GFM task lists: `- [ ] todo` / `- [x] done` become disabled checkboxes.
+ * Adds `task-list-item` to the <li> and `contains-task-list` to the parent list, like GitHub.
+ */
+export function taskLists(md) {
+    md.core.ruler.after("inline", "task_lists", (state) => {
+        const tokens = state.tokens;
+        for (let i = 2; i < tokens.length; i++) {
+            const inline = tokens[i];
+            const item = tokens[i - 2];
+            if (inline.type !== "inline" ||
+                tokens[i - 1].type !== "paragraph_open" ||
+                item.type !== "list_item_open") {
+                continue;
+            }
+            const first = inline.children?.[0];
+            const match = first?.type === "text" ? TASK_MARKER.exec(first.content) : null;
+            if (!first || !match)
+                continue;
+            first.content = first.content.slice(match[0].length);
+            const checkbox = new state.Token("html_inline", "", 0);
+            const checked = match[1] === " " ? "" : " checked";
+            checkbox.content = `<input type="checkbox" class="task-list-item-checkbox" disabled${checked}> `;
+            inline.children.unshift(checkbox);
+            item.attrJoin("class", "task-list-item");
+            for (let j = i - 3; j >= 0; j--) {
+                const list = tokens[j];
+                const isList = list.type === "bullet_list_open" || list.type === "ordered_list_open";
+                if (isList && list.level === item.level - 1) {
+                    if (!String(list.attrGet("class") ?? "").includes("contains-task-list")) {
+                        list.attrJoin("class", "contains-task-list");
+                    }
+                    break;
+                }
+            }
+        }
+    });
+}
+//# sourceMappingURL=task-lists.js.map

package/dist/markdown/toc.d.ts

@@ -0,0 +1,22 @@
+import type { MarkdownIt, Token } from "markdown-it";
+import type { RenderEnv } from "./env.js";
+export interface Heading {
+    level: number;
+    id: string;
+    /** Heading content as HTML (text, inline code and math), without links. */
+    html: string;
+}
+/** Placeholder for the table of contents, filled in after rendering. */
+export declare function tocPlaceholder(nonce: string): string;
+/**
+ * A paragraph containing only `[[toc]]` or `[toc]` marks where the table of contents goes.
+ * Without a marker, `--toc` puts it at the start of the document.
+ */
+export declare function tocMarker(md: MarkdownIt): void;
+/** Collect headings (with the ids set by markdown-it-anchor) from parsed tokens. */
+export declare function collectHeadings(md: MarkdownIt, tokens: Token[], env: RenderEnv): Heading[];
+/**
+ * Nested list of links to the headings up to `depth`. A single level-1 heading is the document
+ * title and is left out. Skipped levels (h2 → h4) nest under an empty item.
+ */
+export declare function buildToc(headings: Heading[], depth: number, title: string): string;

package/dist/markdown/toc.js

@@ -0,0 +1,101 @@
+import { escapeHtml } from "../html.js";
+const MARKER = /^\[\[?toc\]?\]$/i;
+/** Placeholder for the table of contents, filled in after rendering. */
+export function tocPlaceholder(nonce) {
+    return `<!--toc:${nonce}-->`;
+}
+/**
+ * A paragraph containing only `[[toc]]` or `[toc]` marks where the table of contents goes.
+ * Without a marker, `--toc` puts it at the start of the document.
+ */
+export function tocMarker(md) {
+    md.block.ruler.before("paragraph", "toc_marker", (state, startLine, _endLine, silent) => {
+        const start = state.bMarks[startLine] + state.tShift[startLine];
+        const line = state.src.slice(start, state.eMarks[startLine]).trim();
+        if (!MARKER.test(line))
+            return false;
+        if (!silent) {
+            const token = state.push("toc_marker", "", 0);
+            token.map = [startLine, startLine + 1];
+            state.line = startLine + 1;
+        }
+        return true;
+    });
+    md.renderer.rules.toc_marker = (_tokens, _idx, _options, env) => {
+        const renderEnv = env;
+        renderEnv.hasTocMarker = true;
+        return tocPlaceholder(renderEnv.nonce) + "\n";
+    };
+}
+/** Collect headings (with the ids set by markdown-it-anchor) from parsed tokens. */
+export function collectHeadings(md, tokens, env) {
+    const headings = [];
+    tokens.forEach((token, i) => {
+        if (token.type !== "heading_open")
+            return;
+        const id = token.attrGet("id");
+        const inline = tokens[i + 1];
+        if (!id || !inline?.children)
+            return;
+        const html = inline.children
+            .map((child) => {
+            switch (child.type) {
+                case "text":
+                    return escapeHtml(child.content);
+                case "code_inline":
+                    return `<code>${escapeHtml(child.content)}</code>`;
+                case "math_inline":
+                case "softbreak":
+                    return md.renderer.renderInline([child], md.options, env);
+                default:
+                    return "";
+            }
+        })
+            .join("")
+            .trim();
+        headings.push({ level: Number(token.tag.slice(1)), id: String(id), html });
+    });
+    return headings;
+}
+function renderNodes(nodes) {
+    const items = nodes.map((node) => {
+        const link = node.heading
+            ? `<a href="#${escapeHtml(node.heading.id)}">${node.heading.html}</a>`
+            : "";
+        return `<li>${link}${node.children.length ? renderNodes(node.children) : ""}</li>`;
+    });
+    return `<ul>${items.join("")}</ul>`;
+}
+/**
+ * Nested list of links to the headings up to `depth`. A single level-1 heading is the document
+ * title and is left out. Skipped levels (h2 → h4) nest under an empty item.
+ */
+export function buildToc(headings, depth, title) {
+    let items = headings.filter((h) => h.level <= depth);
+    if (headings.filter((h) => h.level === 1).length === 1)
+        items = items.filter((h) => h.level > 1);
+    if (items.length === 0)
+        return "";
+    const base = Math.min(...items.map((h) => h.level));
+    const root = { children: [] };
+    // stack[k] is the node whose children hold level base + k.
+    const stack = [root];
+    for (const heading of items) {
+        const depthIndex = heading.level - base;
+        stack.length = Math.min(stack.length, depthIndex + 1);
+        while (stack.length <= depthIndex) {
+            const parent = stack[stack.length - 1];
+            let last = parent.children[parent.children.length - 1];
+            if (!last) {
+                last = { children: [] };
+                parent.children.push(last);
+            }
+            stack.push(last);
+        }
+        const node = { heading, children: [] };
+        stack[depthIndex].children.push(node);
+        stack.push(node);
+    }
+    return `<nav class="toc"><p class="toc-title">${escapeHtml(title)}</p>\n${renderNodes(root.children)}\n</nav>\n`;
+}
+//# sourceMappingURL=toc.js.map

package/dist/options.d.ts

@@ -0,0 +1,55 @@
+import { MdRenderError } from "./errors.js";
+export declare const PAGE_SIZES: readonly ["A3", "A4", "A5", "Letter", "Legal", "Tabloid"];
+export type PageSize = (typeof PAGE_SIZES)[number];
+export declare const MERMAID_THEMES: readonly ["default", "neutral", "dark", "forest", "base"];
+export type MermaidTheme = (typeof MERMAID_THEMES)[number];
+export declare const BUILTIN_THEMES: readonly ["light", "dark"];
+/** Rendering options, merged from defaults < config file < front matter < command line. */
+export interface DocumentOptions {
+    pageSize: PageSize;
+    /** CSS margin shorthand: 1 to 4 lengths in mm, cm, in or px. */
+    margin: string;
+    landscape: boolean;
+    toc: boolean;
+    /** Deepest heading level listed in the table of contents. */
+    tocDepth: number;
+    /** Default footer with "page / pages". Ignored when `footer` is set. */
+    pageNumbers: boolean;
+    /** Header/footer text; see render/header-footer.ts for placeholders and `|` columns. */
+    header?: string;
+    footer?: string;
+    /** Mermaid theme; when unset, "neutral" for light pages and "dark" for the dark theme. */
+    mermaidTheme?: MermaidTheme;
+    /** "light", "dark", or the absolute path of a stylesheet that replaces the built-in theme. */
+    theme: string;
+    /** Extra stylesheets (absolute paths), applied after the built-in theme. */
+    css: string[];
+    /** BCP 47 language of the document, e.g. "es" or "en". */
+    lang: string;
+    title?: string;
+    subtitle?: string;
+    author?: string;
+    date?: string;
+}
+export declare const DEFAULT_OPTIONS: DocumentOptions;
+export declare class OptionsError extends MdRenderError {
+    constructor(message: string);
+}
+/** Parse a CSS margin shorthand into the four sides, or throw. */
+export declare function parseMargin(margin: string): {
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+};
+/**
+ * Validate options from a config file, front matter or the command line.
+ *
+ * Keys may be camelCase or kebab-case (`page-size`). Unknown keys are ignored so front matter can
+ * hold other metadata. Relative CSS paths resolve against `baseDir`.
+ */
+export declare function normalizeOptions(raw: Record<string, unknown>, source: string, baseDir: string, 
+/** How to name a key in error messages (e.g. as a command-line flag). */
+label?: (key: string) => string): Partial<DocumentOptions>;
+/** Merge option layers, later ones winning. CSS lists accumulate instead of replacing. */
+export declare function mergeOptions(...layers: Partial<DocumentOptions>[]): DocumentOptions;