@classic-homes/theme-docs 0.1.0 → 0.2.0

package/dist/lib/content/load.js

@@ -0,0 +1,366 @@
+/**
+ * Read a directory of markdown into the docs content model, the way Docusaurus does:
+ * routes from file paths, autogenerated sidebars ordered by `sidebar_position` and
+ * `_category_.json`, generated-index category pages, tags, and relative `.md` links
+ * rewritten to routes. Node-only (reads the file system).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { createSlugger } from '../parser/slug.js';
+const isDoc = (name) => /\.mdx?$/.test(name);
+const isIndexDoc = (name) => /^index\.mdx?$/.test(name);
+/** Docusaurus ignores `_`-prefixed files and folders (partials); category files aren't docs. */
+const isIgnored = (name) => name.startsWith('_') || name.startsWith('.');
+/** Directory entries in the order Docusaurus reads them: by name. */
+function entries(dir) {
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => !isIgnored(e.name))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/** Parse YAML front matter; returns `{ data, body }`. Throws on invalid YAML. */
+export function parseFrontmatter(raw, file) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
+    if (!match)
+        return { data: {}, body: raw };
+    try {
+        return {
+            data: yaml.load(match[1]) || {},
+            body: raw.slice(match[0].length),
+        };
+    }
+    catch (err) {
+        throw new Error(`${file}: invalid front matter: ${err.message}`);
+    }
+}
+/** `it/network/vpn/index.md` → `/docs/it/network/vpn`. */
+export function routeOf(file, routeBase = '/docs') {
+    let stem = file.replace(/\.mdx?$/, '');
+    if (path.posix.basename(stem) === 'index')
+        stem = path.posix.dirname(stem);
+    return stem && stem !== '.' ? `${routeBase}/${stem}` : routeBase;
+}
+/** `_category_.json` or `_category_.yml` in a folder, or `{}` when it has neither. */
+function readCategory(dirAbs) {
+    for (const name of ['_category_.json', '_category_.yml', '_category_.yaml']) {
+        const file = path.join(dirAbs, name);
+        if (!fs.existsSync(file))
+            continue;
+        try {
+            return yaml.load(fs.readFileSync(file, 'utf8')) ?? {};
+        }
+        catch (err) {
+            throw new Error(`${file} is not valid ${name.endsWith('.json') ? 'JSON' : 'YAML'}: ${err.message}`);
+        }
+    }
+    return {};
+}
+/**
+ * Read a docs directory into pages, sidebars, generated-index pages and tags.
+ *
+ * Routes come from file paths; `slug` and `id` front matter are rejected rather than
+ * silently ignored. Relative links to `.md`/`.mdx` files become routes (anchors kept),
+ * Docusaurus' `pathname://` prefix is unwrapped, and links under `routeBase` are checked.
+ *
+ * @example
+ * ```ts
+ * const docs = loadDocs({ dir: 'docs', sidebarRoots: ['guides', 'reference'] });
+ * const { pages } = await renderDocs(docs, { parse: { headingIdStyle: 'github' } });
+ * ```
+ */
+export function loadDocs(options) {
+    const { dir, routeBase: contentRouteBase = '/docs', baseUrl: rawBaseUrl = '', sidebarRoots = [''], tags: vocabulary, onBrokenLinks = 'throw', includeDrafts = false, validate, } = options;
+    const warnings = [];
+    const baseUrl = rawBaseUrl.replace(/\/+$/, '');
+    // Routes as served: under the base URL
+    const routeBase = `${baseUrl}${contentRouteBase}`;
+    const roots = [...new Set(sidebarRoots.map((r) => r.replace(/^\/+|\/+$/g, '')))];
+    // Pass 1: every page, keyed by its path under the docs dir.
+    const pagesByFile = new Map();
+    (function walk(dirAbs) {
+        for (const entry of entries(dirAbs)) {
+            const full = path.join(dirAbs, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!isDoc(entry.name))
+                continue;
+            const file = path.relative(dir, full).split(path.sep).join('/');
+            const { data, body } = parseFrontmatter(fs.readFileSync(full, 'utf8'), file);
+            if (data.draft === true && !includeDrafts)
+                continue;
+            if (data.slug !== undefined || data.id !== undefined) {
+                throw new Error(`${file}: "slug" and "id" front matter are not supported; the route is the file path`);
+            }
+            const route = routeOf(file, routeBase);
+            const h1 = /^#\s+(.+)$/m.exec(body);
+            pagesByFile.set(file, {
+                route,
+                file,
+                sidebar: sidebarOf(file),
+                title: typeof data.title === 'string'
+                    ? data.title
+                    : h1
+                        ? h1[1].trim()
+                        : path.posix.basename(route),
+                sidebarLabel: typeof data.sidebar_label === 'string' ? data.sidebar_label : undefined,
+                description: typeof data.description === 'string' ? data.description : '',
+                tags: Array.isArray(data.tags) ? data.tags.map(String) : [],
+                position: typeof data.sidebar_position === 'number' ? data.sidebar_position : undefined,
+                frontmatter: data,
+                body,
+            });
+        }
+    })(dir);
+    function sidebarOf(file) {
+        const root = roots
+            .filter((r) => r === '' || file.startsWith(`${r}/`))
+            .sort((a, b) => b.length - a.length)[0];
+        return root === undefined ? null : sidebarId(root);
+    }
+    const pageByRoute = new Map();
+    for (const page of pagesByFile.values()) {
+        const clash = pageByRoute.get(page.route);
+        if (clash)
+            throw new Error(`duplicate route ${page.route}: ${clash.file} and ${page.file}`);
+        pageByRoute.set(page.route, page);
+    }
+    // Tags: closed vocabulary when given, as Docusaurus' onInlineTags: 'throw' enforces.
+    let tags;
+    if (vocabulary) {
+        for (const page of pagesByFile.values()) {
+            const unknown = page.tags.filter((tag) => !(tag in vocabulary));
+            if (unknown.length)
+                throw new Error(`${page.file}: unknown tag(s) ${unknown.join(', ')}`);
+        }
+        tags = Object.entries(vocabulary).map(([id, value]) => ({
+            id,
+            label: value?.label ?? id,
+            description: value?.description ?? '',
+        }));
+    }
+    else {
+        const used = [...new Set([...pagesByFile.values()].flatMap((p) => p.tags))];
+        tags = used.map((id) => ({ id, label: id, description: '' }));
+    }
+    // Sidebars and generated-index pages. One slugger across the site, so two categories
+    // with the same label get distinct generated-index routes.
+    const categories = [];
+    const categorySlug = createSlugger('github');
+    const sidebars = [];
+    for (const root of roots) {
+        const rootAbs = path.join(dir, root);
+        if (!fs.existsSync(rootAbs))
+            throw new Error(`sidebar root "${root}" does not exist under ${dir}`);
+        const meta = readCategory(rootAbs);
+        const id = sidebarId(root);
+        const own = [...pagesByFile.values()].filter((p) => p.sidebar === id);
+        if (own.length === 0)
+            continue;
+        sidebars.push({
+            id,
+            dir: root,
+            label: meta.label ?? (root ? path.posix.basename(root) : 'Docs'),
+            position: meta.position,
+            route: root ? `${routeBase}/${root}` : routeBase,
+            landingRoute: landingRouteOf(root ? `${routeBase}/${root}` : routeBase, own),
+            items: buildNav(root, id, roots),
+        });
+    }
+    sidebars.sort((a, b) => (a.position ?? Infinity) - (b.position ?? Infinity) || a.label.localeCompare(b.label));
+    /**
+     * One sidebar, built the way Docusaurus autogenerates it: pages and folders ordered by
+     * position (sidebar_position / _category_), unpositioned items after them in name order.
+     * A folder's index page becomes the folder's own link rather than an item inside it,
+     * unless its _category_ says otherwise. Nested sidebar roots are left to their own sidebar.
+     */
+    function buildNav(root, sidebar, allRoots) {
+        // Docs that are some category's own link, and so not items in any list.
+        const linkedDocs = new Set();
+        function build(dirRel, isRoot) {
+            const items = [];
+            for (const entry of entries(path.join(dir, dirRel))) {
+                const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    if (allRoots.includes(rel))
+                        continue; // its own sidebar
+                    items.push(buildCategory(rel));
+                }
+                else if (isDoc(entry.name)) {
+                    const page = pagesByFile.get(rel);
+                    if (!page)
+                        continue; // a draft
+                    items.push({
+                        type: 'page',
+                        title: page.sidebarLabel ?? page.title,
+                        route: page.route,
+                        position: page.position,
+                        file: rel,
+                        isRoot,
+                    });
+                }
+            }
+            return items;
+        }
+        function buildCategory(rel) {
+            const dirAbs = path.join(dir, rel);
+            const meta = readCategory(dirAbs);
+            const items = build(rel, false);
+            const indexFile = entries(dirAbs).find((e) => e.isFile() && isIndexDoc(e.name));
+            const label = meta.label ?? path.posix.basename(rel);
+            let route;
+            if (meta.link?.type === 'doc') {
+                const id = meta.link.id;
+                const linked = [`${id}.md`, `${id}.mdx`].find((f) => pagesByFile.has(f));
+                if (!linked)
+                    throw new Error(`${rel}/_category_ links to missing doc "${id}"`);
+                linkedDocs.add(linked);
+                route = pagesByFile.get(linked).route;
+            }
+            else if (meta.link?.type === 'generated-index') {
+                route = `${routeBase}${meta.link.slug ?? `/category/${categorySlug(label)}`}`;
+                categories.push({
+                    route,
+                    sidebar,
+                    title: meta.link.title ?? label,
+                    description: meta.link.description ?? '',
+                    items: [],
+                });
+            }
+            else if (indexFile &&
+                meta.link === undefined &&
+                pagesByFile.has(`${rel}/${indexFile.name}`)) {
+                // By convention a folder's index page is the folder's link.
+                linkedDocs.add(`${rel}/${indexFile.name}`);
+                route = pagesByFile.get(`${rel}/${indexFile.name}`).route;
+            }
+            return {
+                type: 'category',
+                label,
+                route,
+                position: meta.position,
+                ...(meta.collapsible !== undefined && { collapsible: meta.collapsible }),
+                ...(meta.collapsed !== undefined && { collapsed: meta.collapsed }),
+                items,
+            };
+        }
+        // Linked docs are only known once the whole tree is read, so drop them and sort afterwards.
+        // A category left with no items collapses as Docusaurus does: into a plain link under
+        // the category's label when it has one, or out of the sidebar when not.
+        const finish = (items) => sortItems(items.filter((item) => item.type !== 'page' || item.isRoot || !linkedDocs.has(item.file)))
+            .map((item) => {
+            if (item.type === 'page')
+                return { type: 'page', title: item.title, route: item.route };
+            const { items: drafts, ...rest } = item;
+            delete rest.position;
+            const category = rest;
+            const children = finish(drafts);
+            if (children.length > 0) {
+                // A generated-index page lists its items in sidebar order, as Docusaurus does.
+                const generated = category.route
+                    ? categories.find((c) => c.route === category.route && c.sidebar === sidebar)
+                    : undefined;
+                if (generated)
+                    generated.items = children;
+                return { ...category, items: children };
+            }
+            return category.route
+                ? { type: 'page', title: category.label, route: category.route }
+                : null;
+        })
+            .filter((item) => item !== null);
+        return finish(build(root, true));
+    }
+    // Pass 2: resolve links now that every route is known.
+    const knownRoutes = new Set([...pageByRoute.keys(), ...categories.map((c) => c.route)]);
+    const broken = [];
+    const anchorLinks = [];
+    const pages = [...pagesByFile.values()].map(({ body, ...page }) => ({
+        ...page,
+        markdown: resolveLinks(body, page, pagesByFile, knownRoutes, baseUrl, contentRouteBase, broken, anchorLinks),
+    }));
+    if (broken.length && onBrokenLinks === 'throw') {
+        throw new Error(`Broken links:\n${broken.map((b) => `  - ${b}`).join('\n')}`);
+    }
+    if (onBrokenLinks === 'warn')
+        warnings.push(...broken);
+    const content = { pages, sidebars, categories, tags };
+    if (validate)
+        for (const page of pages)
+            validate(page, content);
+    return { ...content, warnings, anchorLinks };
+}
+/** Sidebar ID for a root directory. */
+function sidebarId(root) {
+    return root || 'default';
+}
+/** The directory's index page, else its shallowest, lowest-positioned page. */
+function landingRouteOf(base, pages) {
+    if (pages.some((page) => page.route === base))
+        return base;
+    const depth = (page) => page.route.slice(base.length).split('/').length;
+    return [...pages].sort((a, b) => depth(a) - depth(b) ||
+        (a.position ?? Number.MAX_SAFE_INTEGER) - (b.position ?? Number.MAX_SAFE_INTEGER) ||
+        a.route.localeCompare(b.route))[0].route;
+}
+/** Positioned items first, by position; the rest keep their name order. */
+function sortItems(items) {
+    return items
+        .map((item, index) => ({ item, index }))
+        .sort((a, b) => (a.item.position ?? Infinity) - (b.item.position ?? Infinity) || a.index - b.index)
+        .map(({ item }) => item);
+}
+/**
+ * Rewrite links into site routes: relative `.md` references become the route of the file
+ * they name (anchors kept), `pathname://` is unwrapped, root-relative links and images get
+ * the base URL, and links under `routeBase` are checked against the known routes. Fenced
+ * code is left alone.
+ */
+function resolveLinks(markdown, page, pagesByFile, knownRoutes, baseUrl, routeBase, broken, anchorLinks) {
+    const { file } = page;
+    return markdown
+        .split(/(^ {0,3}(?:```|~~~)[\s\S]*?^ {0,3}(?:```|~~~))/m)
+        .map((chunk, i) => (i % 2 === 1 ? chunk : rewrite(chunk)))
+        .join('');
+    function rewrite(text) {
+        return text.replace(/(!?)\[([^\]]*)\]\(([^)\s]+)((?:\s+"[^"]*")?)\)/g, (match, bang, label, target, title) => {
+            if (target.startsWith('pathname://')) {
+                return `${bang}[${label}](${baseUrl}${target.slice('pathname://'.length)}${title})`;
+            }
+            if (target.startsWith('#')) {
+                if (!bang)
+                    anchorLinks.push({ file, route: page.route, anchor: target.slice(1) });
+                return match;
+            }
+            if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//'))
+                return match;
+            const [refPath, anchor] = target.split('#');
+            if (refPath.startsWith('/')) {
+                // Root-relative: served under the base URL, like Docusaurus' baseUrl
+                if (!bang && (refPath.startsWith(`${routeBase}/`) || refPath === routeBase)) {
+                    const route = `${baseUrl}${refPath.replace(/\/$/, '')}`;
+                    if (!knownRoutes.has(route))
+                        broken.push(`${file}: link to unknown route ${target}`);
+                    else if (anchor)
+                        anchorLinks.push({ file, route, anchor });
+                }
+                return baseUrl ? `${bang}[${label}](${baseUrl}${target}${title})` : match;
+            }
+            if (bang)
+                return match;
+            if (!isDoc(refPath))
+                return match;
+            const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(file), refPath));
+            const linked = pagesByFile.get(resolved);
+            if (!linked) {
+                broken.push(`${file}: unresolved link ${target}`);
+                return match;
+            }
+            if (anchor)
+                anchorLinks.push({ file, route: linked.route, anchor });
+            return `[${label}](${linked.route}${anchor ? `#${anchor}` : ''}${title})`;
+        });
+    }
+}

