@ox-content/vite-plugin 2.5.0 → 2.7.0

package/dist/index.mjs

@@ -7402,6 +7402,32 @@ export const ${exportName}: NavItem[] = ${JSON.stringify(navItems, null, 2)} as
 */
 const DOCS_MANIFEST_FILE = ".ox-content-docs-manifest.json";
 const DOCS_DATA_FILE = "docs.json";
+const DOC_KIND_ORDER = [
+	"function",
+	"class",
+	"interface",
+	"type",
+	"variable",
+	"module"
+];
+const DOC_KIND_PLURAL = {
+	function: "functions",
+	class: "classes",
+	interface: "interfaces",
+	type: "types",
+	variable: "variables",
+	module: "modules"
+};
+const DEFAULT_DOCS_INCLUDE = [
+	"**/*.ts",
+	"**/*.tsx",
+	"**/*.js",
+	"**/*.jsx",
+	"**/*.mts",
+	"**/*.mjs",
+	"**/*.cts",
+	"**/*.cjs"
+];
 function escapeHtml$3(str) {
 	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -7410,7 +7436,7 @@ function entryAnchor(name) {
 }
 function cleanSummaryText(text, maxLength = 120) {
 	if (!text) return "";
-	const collapsed = text.replace(/\s+/g, " ").trim();
+	const collapsed = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\[([^\]]+)\]/g, "$1").replace(/\s+/g, " ").trim();
 	if (collapsed.length <= maxLength) return collapsed;
 	return `${collapsed.slice(0, maxLength - 1).trimEnd()}…`;
 }
