@ox-content/vite-plugin 3.0.0-alpha.13 → 3.0.0-alpha.15

package/dist/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_vitepress = require("./vitepress.cjs");
+const require_theme_tokens = require("./theme-tokens.cjs");
 const require_jsx_html = require("./jsx-html.cjs");
 const require_markdown_tables = require("./markdown-tables.cjs");
 let path = require("path");
@@ -686,8 +687,14 @@ let missingWarned = false;
 /**
 * Replaces rust `ox-math` placeholders with static KaTeX HTML.
 * Leaves the escaped TeX fallback when `katex` is not installed.
+*
+* `onError` decides what a run KaTeX cannot parse becomes. Prose that
+* quotes math syntax is picked up as math by the `$…$` heuristics, and the
+* default — putting the source back the way it was written — keeps that
+* page readable instead of stamping red error text into the middle of a
+* sentence. Failures are collected either way, so the caller can warn.
 */
-async function renderKatexMath(html) {
+async function renderKatexMath(html, onError = "literal", failures) {
 	if (!html.includes("data-ox-tex")) return html;
 	const katex = loadKatex();
 	if (!katex) {
@@ -695,14 +702,39 @@ async function renderKatexMath(html) {
 		return html;
 	}
 	return html.replace(MATH_TAG, (_match, tag, kind, encoded) => {
-		return `<${tag} class="ox-math ox-math-${kind}">${katex.renderToString(decodeHtmlAttr$3(encoded), {
-			displayMode: kind === "block",
-			throwOnError: false,
+		const block = kind === "block";
+		const tex = decodeHtmlAttr$3(encoded);
+		const options = {
+			displayMode: block,
 			trust: false,
 			output: "htmlAndMathml"
-		})}</${tag}>`;
+		};
+		let rendered;
+		try {
+			rendered = katex.renderToString(tex, {
+				...options,
+				throwOnError: true
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			failures?.push({
+				tex,
+				block,
+				message
+			});
+			if (onError === "error") throw new Error(`${message} (in ${block ? "$$" : "$"}${tex}${block ? "$$" : "$"})`);
+			if (onError === "literal") return escapeHtmlText(block ? `$$${tex}$$` : `$${tex}$`);
+			rendered = katex.renderToString(tex, {
+				...options,
+				throwOnError: false
+			});
+		}
+		return `<${tag} class="ox-math ox-math-${kind}">${rendered}</${tag}>`;
 	});
 }
+function escapeHtmlText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
 /** Directory that contains `katex.min.css` and `fonts/`, or `null`. */
 function resolveKatexDist() {
 	for (const resolver of createKatexResolvers()) try {
@@ -727,8 +759,34 @@ function createKatexResolvers() {
 	resolvers.push((0, node_module.createRequire)(require("url").pathToFileURL(__filename).href));
 	return resolvers;
 }
+const NAMED_ENTITIES$1 = {
+	amp: "&",
+	quot: "\"",
+	apos: "'",
+	lt: "<",
+	gt: ">",
+	nbsp: "\xA0"
+};
+/**
+* Decodes the attribute back to the TeX the author wrote.
+*
+* The placeholder is escaped by Rust and re-serialized by the rehype passes
+* that run before this one, and those two do not agree on a spelling — an
+* apostrophe leaves Rust untouched and comes back from rehype as `&#x27;`.
+* A general decoder covers whichever spelling arrives; chained `replaceAll`
+* calls over a fixed list did not, and the leftover `&#x27;` reached KaTeX
+* as five literal characters.
+*
+* One left-to-right pass, so `&amp;lt;` decodes to `&lt;` rather than `<`.
+*/
 function decodeHtmlAttr$3(value) {
-	return value.replaceAll("&quot;", "\"").replaceAll("&#39;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+	return value.replace(/&(#[0-9]+|#[xX][0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (match, body) => {
+		if (body.startsWith("#")) {
+			const code = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+			return Number.isFinite(code) && code >= 0 && code <= 1114111 ? String.fromCodePoint(code) : match;
+		}
+		return NAMED_ENTITIES$1[body.toLowerCase()] ?? match;
+	});
 }
 function warnMissingKatexOnce() {
 	if (missingWarned) return;
@@ -1070,12 +1128,27 @@ function citationKeysFromMarkdown(markdown, options, diagnostics) {
 	for (const match of visibleMarkdown.matchAll(BRACKET_RE)) {
 		const body = (match[1] ?? "").trim();
 		if (!body.startsWith("@") && !body.startsWith("-@")) continue;
+		if (isLinkLabel(visibleMarkdown, match)) continue;
 		const parsed = parseCitationGroup(body, options, diagnostics);
 		if (!parsed) continue;
 		keys.push(...parsed.map((citation) => citation.key));
 	}
 	return keys;
 }
+/**
+* A bracketed span that a destination or reference immediately follows is a
+* Markdown link label, not a citation group.
+*
+* The HTML pass never sees these — by then the label is inside an `<a>` and has
+* no brackets left — but the search-index pass reads the Markdown source, where
+* a linked scoped package name is indistinguishable from a citation by its
+* opening `@` alone. `[@ox-content/vite-plugin](./packages/vite-plugin.md)`
+* reported a malformed citation and failed the whole index.
+*/
+function isLinkLabel(markdown, match) {
+	const end = (match.index ?? 0) + match[0].length;
+	return markdown[end] === "(" || markdown[end] === "[";
+}
 function stripMarkdownCitationProtectedText(markdown) {
 	return markdown.replace(/^([ \t]*)(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1\2[ \t]*$/gm, "").replace(/^(?: {4}|\t).+$/gm, "").replace(/<!--[\s\S]*?-->/g, "").replace(/<(pre|code|script|style|textarea|a)\b[\s\S]*?<\/\1>/gi, "").replace(/`+[^`\n]*`+/g, "");
 }
@@ -6918,7 +6991,7 @@ async function transformMarkdown(source, filePath, options, ssgOptions) {
 		markdown: source,
 		replacements: /* @__PURE__ */ new Map()
 	};
-	const result = napi.transform(graphviz.markdown, {
+	const napiOptions = {
 		gfm: options.gfm,
 		mdx: resolveMdxForFilePath(filePath, options.mdx),
 		footnotes: options.footnotes,
@@ -7003,10 +7076,15 @@ async function transformMarkdown(source, filePath, options, ssgOptions) {
 			repoUrl: options.editThisPage.repoUrl,
 			branch: options.editThisPage.branch,
 			rootDir: options.editThisPage.rootDir,
+			srcDir: ssgOptions?.srcDir,
+			provider: options.editThisPage.provider,
+			urlPattern: options.editThisPage.urlPattern,
 			label: options.editThisPage.label
 		} : void 0,
 		math: isMathEnabled(options.math)
-	});
+	};
+	const transformers = options.transformers ?? [];
+	const result = transformers.length ? await runTransformers(napi, graphviz.markdown, napiOptions, filePath, options, transformers) : napi.transform(graphviz.markdown, napiOptions);
 	if (result.errors.length > 0) console.warn("[ox-content] Transform warnings:", result.errors);
 	let html = normalizeSelfClosingEmbeds(restoreGraphvizPlaceholders(result.html, graphviz.replacements));
 	const frontmatter = parseFrontmatterJson(result.frontmatter);
@@ -7030,7 +7108,11 @@ async function transformMarkdown(source, filePath, options, ssgOptions) {
 	const citationResult = await transformCitations(html, options.citations);
 	html = citationResult.html;
 	if (options.sanitize?.enabled) html = napi.sanitizeHtml(html, toJsSanitizeOptions(options.sanitize));
-	if (isMathEnabled(options.math)) html = await renderKatexMath(html);
+	if (isMathEnabled(options.math)) {
+		const failures = [];
+		html = await renderKatexMath(html, options.math?.onError ?? "literal", failures);
+		warnMathFailures(failures, filePath);
+	}
 	html = await transformBudouxHtml(html, options.budoux);
 	const imports = result.imports ?? [];
 	const exports = result.exports ?? [];
@@ -7086,6 +7168,52 @@ function toJsSanitizeOptions(options) {
 		allowedUrlSchemes: options.allowedUrlSchemes
 	};
 }
+/**
+* Runs the configured `transformers` over the parsed tree.
+*
+* Markdown never passes through Vite's `transform` hook — the native layer
+* reads it directly — so this is the only place user config can reach the
+* AST. The tree is handed over after frontmatter parsing and Markdown
+* feature expansion, and handed back for rendering, HTML postprocessing,
+* and sanitization, so a transformer costs a document nothing else.
+*
+* A transformer that throws, or returns something that is not a node, is
+* reported and skipped: one bad hook should not take the page down with it.
+*/
+async function runTransformers(napi, markdown, napiOptions, filePath, options, transformers) {
+	const parsed = napi.transformMdast(markdown, napiOptions);
+	if (!parsed.astJson) return {
+		html: "",
+		frontmatter: parsed.frontmatter,
+		toc: [],
+		errors: parsed.errors,
+		imports: [],
+		exports: [],
+		components: []
+	};
+	const errors = [...parsed.errors];
+	const context = {
+		filePath,
+		frontmatter: parseFrontmatterJson(parsed.frontmatter),
+		options
+	};
+	let ast = JSON.parse(parsed.astJson);
+	for (const transformer of transformers) try {
+		const next = await transformer.transform(ast, context);
+		if (!next || typeof next !== "object") {
+			errors.push(`transformer "${transformer.name}" returned ${next === void 0 ? "undefined" : String(next)} instead of a node`);
+			continue;
+		}
+		ast = next;
+	} catch (error) {
+		errors.push(`transformer "${transformer.name}" failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const result = napi.transformFromMdast(JSON.stringify(ast), parsed.frontmatter, napiOptions);
+	return {
+		...result,
+		errors: [...errors, ...result.errors]
+	};
+}
 function parseFrontmatterJson(json) {
 	if (!json) return {};
 	try {
@@ -7185,6 +7313,19 @@ if (import.meta.hot) {
 }
 `;
 }
+/**
+* Reports every `$…$` run KaTeX refused.
+*
+* Under the default policy the page keeps its prose, which is the readable
+* outcome but also a silent one — a genuine mistake in a formula would
+* otherwise leave no trace at all.
+*/
+function warnMathFailures(failures, filePath) {
+	for (const failure of failures) {
+		const delimiter = failure.block ? "$$" : "$";
+		console.warn(`[ox-content] ${filePath}: math left as written — ${failure.message} (in ${delimiter}${failure.tex}${delimiter})`);
+	}
+}
 function isMathEnabled(math) {
 	if (math === true) return true;
 	if (math === false || math == null) return false;
@@ -8528,18 +8669,39 @@ async function renderSingleSatoriPage(entry, templateFn, options, cacheDir, root
 /**
 * Serve and copy KaTeX CSS/fonts only when the optional `katex` package exists.
 */
+/** Font formats KaTeX ships, newest first. */
+const FONT_FORMATS = {
+	woff2: [".woff2"],
+	all: [
+		".woff2",
+		".woff",
+		".ttf"
+	]
+};
 /**
-* Copies `katex.min.css` and `fonts/` into the SSG output.
+* Copies `katex.min.css` and the requested font formats into the SSG output.
 * Returns an empty list when KaTeX is not installed.
+*
+* The `.ttf` and `.woff` sets are three quarters of the font bytes and no
+* browser that can run the rest of the site needs them: `@font-face` lists
+* `woff2` first and stops at the first format it supports. `formats: "all"`
+* brings them back.
 */
-async function copyKatexAssets(outDir) {
+async function copyKatexAssets(outDir, formats = "woff2") {
 	const dist = resolveKatexDist();
 	if (!dist) return [];
 	const dest = (0, node_path.join)(outDir, KATEX_ASSET_DIR);
 	await (0, node_fs_promises.mkdir)((0, node_path.join)(dest, "fonts"), { recursive: true });
 	const cssDest = (0, node_path.join)(dest, "katex.min.css");
 	await (0, node_fs_promises.copyFile)((0, node_path.join)(dist, "katex.min.css"), cssDest);
-	await (0, node_fs_promises.cp)((0, node_path.join)(dist, "fonts"), (0, node_path.join)(dest, "fonts"), { recursive: true });
+	const wanted = FONT_FORMATS[formats] ?? FONT_FORMATS.woff2;
+	await (0, node_fs_promises.cp)((0, node_path.join)(dist, "fonts"), (0, node_path.join)(dest, "fonts"), {
+		recursive: true,
+		filter: (source) => {
+			const extension = (0, node_path.extname)(source);
+			return extension === "" || wanted.includes(extension);
+		}
+	});
 	return [cssDest];
 }
 /** Dev-server middleware that serves `/__ox_katex__/*` from `katex/dist`. */
@@ -16842,7 +17004,7 @@ async function buildSsg(options, root) {
 	});
 	await applyDocumentationVersions(generatedPages, context, errors);
 	await writeGeneratedPages(generatedPages, context, generatedFiles, listedPages, outputPages, errors);
-	if (options.math?.enabled) generatedFiles.push(...await copyKatexAssets(outDir));
+	if (options.math?.enabled && generatedPages.some((page) => page.html.includes("__ox_katex__"))) generatedFiles.push(...await copyKatexAssets(outDir, options.math.fontFormats));
 	generatedFiles.push(...await require_vitepress.writeSelfHostedThemeFonts({
 		fonts: ssgOptions.theme?.fonts ?? {},
 		outDir,
@@ -17007,7 +17169,8 @@ async function transformSsgPage(context, inputPath) {
 	const result = await transformMarkdown(content, inputPath, context.options, {
 		convertMdLinks: true,
 		baseUrl: publicBase(context.base, context.ssgOptions.routePrefix),
-		sourcePath: inputPath
+		sourcePath: inputPath,
+		srcDir: context.srcDir
 	});
 	const frontmatter = require_vitepress.normalizeVitePressFrontmatter(result.frontmatter);
 	const transformedHtml = await transformSsgHtml(result.html, context.options);
@@ -17296,7 +17459,8 @@ async function transformNotFoundMarkdown(context, inputPath, markdown) {
 	const result = await transformMarkdown(markdown, inputPath, context.options, {
 		convertMdLinks: true,
 		baseUrl: context.base,
-		sourcePath: path.join(context.srcDir, "index.md")
+		sourcePath: path.join(context.srcDir, "index.md"),
+		srcDir: context.srcDir
 	});
 	const frontmatter = require_vitepress.normalizeVitePressFrontmatter(result.frontmatter);
 	const transformedHtml = await transformSsgHtml(result.html, context.options);
@@ -17638,7 +17802,8 @@ async function renderPage$1(filePath, options, navGroups, siteName, base, root,
 	const result = await transformMarkdown(await fs_promises.readFile(filePath, "utf-8"), filePath, options, {
 		convertMdLinks: true,
 		baseUrl: base,
-		sourcePath: filePath
+		sourcePath: filePath,
+		srcDir
 	});
 	const frontmatter = require_vitepress.normalizeVitePressFrontmatter(result.frontmatter);
 	let transformedHtml = result.html;
@@ -18594,9 +18759,21 @@ function resolveEmojiShortcodeOptions(options) {
 	};
 }
 function resolveMathOptions(options) {
-	if (!options) return { enabled: false };
-	if (options === true) return { enabled: true };
-	return { enabled: options.enabled ?? true };
+	if (!options) return {
+		enabled: false,
+		onError: "literal",
+		fontFormats: "woff2"
+	};
+	if (options === true) return {
+		enabled: true,
+		onError: "literal",
+		fontFormats: "woff2"
+	};
+	return {
+		enabled: options.enabled ?? true,
+		onError: options.onError ?? "literal",
+		fontFormats: options.fontFormats ?? "woff2"
+	};
 }
 function resolveAttrsOptions(options) {
 	if (!options) return { enabled: false };
@@ -18673,6 +18850,8 @@ function resolveEditThisPageOptions(options) {
 		repoUrl: options.repoUrl,
 		branch: options.branch ?? "main",
 		rootDir: options.rootDir,
+		provider: options.provider,
+		urlPattern: options.urlPattern,
 		label: options.label ?? "Edit this page"
 	};
 }
@@ -20882,6 +21061,7 @@ exports.renderIslandComponentImports = renderIslandComponentImports;
 exports.renderMarkdown = renderMarkdown;
 exports.renderMarkdownStream = renderMarkdownStream;
 exports.renderPage = renderPage;
+exports.renderThemeTokenCss = require_theme_tokens.renderThemeTokenCss;
 exports.renderToString = require_jsx_html.renderToString;
 exports.resolveAbbreviationsOptions = resolveAbbreviationsOptions;
 exports.resolveBadgeOptions = resolveBadgeOptions;
@@ -20939,6 +21119,7 @@ exports.setRenderContext = setRenderContext;
 exports.shouldLintMarkdownFile = shouldLintMarkdownFile;
 exports.stripMarkdownExtension = stripMarkdownExtension;
 exports.stripViteQuery = stripViteQuery;
+exports.tokensToCss = require_theme_tokens.tokensToCss;
 exports.transformAllPlugins = transformAllPlugins;
 exports.transformBudouxHtml = transformBudouxHtml;
 exports.transformGitHub = transformGitHub;