package/dist/lib/content/nav.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Helpers over sidebar trees. Pure functions on plain data: safe in the browser.
+ */
+import type { DocSource, NavItem, Tag } from './types.js';
+export interface NavLink {
+    title: string;
+    route: string;
+}
+/** Every linkable entry in sidebar order (pages, and categories with their own page), deduped. */
+export declare function flattenNav(items: NavItem[]): NavLink[];
+/** Previous and next entries around `route`, in sidebar order: the page footer links. */
+export declare function neighbours(items: NavItem[], route: string): {
+    previous: NavLink | null;
+    next: NavLink | null;
+};
+export interface Crumb {
+    label: string;
+    /** Undefined for a category without its own page */
+    route?: string;
+}
+/**
+ * The categories leading to `route`, outermost first, ending with the page itself.
+ * Empty when the route isn't in the tree. A category whose own page is `route` ends the
+ * trail. Prepend the sidebar (and a home link) yourself if the layout wants them.
+ */
+export declare function breadcrumbs(items: NavItem[], route: string): Crumb[];
+/** Whether `route` is in the tree under `item` (the item itself included). */
+export declare function navContains(item: NavItem, route: string): boolean;
+/** Linkable entries under a sidebar list, recursively (pages and categories with their own page). */
+export declare function countPages(items: NavItem[]): number;
+/** Tags in use among `pages`, with how many pages carry each, in vocabulary order. */
+export declare function tagCounts(tags: Tag[], pages: Pick<DocSource, 'tags'>[]): (Tag & {
+    count: number;
+})[];
+/** Pages carrying `tag`, by title. */
+export declare function pagesTagged<T extends Pick<DocSource, 'tags' | 'title'>>(pages: T[], tag: string): T[];