@@ -7548,6 +7574,86 @@ function renderDetailsControlsHtml(targetSelector) {
 <button type="button" class="ox-api-controls__button" data-ox-api-toggle="collapse">Close all</button>
 </div>`;
 }
+function createEmptyEntryStats() {
+	return {
+		entries: 0,
+		byKind: {},
+		params: 0,
+		returns: 0,
+		examples: 0,
+		deprecated: 0
+	};
+}
+function summarizeEntries(entries) {
+	const stats = createEmptyEntryStats();
+	for (const entry of entries) {
+		stats.entries++;
+		stats.byKind[entry.kind] = (stats.byKind[entry.kind] ?? 0) + 1;
+		stats.params += entry.params?.length ?? 0;
+		stats.returns += entry.returns ? 1 : 0;
+		stats.examples += entry.examples?.length ?? 0;
+		stats.deprecated += entry.tags?.deprecated !== void 0 ? 1 : 0;
+	}
+	return stats;
+}
+function buildDocsSummary(docs) {
+	const stats = summarizeEntries(docs.flatMap((doc) => doc.entries));
+	const byKind = {};
+	for (const kind of DOC_KIND_ORDER) {
+		const count = stats.byKind[kind];
+		if (count) byKind[kind] = count;
+	}
+	return {
+		modules: docs.length,
+		entries: stats.entries,
+		byKind,
+		params: stats.params,
+		returns: stats.returns,
+		examples: stats.examples,
+		deprecated: stats.deprecated
+	};
+}
+function renderStatsHtml(stats, moduleCount) {
+	const items = [];
+	if (moduleCount !== void 0) items.push({
+		label: "modules",
+		value: moduleCount
+	});
+	items.push({
+		label: "symbols",
+		value: stats.entries
+	});
+	for (const kind of DOC_KIND_ORDER) {
+		const count = stats.byKind[kind];
+		if (count) items.push({
+			label: DOC_KIND_PLURAL[kind],
+			value: count
+		});
+	}
+	if (stats.params) items.push({
+		label: "parameters",
+		value: stats.params
+	});
+	if (stats.returns) items.push({
+		label: "returns",
+		value: stats.returns
+	});
+	if (stats.examples) items.push({
+		label: "examples",
+		value: stats.examples
+	});
+	if (stats.deprecated) items.push({
+		label: "deprecated",
+		value: stats.deprecated,
+		tone: "warning"
+	});
+	return `<div class="ox-api-stats" aria-label="API reference summary">
+${items.map((item) => `<span class="ox-api-stat${item.tone ? ` ox-api-stat--${item.tone}` : ""}">
+  <strong>${item.value}</strong>
+  <span>${escapeHtml$3(item.label)}</span>
+</span>`).join("\n")}
+</div>`;
+}
 function normalizeDocFilePath(filePath) {
 	const normalized = filePath.replace(/\\/g, "/");
 	return normalized.match(/(?:^|\/)((?:npm|packages|crates|src)\/.+)$/)?.[1] ?? normalized.replace(/^\/+/, "");
@@ -7556,6 +7662,7 @@ function buildDocsData(docs) {
 	return {
 		version: 1,
 		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		summary: buildDocsSummary(docs),
 		modules: docs.map((doc) => ({
 			...doc,
 			file: normalizeDocFilePath(doc.file),
@@ -7566,6 +7673,86 @@ function buildDocsData(docs) {
 		}))
 	};
 }
+function consumeJSDocType(value) {
+	const trimmed = value.trimStart();
+	if (!trimmed.startsWith("{")) return { rest: trimmed };
+	let depth = 0;
+	for (let index = 0; index < trimmed.length; index++) {
+		const char = trimmed[index];
+		if (char === "{") depth++;
+		else if (char === "}") {
+			depth--;
+			if (depth === 0) return {
+				type: trimmed.slice(1, index).trim() || void 0,
+				rest: trimmed.slice(index + 1).trimStart()
+			};
+		}
+	}
+	return { rest: trimmed };
+}
+function cleanTagDescription(value) {
+	return value.trim().replace(/^-\s*/, "").trim();
+}
+function splitTagNameAndDescription(value) {
+	const trimmed = value.trimStart();
+	if (trimmed.startsWith("[")) {
+		const closeIndex = trimmed.indexOf("]");
+		if (closeIndex >= 0) return {
+			name: trimmed.slice(0, closeIndex + 1),
+			description: trimmed.slice(closeIndex + 1).trimStart()
+		};
+	}
+	const match = /^(\S+)(?:\s+([\s\S]*))?$/u.exec(trimmed);
+	return {
+		name: match?.[1] ?? "",
+		description: match?.[2] ?? ""
+	};
+}
+function parseParamTagValue(value) {
+	const { type, rest } = consumeJSDocType(value);
+	const { name: rawName, description } = splitTagNameAndDescription(rest);
+	let name = rawName.trim();
+	if (!name) return null;
+	let optional = false;
+	let defaultValue;
+	const optionalMatch = /^\[(.*)\]$/u.exec(name);
+	if (optionalMatch) {
+		optional = true;
+		const [innerName, innerDefault] = optionalMatch[1].split(/=(.*)/su);
+		name = innerName.trim();
+		defaultValue = innerDefault?.trim() || void 0;
+	}
+	if (!name) return null;
+	return {
+		name,
+		type: type || "unknown",
+		description: cleanTagDescription(description),
+		optional: optional || void 0,
+		default: defaultValue
+	};
+}
+function parseReturnsTagValue(value) {
+	const { type, rest } = consumeJSDocType(value);
+	return {
+		type: type || "unknown",
+		description: cleanTagDescription(rest)
+	};
+}
+function normalizeReturnType(value) {
+	const parsed = parseReturnsTagValue(value);
+	return parsed.type === "unknown" ? value : parsed.type;
+}
+function mergeParam(params, next) {
+	const existing = params.find((param) => param.name === next.name);
+	if (!existing) {
+		params.push(next);
+		return;
+	}
+	if (next.type && (existing.type === "unknown" || next.type !== "unknown")) existing.type = next.type;
+	if (next.description) existing.description = next.description;
+	if (next.optional) existing.optional = true;
+	if (next.default) existing.default = next.default;
+}
 /**
 * Extracts JSDoc documentation from source files in specified directories.
 *
@@ -7577,7 +7764,7 @@ function buildDocsData(docs) {
 *
 * 1. **File Discovery**: Recursively walks directories, applying filters
 * 2. **File Reading**: Loads each matching file's content
-* 3. **JSDoc Extraction**: Parses JSDoc comments using regex patterns
+* 3. **JSDoc Extraction**: Parses JSDoc comments using the native parser
 * 4. **Declaration Matching**: Pairs JSDoc comments with source declarations
 * 5. **Result Collection**: Aggregates extracted documentation by file
 *
@@ -7717,32 +7904,29 @@ function parseNapiDocItem(item) {
 				currentExample = "";
 				inExample = false;
 			}
-			const tagMatch = /@(\w+)\s*(?:\{([^}]*)\})?(.*)/.exec(lineText);
+			const tagMatch = /^@(\S+)\s*([\s\S]*)$/u.exec(lineText);
 			if (tagMatch) {
-				const [, tagName, tagType, tagRest] = tagMatch;
+				const [, tagName, tagValue = ""] = tagMatch;
 				switch (tagName) {
 					case "param":
-						const paramMatch = /(\w+)\s*-?\s*(.*)/.exec(tagRest.trim());
-						if (paramMatch) params.push({
-							name: paramMatch[1],
-							type: tagType || "unknown",
-							description: paramMatch[2]
-						});
+					case "arg":
+					case "argument": {
+						const param = parseParamTagValue(tagValue);
+						if (param) mergeParam(params, param);
 						break;
+					}
 					case "returns":
 					case "return":
-						returns = {
-							type: tagType || "unknown",
-							description: tagRest.trim()
-						};
+						returns = parseReturnsTagValue(tagValue);
 						break;
 					case "example":
 						inExample = true;
+						currentExample = tagValue.trim() ? `${tagValue.trim()}\n` : "";
 						break;
 					case "private":
 						isPrivate = true;
 						break;
-					default: tags[tagName] = tagRest.trim();
+					default: tags[tagName] = tagValue.trim();
 				}
 			}
 		} else if (inExample) currentExample += rawLine + "\n";
@@ -7750,32 +7934,41 @@ function parseNapiDocItem(item) {
 		else description += "\n" + lineText;
 	}
 	if (inExample && currentExample) examples.push(currentExample.trim());
-	if (params.length === 0 && item.params.length > 0) params.push(...item.params.map((param) => ({
-		name: param.name,
-		type: param.typeAnnotation ?? "unknown",
-		description: param.description ?? "",
-		optional: param.optional || void 0,
-		default: param.defaultValue
-	})));
-	else if (item.params.length > 0) {
-		const paramMap = new Map(item.params.map((param) => [param.name, param]));
-		for (const param of params) {
-			const rustParam = paramMap.get(param.name);
-			if (!rustParam) continue;
-			if (param.type === "unknown" && rustParam.typeAnnotation) param.type = rustParam.typeAnnotation;
-			if (!param.description && rustParam.description) param.description = rustParam.description;
-			if (param.optional === void 0 && rustParam.optional) param.optional = true;
-			if (!param.default && rustParam.defaultValue) param.default = rustParam.defaultValue;
-		}
+	for (const param of item.params) {
+		if (params.length > 0 && param.name === "param" && !param.typeAnnotation && !param.description && !param.defaultValue) continue;
+		mergeParam(params, {
+			name: param.name,
+			type: param.typeAnnotation ?? "unknown",
+			description: param.description ?? "",
+			optional: param.optional || void 0,
+			default: param.defaultValue
+		});
 	}
 	if (!returns && item.returnType) returns = {
-		type: item.returnType,
+		type: normalizeReturnType(item.returnType),
 		description: ""
 	};
-	else if (returns && returns.type === "unknown" && item.returnType) returns.type = item.returnType;
+	else if (returns && item.returnType) returns.type = normalizeReturnType(item.returnType);
 	if (!description) description = item.doc ?? "";
 	for (const tag of item.tags) {
-		if (tag.tag === "param" || tag.tag === "returns" || tag.tag === "return" || tag.tag === "example") continue;
+		if (tag.tag === "param" || tag.tag === "arg" || tag.tag === "argument" || tag.tag === "returns" || tag.tag === "return") {
+			if (tag.tag === "param" || tag.tag === "arg" || tag.tag === "argument") {
+				const param = parseParamTagValue(tag.value);
+				if (param) mergeParam(params, param);
+			} else {
+				const parsedReturns = parseReturnsTagValue(tag.value);
+				if (!returns) returns = parsedReturns;
+				else {
+					returns.type = returns.type === "unknown" ? parsedReturns.type : returns.type;
+					returns.description ||= parsedReturns.description;
+				}
+			}
+			continue;
+		}
+		if (tag.tag === "example") {
+			if (tag.value && !examples.includes(tag.value)) examples.push(tag.value);
+			continue;
+		}
 		if (tag.tag === "private") {
 			isPrivate = true;
 			continue;
@@ -7862,6 +8055,7 @@ function generateFileMarkdown(doc, options, currentFileName, symbolMap) {
 	}
 	md += `> ${doc.entries.length} documented symbol${doc.entries.length === 1 ? "" : "s"}. `;
 	md += "Read the signatures first, then expand each item for parameters, return types, and examples.\n\n";
+	md += renderStatsHtml(summarizeEntries(doc.entries)) + "\n\n";
 	md += "## Reference\n\n";
 	if (doc.entries.length > 1) md += renderDetailsControlsHtml(".ox-api-entry") + "\n\n";
 	for (const entry of doc.entries) md += generateEntryMarkdown(entry, options, currentFileName, symbolMap);
@@ -7881,6 +8075,42 @@ function formatKindLabel(kind) {
 		default: return kind;
 	}
 }
+function formatCountLabel(count, singular, plural = `${singular}s`) {
+	return `${count} ${count === 1 ? singular : plural}`;
+}
+function getEntryBadges(entry) {
+	const badges = [];
+	if (entry.tags?.deprecated !== void 0) badges.push({
+		label: "deprecated",
+		tone: "warning"
+	});
+	if (entry.params?.length) badges.push({ label: formatCountLabel(entry.params.length, "param") });
+	if (entry.returns) badges.push({ label: `returns ${entry.returns.type}` });
+	if (entry.examples?.length) badges.push({ label: formatCountLabel(entry.examples.length, "example") });
+	if (entry.tags?.since) badges.push({ label: `since ${entry.tags.since}` });
+	if (entry.private) badges.push({
+		label: "private",
+		tone: "warning"
+	});
+	return badges;
+}
+function renderEntryBadgesHtml(entry, className) {
+	const badges = getEntryBadges(entry);
+	if (badges.length === 0) return "";
+	return `<span class="${className}">${badges.map((badge) => `<span class="ox-api-badge${badge.tone ? ` ox-api-badge--${badge.tone}` : ""}">${escapeHtml$3(badge.label)}</span>`).join("")}</span>`;
+}
+function parseExampleBlock(example) {
+	const trimmed = example.trim();
+	const fenceMatch = /^```([\w-]+)?[^\n]*\n([\s\S]*?)\n?```$/u.exec(trimmed);
+	if (!fenceMatch) return {
+		code: trimmed,
+		language: "ts"
+	};
+	return {
+		code: fenceMatch[2],
+		language: fenceMatch[1] || "ts"
+	};
+}
 function renderOverviewLine(entry, href) {
 	const signature = normalizeSignature(entry.signature);
 	const summary = cleanSummaryText(entry.description, 88);
@@ -7892,8 +8122,9 @@ function renderOverviewLine(entry, href) {
 function renderOverviewHtmlItem(entry, href) {
 	const signature = normalizeSignature(entry.signature);
 	const summary = cleanSummaryText(entry.description, 88);
+	const meta = renderEntryBadgesHtml(entry, "ox-api-module__meta");
 	const heading = signature ? `<a href="${escapeHtml$3(href)}" class="ox-api-module__link">${renderHighlightedInlineCodeHtml(signature, "ox-api-module__signature ox-api-module__signature--highlighted")}</a>` : `<a href="${escapeHtml$3(href)}" class="ox-api-module__link"><code class="ox-api-module__name">${escapeHtml$3(entry.name)}</code></a>`;
-	return `<li><span class="ox-api-module__kind">${escapeHtml$3(formatKindLabel(entry.kind))}</span><div class="ox-api-module__item">${heading}${summary ? `<span class="ox-api-module__summary">${renderInlineHtml(summary)}</span>` : ""}</div></li>`;
+	return `<li><span class="ox-api-module__kind">${escapeHtml$3(formatKindLabel(entry.kind))}</span><div class="ox-api-module__item">${heading}${summary ? `<span class="ox-api-module__summary">${renderInlineHtml(summary)}</span>` : ""}${meta}</div></li>`;
 }
 function renderParamsListHtml(params) {
 	return `<div class="ox-api-entry__section ox-api-entry__section--params">
@@ -7925,6 +8156,10 @@ function generateEntryMarkdown(entry, options, currentFileName, symbolMap) {
 	const sourceHref = options?.githubUrl ? generateSourceHref(entry.file, options.githubUrl, entry.line, entry.endLine) : void 0;
 	let body = "";
 	if (processedDescription) body += renderMarkdownBlocksHtml(processedDescription) + "\n";
+	if (entry.signature) body += `<div class="ox-api-entry__section ox-api-entry__section--signature">
+<h4>Signature</h4>
+${renderCodeBlockHtml(entry.signature, "typescript")}
+</div>\n`;
 	if (sourceHref) body += `<p class="ox-api-entry__source"><a href="${escapeHtml$3(sourceHref)}">View source</a></p>\n`;
 	if (entry.params && entry.params.length > 0) body += renderParamsListHtml(entry.params) + "\n";
 	if (entry.returns) body += `<div class="ox-api-entry__section ox-api-entry__section--returns">
@@ -7935,13 +8170,19 @@ function generateEntryMarkdown(entry, options, currentFileName, symbolMap) {
 </div>
 </div>\n`;
 	if (entry.examples && entry.examples.length > 0) {
-		const examplesHtml = entry.examples.map((example) => example.replace(/^```\w*\n?/, "").replace(/\n?```$/, "")).map((example) => renderCodeBlockHtml(example, "ts")).join("\n");
+		const examplesHtml = entry.examples.map((example, index) => {
+			const parsed = parseExampleBlock(example);
+			return `<div class="ox-api-entry__example">
+<div class="ox-api-entry__example-heading">Example ${index + 1}</div>
+${renderCodeBlockHtml(parsed.code, parsed.language)}
+</div>`;
+		}).join("\n");
 		body += `<div class="ox-api-entry__section ox-api-entry__section--examples">\n<h4>Examples</h4>\n${examplesHtml}\n</div>\n`;
 	}
 	if (entry.tags && Object.keys(entry.tags).length > 0) body += renderTagListHtml(entry.tags) + "\n";
 	const summaryDescription = cleanSummaryText(processedDescription, summarySignature ? 80 : 120);
 	const summaryHeading = summarySignature ? renderHighlightedInlineCodeHtml(summarySignature, "ox-api-entry__signature ox-api-entry__signature--highlighted") : `<code class="ox-api-entry__name">${escapeHtml$3(entry.name)}</code>`;
-	const summaryParts = [`<span class="ox-api-entry__kind">${escapeHtml$3(formatKindLabel(entry.kind))}</span>`, `<span class="ox-api-entry__summary-main">${summaryHeading}${summaryDescription ? `<span class="ox-api-entry__description">${renderInlineHtml(summaryDescription)}</span>` : ""}</span>`];
+	const summaryParts = [`<span class="ox-api-entry__kind">${escapeHtml$3(formatKindLabel(entry.kind))}</span>`, `<span class="ox-api-entry__summary-main">${summaryHeading}${summaryDescription ? `<span class="ox-api-entry__description">${renderInlineHtml(summaryDescription)}</span>` : ""}${renderEntryBadgesHtml(entry, "ox-api-entry__meta")}</span>`];
 	return `<details id="${entryAnchor(entry.name)}" class="ox-api-entry">
   <summary>${summaryParts.join("")}</summary>
   <div class="ox-api-entry__body">
@@ -7955,6 +8196,7 @@ function generateIndex(docs, docToFile) {
 	let md = "# API Documentation\n\n";
 	md += "Generated by [Ox Content](https://github.com/ubugeeei/ox-content)\n\n";
 	md += "> Use search scopes like `@api transform` to limit results to the generated API reference.\n\n";
+	md += renderStatsHtml(summarizeEntries(docs.flatMap((doc) => doc.entries)), docs.length) + "\n\n";
 	md += "## Modules\n\n";
 	if (docs.length > 1) md += renderDetailsControlsHtml(".ox-api-module") + "\n\n";
 	for (const doc of docs) {
@@ -7984,6 +8226,7 @@ function generateCategoryMarkdown(kind, entries, options, symbolMap) {
 	const categoryFileName = `${kind}s`;
 	let md = `# ${kind.charAt(0).toUpperCase() + kind.slice(1)}s\n\n`;
 	md += `> ${entries.length} documented ${kind}${entries.length === 1 ? "" : "s"} collected across modules.\n\n`;
+	md += renderStatsHtml(summarizeEntries(entries)) + "\n\n";
 	md += "## Overview\n\n";
 	for (const entry of entries) md += renderOverviewLine(entry, `#${entryAnchor(entry.name)}`);
 	md += "\n## Reference\n\n";
@@ -7994,6 +8237,7 @@ function generateCategoryMarkdown(kind, entries, options, symbolMap) {
 function generateCategoryIndex(byKind) {
 	let md = "# API Documentation\n\n";
 	md += "Generated by [Ox Content](https://github.com/ubugeeei/ox-content)\n\n";
+	md += renderStatsHtml(summarizeEntries([...byKind.values()].flatMap((entries) => entries))) + "\n\n";
 	for (const [kind, entries] of [...byKind.entries()].sort(([a], [b]) => compareStrings(a, b))) {
 		const kindTitle = kind.charAt(0).toUpperCase() + kind.slice(1) + "s";
 		md += `## [${kindTitle}](./${kind}s.md)\n\n`;
@@ -8105,7 +8349,7 @@ function resolveDocsOptions(options) {
 		enabled: opts.enabled ?? true,
 		src: opts.src ?? ["./src"],
 		out: opts.out ?? "docs/api",
-		include: opts.include ?? ["**/*.ts", "**/*.tsx"],
+		include: opts.include ?? DEFAULT_DOCS_INCLUDE,
 		exclude: opts.exclude ?? [
 			"**/*.test.*",
 			"**/*.spec.*",
@@ -9153,6 +9397,7 @@ function resolveTheme(config) {
 		header: merged.header ?? defaultTheme.header,
 		footer: merged.footer ?? defaultTheme.footer,
 		socialLinks: merged.socialLinks ?? defaultTheme.socialLinks,
+		sidebar: merged.sidebar ?? [],
 		embed: merged.embed ?? {},
 		css: merged.css ?? "",
 		js: merged.js ?? ""
@@ -9162,6 +9407,7 @@ function resolveTheme(config) {
 * Converts resolved theme to the format expected by Rust NAPI.
 */
 function themeToNapi(theme) {
+	const socialLinks = socialLinksToNapi(theme.socialLinks);
 	return {
 		colors: theme.colors.primary ? {
 			primary: theme.colors.primary,
@@ -9207,16 +9453,30 @@ function themeToNapi(theme) {
 			message: theme.footer.message,
 			copyright: theme.footer.copyright
 		} : void 0,
-		socialLinks: theme.socialLinks.github || theme.socialLinks.twitter || theme.socialLinks.discord ? {
-			github: theme.socialLinks.github,
-			twitter: theme.socialLinks.twitter,
-			discord: theme.socialLinks.discord
-		} : void 0,
+		socialLinks,
 		embed: Object.keys(theme.embed).length > 0 ? theme.embed : void 0,
 		css: theme.css || void 0,
 		js: theme.js || void 0
 	};
 }
+function socialLinksToNapi(links) {
+	if (Array.isArray(links)) {
+		const items = links.map((item) => {
+			return {
+				icon: typeof item.icon === "string" ? item.icon : void 0,
+				iconSvg: typeof item.icon === "object" ? item.icon.svg : void 0,
+				link: item.link,
+				ariaLabel: item.ariaLabel
+			};
+		});
+		return items.length > 0 ? { links: items } : void 0;
+	}
+	return links.github || links.twitter || links.discord ? {
+		github: links.github,
+		twitter: links.twitter,
+		discord: links.discord
+	} : void 0;
+}
 //#endregion
 //#region src/ssg.ts
 /**
@@ -9725,6 +9985,40 @@ const DEFAULT_HTML_TEMPLATE = `<!DOCTYPE html>
       border-color: color-mix(in srgb, var(--color-primary) 38%, var(--color-border));
       background: color-mix(in srgb, var(--color-bg-alt) 68%, var(--color-primary) 6%);
     }
+    .content .ox-api-stats {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(7rem, 1fr));
+      gap: 0.55rem;
+      margin: 1rem 0 1.35rem;
+    }
+    .content .ox-api-stat {
+      min-width: 0;
+      padding: 0.7rem 0.75rem;
+      border: 1px solid color-mix(in srgb, var(--color-border) 76%, transparent);
+      border-radius: 4px;
+      background: color-mix(in srgb, var(--color-bg-alt) 72%, transparent);
+    }
+    .content .ox-api-stat strong {
+      display: block;
+      font-family: var(--font-mono);
+      font-size: 1rem;
+      line-height: 1.2;
+      color: var(--color-text);
+    }
+    .content .ox-api-stat span {
+      display: block;
+      margin-top: 0.25rem;
+      font-family: var(--font-mono);
+      font-size: 0.7rem;
+      font-weight: 600;
+      letter-spacing: 0.04em;
+      text-transform: uppercase;
+      color: var(--color-text-muted);
+    }
+    .content .ox-api-stat--warning {
+      border-color: color-mix(in srgb, #f59e0b 42%, var(--color-border));
+      background: color-mix(in srgb, var(--color-bg-alt) 78%, #f59e0b 8%);
+    }
     .content .ox-api-entry,
     .content .ox-api-module {
       margin: 0;
@@ -9834,6 +10128,31 @@ const DEFAULT_HTML_TEMPLATE = `<!DOCTYPE html>
       flex-direction: column;
       gap: 0.55rem;
     }
+    .content .ox-api-entry__meta,
+    .content .ox-api-module__meta {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.35rem;
+    }
+    .content .ox-api-badge {
+      display: inline-flex;
+      align-items: center;
+      max-width: 100%;
+      padding: 0.18rem 0.42rem;
+      border: 1px solid color-mix(in srgb, var(--color-border) 78%, transparent);
+      border-radius: 4px;
+      background: color-mix(in srgb, var(--color-bg-alt) 78%, var(--color-primary) 6%);
+      color: color-mix(in srgb, var(--color-text) 74%, var(--color-text-muted));
+      font-family: var(--font-mono);
+      font-size: 0.68rem;
+      font-weight: 600;
+      line-height: 1.35;
+    }
+    .content .ox-api-badge--warning {
+      border-color: color-mix(in srgb, #f59e0b 46%, var(--color-border));
+      background: color-mix(in srgb, var(--color-bg-alt) 78%, #f59e0b 9%);
+      color: color-mix(in srgb, var(--color-text) 86%, #f59e0b);
+    }
     .content .ox-api-entry__name,
     .content .ox-api-entry__signature,
     .content .ox-api-module__name,
@@ -9982,6 +10301,23 @@ const DEFAULT_HTML_TEMPLATE = `<!DOCTYPE html>
       font-size: 0.88rem;
       line-height: 1.55;
     }
+    .content .ox-api-entry__section--signature pre {
+      margin: 0;
+      border: 1px solid var(--color-code-frame-border);
+      border-radius: 4px;
+    }
+    .content .ox-api-entry__example + .ox-api-entry__example {
+      margin-top: 0.85rem;
+    }
+    .content .ox-api-entry__example-heading {
+      margin-bottom: 0.45rem;
+      font-family: var(--font-mono);
+      font-size: 0.72rem;
+      font-weight: 700;
+      letter-spacing: 0.04em;
+      text-transform: uppercase;
+      color: var(--color-text-muted);
+    }
     .content .ox-api-entry__section--examples pre {
       margin: 0;
       border: 1px solid var(--color-code-frame-border);
@@ -10496,7 +10832,8 @@ function resolveSsgOptions(ssg) {
 		extension: ".html",
 		clean: false,
 		bare: false,
-		generateOgImage: false
+		generateOgImage: false,
+		lastUpdated: false
 	};
 	if (ssg === true || ssg === void 0) return {
 		enabled: true,
@@ -10504,6 +10841,7 @@ function resolveSsgOptions(ssg) {
 		clean: false,
 		bare: false,
 		generateOgImage: false,
+		lastUpdated: false,
 		theme: resolveTheme(void 0)
 	};
 	return {
@@ -10514,6 +10852,7 @@ function resolveSsgOptions(ssg) {
 		siteName: ssg.siteName,
 		ogImage: ssg.ogImage,
 		generateOgImage: ssg.generateOgImage ?? false,
+		lastUpdated: ssg.lastUpdated ?? false,
 		siteUrl: ssg.siteUrl,
 		theme: resolveTheme(ssg.theme)
 	};
@@ -10567,13 +10906,17 @@ async function generateHtmlPage(pageData, navGroups, siteName, base, ogImage, th
 		text: entry.text,
 		slug: entry.slug
 	}));
+	const toRustNavItem = (item) => ({
+		title: item.title,
+		path: item.path,
+		href: item.href,
+		children: item.children?.map(toRustNavItem),
+		collapsed: item.collapsed
+	});
 	const navGroupsForRust = navGroups.map((group) => ({
 		title: group.title,
-		items: group.items.map((item) => ({
-			title: item.title,
-			path: item.path,
-			href: item.href
-		}))
+		collapsed: group.collapsed,
+		items: group.items.map(toRustNavItem)
 	}));
 	const themeForRust = theme ? themeToNapi(theme) : void 0;
 	const entryPageForRust = pageData.entryPage ? {
@@ -10612,6 +10955,7 @@ async function generateHtmlPage(pageData, navGroups, siteName, base, ogImage, th
 		description: pageData.description,
 		content: pageData.content,
 		toc: tocForRust,
+		lastUpdated: pageData.lastUpdated,
 		path: pageData.path,
 		entryPage: entryPageForRust
 	}, navGroupsForRust, {
@@ -10899,6 +11243,63 @@ function buildNavItems(markdownFiles, srcDir, base, extension) {
 	});
 	return result;
 }
+function isSafeSidebarLink(link) {
+	const trimmed = link.trim();
+	if (trimmed.startsWith("//")) return false;
+	return !/^[a-z][a-z0-9+.-]*:/i.test(trimmed) || /^(https?:|mailto:)/i.test(trimmed);
+}
+function sidebarPath(link) {
+	if (!link || !isSafeSidebarLink(link)) return "";
+	if (/^(https?:|mailto:|#)/i.test(link.trim())) return "";
+	const bare = link.trim().split("#", 1)[0].split("?", 1)[0].replace(/^\/+/, "").replace(/\/$/, "").replace(/\.(md|markdown)$/i, "");
+	if (!bare || bare === "index") return "/";
+	return bare.replace(/\/index$/, "");
+}
+function sidebarHref(link, base, extension) {
+	if (!link) return "#";
+	const trimmed = link.trim();
+	if (!isSafeSidebarLink(trimmed)) return "#";
+	if (/^(https?:|mailto:|#)/i.test(trimmed)) return trimmed;
+	const hash = trimmed.includes("#") ? `#${trimmed.split("#").slice(1).join("#")}` : "";
+	const withoutExt = trimmed.split("#", 1)[0].replace(/^\/+/, "").replace(/\/$/, "").replace(/\.(md|markdown)$/i, "");
+	return `${base}${!withoutExt || withoutExt === "index" ? "index" : `${withoutExt.replace(/\/index$/, "")}/index`}${extension}${hash}`;
+}
+/**
+* Builds navigation items from an explicit theme sidebar tree.
+*/
+function buildThemeNavItems(sidebar, base, extension) {
+	const toNavItem = (item) => {
+		const navItem = {
+			title: item.text ?? item.link ?? "Untitled",
+			path: sidebarPath(item.link),
+			href: sidebarHref(item.link, base, extension)
+		};
+		if (item.items?.length) navItem.children = item.items.map(toNavItem);
+		if (item.collapsed !== void 0) navItem.collapsed = item.collapsed;
+		return navItem;
+	};
+	const groups = [];
+	let looseItems = [];
+	const flushLooseItems = () => {
+		if (looseItems.length > 0) {
+			groups.push({
+				title: "Guide",
+				items: looseItems
+			});
+			looseItems = [];
+		}
+	};
+	for (const item of sidebar) if (item.items?.length && !item.link) {
+		flushLooseItems();
+		groups.push({
+			title: item.text ?? "Guide",
+			items: item.items.map(toNavItem),
+			collapsed: item.collapsed
+		});
+	} else looseItems.push(toNavItem(item));
+	flushLooseItems();
+	return groups;
+}
 /**
 * Builds all markdown files to static HTML.
 */
@@ -10921,7 +11322,7 @@ async function buildSsg(options, root) {
 		});
 	} catch {}
 	const markdownFiles = await collectMarkdownFiles$1(srcDir);
-	const navItems = buildNavItems(markdownFiles, srcDir, base, ssgOptions.extension);
+	const navItems = ssgOptions.theme?.sidebar.length ? buildThemeNavItems(ssgOptions.theme.sidebar, base, ssgOptions.extension) : buildNavItems(markdownFiles, srcDir, base, ssgOptions.extension);
 	let siteName = ssgOptions.siteName ?? "Documentation";
 	if (!ssgOptions.siteName) try {
 		const pkgPath = path$2.join(root, "package.json");
@@ -10933,6 +11334,7 @@ async function buildSsg(options, root) {
 	const ogImageUrlMap = /* @__PURE__ */ new Map();
 	const shouldGenerateOgImages = (options.ogImage || ssgOptions.generateOgImage) && !ssgOptions.bare;
 	const pageResults = [];
+	const napi = ssgOptions.lastUpdated ? await importNapiModule() : void 0;
 	for (const inputPath of markdownFiles) try {
 		const result = await transformMarkdown(await fs$1.readFile(inputPath, "utf-8"), inputPath, options, {
 			convertMdLinks: true,
@@ -10960,6 +11362,7 @@ async function buildSsg(options, root) {
 			transformedHtml,
 			title,
 			description,
+			lastUpdated: napi?.getGitLastUpdated(inputPath, root) ?? void 0,
 			frontmatter: result.frontmatter,
 			toc: result.toc
 		});
@@ -11005,7 +11408,7 @@ async function buildSsg(options, root) {
 		ogImageUrlMap.clear();
 	}
 	for (const pageResult of pageResults) try {
-		const { inputPath, transformedHtml, title, description, frontmatter, toc } = pageResult;
+		const { inputPath, transformedHtml, title, description, lastUpdated, frontmatter, toc } = pageResult;
 		let pageOgImage = ssgOptions.ogImage;
 		if (shouldGenerateOgImages && ogImageUrlMap.has(inputPath)) pageOgImage = ogImageUrlMap.get(inputPath);
 		let entryPage;
@@ -11020,6 +11423,7 @@ async function buildSsg(options, root) {
 			description,
 			content: transformedHtml,
 			toc,
+			lastUpdated,
 			frontmatter,
 			path: getUrlPath$1(inputPath, srcDir),
 			href: getHref(inputPath, srcDir, base, ssgOptions.extension),
@@ -12928,6 +13332,7 @@ function renderPage(page, options) {
 			description: page.description,
 			html: page.html,
 			toc: page.toc,
+			lastUpdated: page.lastUpdated,
 			path: page.path,
 			url: page.url,
 			frontmatter: page.frontmatter,
@@ -12942,6 +13347,7 @@ function renderPage(page, options) {
 				description: p.description,
 				html: p.html,
 				toc: p.toc,
+				lastUpdated: p.lastUpdated,
 				path: p.path,
 				url: p.url,
 				frontmatter: p.frontmatter,