package/dist/lib/content/nav.js

@@ -0,0 +1,81 @@
+/**
+ * Helpers over sidebar trees. Pure functions on plain data: safe in the browser.
+ */
+/** Every linkable entry in sidebar order (pages, and categories with their own page), deduped. */
+export function flattenNav(items) {
+    const flat = [];
+    const seen = new Set();
+    const add = (title, route) => {
+        if (seen.has(route))
+            return;
+        seen.add(route);
+        flat.push({ title, route });
+    };
+    (function walk(list) {
+        for (const item of list) {
+            if (item.type === 'page')
+                add(item.title, item.route);
+            else {
+                if (item.route)
+                    add(item.label, item.route);
+                walk(item.items);
+            }
+        }
+    })(items);
+    return flat;
+}
+/** Previous and next entries around `route`, in sidebar order: the page footer links. */
+export function neighbours(items, route) {
+    const flat = flattenNav(items);
+    const index = flat.findIndex((entry) => entry.route === route);
+    return {
+        previous: index > 0 ? flat[index - 1] : null,
+        next: index >= 0 && index < flat.length - 1 ? flat[index + 1] : null,
+    };
+}
+/**
+ * The categories leading to `route`, outermost first, ending with the page itself.
+ * Empty when the route isn't in the tree. A category whose own page is `route` ends the
+ * trail. Prepend the sidebar (and a home link) yourself if the layout wants them.
+ */
+export function breadcrumbs(items, route) {
+    for (const item of items) {
+        if (item.type === 'page') {
+            if (item.route === route)
+                return [{ label: item.title, route: item.route }];
+            continue;
+        }
+        if (item.route === route)
+            return [{ label: item.label, route: item.route }];
+        const inner = breadcrumbs(item.items, route);
+        if (inner.length)
+            return [{ label: item.label, route: item.route }, ...inner];
+    }
+    return [];
+}
+/** Whether `route` is in the tree under `item` (the item itself included). */
+export function navContains(item, route) {
+    return item.type === 'page'
+        ? item.route === route
+        : item.route === route || item.items.some((child) => navContains(child, route));
+}
+/** Linkable entries under a sidebar list, recursively (pages and categories with their own page). */
+export function countPages(items) {
+    return items.reduce((n, item) => n + (item.type === 'page' ? 1 : (item.route ? 1 : 0) + countPages(item.items)), 0);
+}
+/** Tags in use among `pages`, with how many pages carry each, in vocabulary order. */
+export function tagCounts(tags, pages) {
+    const counts = new Map();
+    for (const page of pages)
+        for (const tag of page.tags)
+            counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    return tags
+        .filter((tag) => counts.has(tag.id))
+        .map((tag) => ({ ...tag, count: counts.get(tag.id) }));
+}
+/** Pages carrying `tag`, by title. */
+export function pagesTagged(pages, tag) {
+    return pages
+        .filter((page) => page.tags.includes(tag))
+        .sort((a, b) => a.title.localeCompare(b.title));
+}

package/dist/lib/content/render.d.ts

@@ -0,0 +1,38 @@
+import type { ParseOptions } from '../types/frontmatter.js';
+import type { BrokenLinkPolicy, LoadedDocs } from './load.js';
+import type { RenderedDoc } from './types.js';
+export interface RenderDocsOptions {
+    /** Options for `parseMarkdown`, applied to every page */
+    parse?: ParseOptions;
+    /**
+     * Sanitize each page with `sanitizeDocsHtml` (from `@classic-homes/theme-docs/sanitize`).
+     * Removals are reported in `sanitized`. Default: false
+     */
+    sanitize?: boolean;
+    /** Links to `#anchors` that don't exist on the target page. Default: `'warn'`, as Docusaurus */
+    onBrokenAnchors?: BrokenLinkPolicy;
+    /**
+     * Lift a page's leading `# Heading` out of the body: it becomes the title when the page
+     * has no `title` front matter, and the layout renders it (so content such as a lead
+     * paragraph can sit between title and body). Default: false
+     */
+    hoistTitle?: boolean;
+}
+export interface RenderDocsResult {
+    pages: RenderedDoc[];
+    /** Broken anchors (when `'warn'`) */
+    warnings: string[];
+    /** Pages the sanitizer changed, and what it removed */
+    sanitized: {
+        file: string;
+        removed: string[];
+    }[];
+}
+/**
+ * Render every page loaded by `loadDocs` to HTML, then check `#anchor` links against the
+ * IDs the target pages actually have. Run it at build time: Shiki and marked then never
+ * load in the browser or the server runtime.
+ */
+export declare function renderDocs(docs: LoadedDocs, options?: RenderDocsOptions): Promise<RenderDocsResult>;
+/** Searchable text: rendered HTML minus markup, code blocks and diagrams. */
+export declare function plainText(html: string): string;

package/dist/lib/content/render.js

@@ -0,0 +1,84 @@
+import { parseMarkdown } from '../parser/index.js';
+/**
+ * Render every page loaded by `loadDocs` to HTML, then check `#anchor` links against the
+ * IDs the target pages actually have. Run it at build time: Shiki and marked then never
+ * load in the browser or the server runtime.
+ */
+export async function renderDocs(docs, options = {}) {
+    const { parse, sanitize = false, onBrokenAnchors = 'warn', hoistTitle = false } = options;
+    const sanitizeHtml = sanitize ? (await import('../sanitize/index.js')).sanitizeDocsHtml : null;
+    const sanitized = [];
+    const pages = await Promise.all(docs.pages.map(async ({ markdown, ...page }) => {
+        // Front matter was already read by loadDocs, so the body parses as plain markdown.
+        const rendered = await parseMarkdown(markdown, parse);
+        let html = rendered.html;
+        let { title } = page;
+        let toc = rendered.toc;
+        if (hoistTitle) {
+            const leading = /^\s*<h1\b[^>]*>([\s\S]*?)<\/h1>\s*/.exec(html);
+            if (leading) {
+                html = html.slice(leading[0].length);
+                if (page.frontmatter.title === undefined)
+                    title = plainText(leading[1]);
+                toc = toc.filter((entry, i) => !(i === 0 && entry.level === 1));
+            }
+        }
+        if (sanitizeHtml) {
+            const result = sanitizeHtml(html);
+            html = result.html;
+            if (result.removed.length)
+                sanitized.push({ file: page.file, removed: result.removed });
+        }
+        return {
+            ...page,
+            title,
+            html,
+            toc,
+            hasH1: toc.some((entry) => entry.level === 1) || /<h1[\s>]/.test(html),
+            text: plainText(html),
+        };
+    }));
+    const warnings = [];
+    if (onBrokenAnchors !== 'ignore') {
+        const idsByRoute = new Map(pages.map((p) => [p.route, elementIds(p.html)]));
+        const broken = docs.anchorLinks
+            .filter(({ route, anchor }) => {
+            const ids = idsByRoute.get(route);
+            // Category pages have no headings to link to; their routes were checked by loadDocs.
+            return ids !== undefined && !ids.has(decodeURIComponent(anchor));
+        })
+            .map(({ file, route, anchor }) => `${file}: link to missing anchor ${route}#${anchor}`);
+        if (broken.length && onBrokenAnchors === 'throw') {
+            throw new Error(`Broken anchors:\n${broken.map((b) => `  - ${b}`).join('\n')}`);
+        }
+        warnings.push(...broken);
+    }
+    return { pages, warnings, sanitized };
+}
+/** Every `id` (and `name`) attribute in a page: headings, footnotes, explicit anchors. */
+function elementIds(html) {
+    return new Set([...html.matchAll(/\s(?:id|name)="([^"]+)"/g)].map((m) => decodeEntities(m[1])));
+}
+function decodeEntities(text) {
+    return text
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#0?39;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+const BLOCK_TAG = /<\/?(?:p|div|section|article|li|ul|ol|dl|dt|dd|h[1-6]|table|thead|tbody|tr|td|th|blockquote|br|hr|details|summary)\b[^>]*>/gi;
+/** Searchable text: rendered HTML minus markup, code blocks and diagrams. */
+export function plainText(html) {
+    return decodeEntities(html
+        .replace(/<pre[\s\S]*?<\/pre>/g, ' ')
+        .replace(/<svg[\s\S]*?<\/svg>/g, ' ')
+        .replace(/<a class="hash-link"[\s\S]*?<\/a>/g, '')
+        .replace(/<span class="external-link-hint">[\s\S]*?<\/span>/g, '')
+        // Block boundaries separate words; inline tags (links, emphasis) must not split them
+        .replace(BLOCK_TAG, ' ')
+        .replace(/<[^>]+>/g, ''))
+        .replace(/\s+/g, ' ')
+        .trim();
+}