blodemd 0.0.13 → 0.0.15

package/packages/@repo/previewing/dist/index.js

@@ -1,1005 +1,13 @@
-import path from "node:path";
-import { ensureArray, normalizePath, slugify } from "@repo/common";
-import { PageModeSchema } from "@repo/models";
-import { extractOpenApiOperations, openApiIdentifier, openApiSlug, parseOpenApiSpec, } from "@repo/prebuild";
-import { validateDocsConfig, validateFrontmatter, validateSiteConfig, } from "@repo/validation";
-import YAML from "yaml";
 export { BlobContentSource, createBlobSource } from "./blob-source.js";
+export { getDocsCollection, getDocsCollectionWithNavigation, getDocsNavigation, loadSiteConfig, } from "./config-loader.js";
+export { LEGACY_PROJECT_NAME_FALLBACK_WARNING, PREBUILT_INDEX_PATH, PREBUILT_OPENAPI_INDEX_PATH, PREBUILT_SEARCH_INDEX_PATH, PREBUILT_TOC_INDEX_PATH, PREBUILT_UTILITY_INDEX_PATH, PREBUILT_UTILITY_LLMS_FULL_PATH, PREBUILT_UTILITY_LLMS_PATH, PREBUILT_UTILITY_LLMS_SEGMENT_PREFIX, PREBUILT_UTILITY_SITEMAP_PATH, PREBUILT_UTILITY_SKILLS_INDEX_PATH, PREBUILT_UTILITY_SKILLS_MD_PREFIX, UTILITY_DOCS_ROOT_TOKEN, } from "./constants.js";
+export { buildContentIndex, buildPageMetadataMap } from "./content-index.js";
 export { createFsSource, FsContentSource } from "./fs-source.js";
-export const PREBUILT_INDEX_PATH = "_content-index.json";
-export const PREBUILT_OPENAPI_INDEX_PATH = "_openapi-index.json";
-export const PREBUILT_SEARCH_INDEX_PATH = "_search-index.json";
-export const PREBUILT_TOC_INDEX_PATH = "_toc-index.json";
-export const PREBUILT_UTILITY_INDEX_PATH = "_utility-index.json";
-export const PREBUILT_UTILITY_SITEMAP_PATH = "_utility/sitemap.xml";
-export const PREBUILT_UTILITY_LLMS_PATH = "_utility/llms.txt";
-export const PREBUILT_UTILITY_LLMS_FULL_PATH = "_utility/llms-full.txt";
-export const PREBUILT_UTILITY_SKILLS_INDEX_PATH = "_utility/skills-index.json";
-export const PREBUILT_UTILITY_SKILLS_MD_PREFIX = "_utility/skills/";
-export const UTILITY_DOCS_ROOT_TOKEN = "__BLODEMD_DOCS_ROOT__";
-export const LEGACY_PROJECT_NAME_FALLBACK_WARNING = "docs.json.slug is recommended. Falling back to docs.json.name as the deployment slug is deprecated.";
-const validModes = new Set(PageModeSchema.options);
-export const buildPageMetadataMap = (index) => {
-    const map = new Map();
-    for (const entry of index.entries) {
-        if (entry.kind !== "entry") {
-            continue;
-        }
-        const fm = entry.frontmatter;
-        const meta = {
-            title: entry.title,
-        };
-        const hasFields = true;
-        if (typeof fm.sidebarTitle === "string") {
-            meta.sidebarTitle = fm.sidebarTitle;
-        }
-        if (typeof fm.icon === "string") {
-            meta.icon = fm.icon;
-        }
-        if (typeof fm.iconType === "string") {
-            meta.iconType = fm.iconType;
-        }
-        if (typeof fm.tag === "string") {
-            meta.tag = fm.tag;
-        }
-        if (typeof fm.hidden === "boolean") {
-            meta.hidden = fm.hidden;
-        }
-        if (typeof fm.deprecated === "boolean") {
-            meta.deprecated = fm.deprecated;
-        }
-        if (typeof fm.url === "string") {
-            meta.url = fm.url;
-        }
-        if (typeof fm.mode === "string" && validModes.has(fm.mode)) {
-            meta.mode = fm.mode;
-        }
-        if (typeof fm.noindex === "boolean") {
-            meta.noindex = fm.noindex;
-        }
-        if (typeof fm.hideFooterPagination === "boolean") {
-            meta.hideFooterPagination = fm.hideFooterPagination;
-        }
-        if (typeof fm.hideApiMarker === "boolean") {
-            meta.hideApiMarker = fm.hideApiMarker;
-        }
-        if (Array.isArray(fm.keywords)) {
-            meta.keywords = fm.keywords;
-        }
-        if (hasFields) {
-            map.set(entry.slug, meta);
-        }
-    }
-    return map;
-};
-const DOCS_CONFIG_FILE = "docs.json";
-const DOC_FILE_EXTENSION_REGEX = /\.(mdx|md)$/;
-const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
-const INDEX_SUFFIX = "/index";
-const titleFromSlug = (slug) => {
-    const clean = slug.replaceAll("-", " ").split("/").pop() ?? slug;
-    if (clean === "index") {
-        return "Overview";
-    }
-    return clean.replaceAll(/\b\w/g, (char) => char.toUpperCase());
-};
-const parseFrontmatter = (source) => {
-    const match = FRONTMATTER_REGEX.exec(source);
-    if (!match) {
-        return { body: source, frontmatter: {} };
-    }
-    const raw = match[1] ?? "";
-    const data = YAML.parse(raw) ?? {};
-    const body = source.slice(match[0].length);
-    return { body, frontmatter: data };
-};
-const slugFromFile = (relativePath) => {
-    const clean = normalizePath(relativePath);
-    const withoutExt = clean.replace(DOC_FILE_EXTENSION_REGEX, "");
-    if (withoutExt.endsWith(INDEX_SUFFIX)) {
-        const trimmed = withoutExt.slice(0, -INDEX_SUFFIX.length);
-        return trimmed.length ? trimmed : "index";
-    }
-    return withoutExt.length ? withoutExt : "index";
-};
-const defaultLinkLabel = (input) => {
-    if (input.label) {
-        return input.label;
-    }
-    if (input.type === "github") {
-        return "GitHub";
-    }
-    if (input.type === "discord") {
-        return "Discord";
-    }
-    try {
-        return new URL(input.href).hostname;
-    }
-    catch {
-        return input.href;
-    }
-};
-// oxlint-disable-next-line eslint/complexity
-const mapDocsConfig = (docs) => {
-    const navigation = {
-        global: docs.navbar?.links?.length || docs.navigation.global?.anchors?.length
-            ? {
-                anchors: docs.navigation.global?.anchors?.map((anchor) => ({
-                    href: anchor.href,
-                    label: anchor.anchor,
-                })),
-                links: docs.navbar?.links?.map((link) => ({
-                    href: link.href,
-                    label: defaultLinkLabel(link),
-                })),
-            }
-            : undefined,
-        groups: docs.navigation.groups?.map((group) => ({
-            expanded: group.expanded,
-            group: group.group,
-            hidden: group.hidden,
-            pages: group.root
-                ? [
-                    group.root,
-                    ...(group.pages ?? []).filter((page) => page !== group.root),
-                ]
-                : group.pages,
-        })),
-        languages: docs.navigation.languages?.map((language) => ({
-            label: language.language,
-            locale: language.language,
-            url: language.href,
-        })),
-        pages: docs.navigation.pages,
-        tabs: docs.navigation.tabs?.map((tab) => ({
-            groups: tab.groups?.map((group) => ({
-                expanded: group.expanded,
-                group: group.group,
-                hidden: group.hidden,
-                pages: group.root
-                    ? [
-                        group.root,
-                        ...(group.pages ?? []).filter((page) => page !== group.root),
-                    ]
-                    : group.pages,
-            })),
-            href: tab.href,
-            icon: tab.icon,
-            label: tab.tab,
-            pages: tab.pages,
-        })),
-        versions: docs.navigation.versions?.map((version) => ({
-            label: version.version,
-            url: version.href,
-        })),
-    };
-    return {
-        collections: [
-            {
-                id: "docs",
-                navigation,
-                openapi: docs.api?.openapi,
-                root: "",
-                type: "docs",
-            },
-        ],
-        contextual: docs.contextual,
-        description: docs.description,
-        favicon: typeof docs.favicon === "string" ? docs.favicon : docs.favicon?.light,
-        features: {
-            rightToc: true,
-            search: true,
-            themeToggle: docs.appearance?.strict !== true,
-            toc: true,
-        },
-        logo: docs.logo
-            ? {
-                dark: typeof docs.logo === "string" ? docs.logo : docs.logo.dark,
-                href: typeof docs.logo === "string" ? undefined : docs.logo.href,
-                light: typeof docs.logo === "string" ? docs.logo : docs.logo.light,
-            }
-            : undefined,
-        name: docs.name,
-        navigation,
-        openapiProxy: {
-            enabled: docs.api?.playground?.proxy !== false &&
-                Boolean(docs.api?.openapi || docs.api?.asyncapi),
-        },
-        seo: docs.seo,
-        slug: docs.slug,
-    };
-};
-const getProjectWarnings = (config) => config.slug ? [] : [LEGACY_PROJECT_NAME_FALLBACK_WARNING];
-const readJsonConfig = async (source, relativePath) => JSON.parse(await source.readFile(relativePath));
-const normalizeRefPath = (baseDirectory, reference) => {
-    if (reference.startsWith("/") ||
-        reference.startsWith("\\") ||
-        reference.startsWith("http://") ||
-        reference.startsWith("https://")) {
-        throw new Error(`Invalid $ref "${reference}". Only relative JSON files are supported.`);
-    }
-    const normalized = normalizePath(path.posix.join(baseDirectory, reference));
-    if (!normalized ||
-        normalized === "." ||
-        normalized.startsWith("../") ||
-        normalized.includes("/../")) {
-        throw new Error(`Invalid $ref "${reference}".`);
-    }
-    return normalized;
-};
-const resolveJsonRefs = async (source, value, baseDirectory, seen) => {
-    if (Array.isArray(value)) {
-        return await Promise.all(value.map((item) => resolveJsonRefs(source, item, baseDirectory, seen)));
-    }
-    if (!value || typeof value !== "object") {
-        return value;
-    }
-    const record = value;
-    const reference = record.$ref;
-    if (typeof reference === "string") {
-        const resolvedPath = normalizeRefPath(baseDirectory, reference);
-        if (seen.has(resolvedPath)) {
-            throw new Error(`Circular $ref detected for "${resolvedPath}".`);
-        }
-        const nextSeen = new Set(seen);
-        // oxlint-disable-next-line eslint-plugin-unicorn/no-immediate-mutation
-        nextSeen.add(resolvedPath);
-        const referenced = await readJsonConfig(source, resolvedPath);
-        const referencedValue = await resolveJsonRefs(source, referenced, path.posix.dirname(resolvedPath) === "."
-            ? ""
-            : normalizePath(path.posix.dirname(resolvedPath)), nextSeen);
-        const siblingEntries = Object.entries(record).filter(([key]) => key !== "$ref");
-        if (!siblingEntries.length ||
-            !referencedValue ||
-            typeof referencedValue !== "object" ||
-            Array.isArray(referencedValue)) {
-            return referencedValue;
-        }
-        const siblingValue = await resolveJsonRefs(source, Object.fromEntries(siblingEntries), baseDirectory, seen);
-        return {
-            ...referencedValue,
-            ...siblingValue,
-        };
-    }
-    const resolvedEntries = await Promise.all(Object.entries(record).map(async ([key, entryValue]) => [
-        key,
-        await resolveJsonRefs(source, entryValue, baseDirectory, seen),
-    ]));
-    return Object.fromEntries(resolvedEntries);
-};
-const readResolvedJsonConfig = async (source, relativePath) => await resolveJsonRefs(source, await readJsonConfig(source, relativePath), path.posix.dirname(relativePath) === "."
-    ? ""
-    : normalizePath(path.posix.dirname(relativePath)), new Set([relativePath]));
-const loadDocsConfig = async (source) => {
-    if (!(await source.exists(DOCS_CONFIG_FILE))) {
-        return null;
-    }
-    try {
-        const parsed = await readResolvedJsonConfig(source, DOCS_CONFIG_FILE);
-        // Try SiteConfig format first (has collections, theme, colors, etc.)
-        const siteResult = validateSiteConfig(parsed);
-        if (siteResult.success) {
-            return {
-                config: siteResult.data,
-                ok: true,
-                warnings: getProjectWarnings(siteResult.data),
-            };
-        }
-        // Fall back to DocsConfig format (Mintlify-compatible) and map to SiteConfig
-        const docsResult = validateDocsConfig(parsed);
-        if (docsResult.success) {
-            return {
-                config: mapDocsConfig(docsResult.data),
-                ok: true,
-                warnings: getProjectWarnings(docsResult.data),
-            };
-        }
-        return { errors: docsResult.errors, ok: false };
-    }
-    catch (error) {
-        return {
-            errors: [
-                error instanceof Error
-                    ? error.message
-                    : `Failed to load ${DOCS_CONFIG_FILE}`,
-            ],
-            ok: false,
-        };
-    }
-};
-export const loadSiteConfig = async (source) => {
-    const docsConfig = await loadDocsConfig(source);
-    if (docsConfig) {
-        return docsConfig;
-    }
-    return {
-        errors: [`${DOCS_CONFIG_FILE} not found.`],
-        ok: false,
-    };
-};
-export const loadContentSource = async (source, relativePath) => await source.readFile(relativePath);
-const listContentFiles = async (source, directory) => {
-    const files = await source.listFiles(directory);
-    return files.filter((file) => DOC_FILE_EXTENSION_REGEX.test(file));
-};
-const sortDefaults = {
-    blog: { direction: "desc", field: "date" },
-    courses: { direction: "asc", field: "order" },
-    docs: { direction: "asc", field: "title" },
-    forms: { direction: "asc", field: "title" },
-    notes: { direction: "desc", field: "date" },
-    products: { direction: "asc", field: "title" },
-    sheets: { direction: "asc", field: "title" },
-    site: { direction: "asc", field: "title" },
-    slides: { direction: "asc", field: "title" },
-    todos: { direction: "desc", field: "date" },
-};
-const normalizeSortValue = (value) => {
-    if (typeof value === "number") {
-        return value;
-    }
-    if (typeof value === "string") {
-        const timestamp = Date.parse(value);
-        if (!Number.isNaN(timestamp)) {
-            return timestamp;
-        }
-        return value.toLowerCase();
-    }
-    return null;
-};
-const compareValues = (a, b, direction) => {
-    const left = normalizeSortValue(a);
-    const right = normalizeSortValue(b);
-    if (left === null && right === null) {
-        return 0;
-    }
-    if (left === null) {
-        return 1;
-    }
-    if (right === null) {
-        return -1;
-    }
-    const multiplier = direction === "desc" ? -1 : 1;
-    if (typeof left === "number" && typeof right === "number") {
-        return (left - right) * multiplier;
-    }
-    if (left < right) {
-        return -1 * multiplier;
-    }
-    if (left > right) {
-        return 1 * multiplier;
-    }
-    return 0;
-};
-const autoIndexTypes = new Set([
-    "blog",
-    "courses",
-    "products",
-    "notes",
-    "forms",
-    "sheets",
-    "slides",
-    "todos",
-]);
-const getCollectionIndex = (collection, slugPrefix) => {
-    if (collection.index) {
-        return collection.index;
-    }
-    if (autoIndexTypes.has(collection.type)) {
-        const slug = slugPrefix || collection.id;
-        return {
-            slug,
-            title: titleFromSlug(slug),
-        };
-    }
-    return null;
-};
-const addEntry = (entry, index, errors) => {
-    if (index.bySlug.has(entry.slug)) {
-        errors.push(`slug "${entry.slug}" is defined more than once`);
-        return;
-    }
-    index.entries.push(entry);
-    index.bySlug.set(entry.slug, entry);
-};
-const resolveEntrySlug = (relativeSlug, slugPrefix) => {
-    if (!slugPrefix) {
-        return relativeSlug;
-    }
-    if (relativeSlug === "index") {
-        return slugPrefix;
-    }
-    return normalizePath(`${slugPrefix}/${relativeSlug}`);
-};
-const buildEntryFromFile = async ({ collection, errors, file, root, slugPrefix, source, }) => {
-    const sourcePath = root
-        ? normalizePath(path.join(root, file))
-        : normalizePath(file);
-    let entrySource = "";
-    try {
-        entrySource = await source.readFile(sourcePath);
-    }
-    catch (error) {
-        errors.push(error instanceof Error ? error.message : `Failed to read ${sourcePath}`);
-        return null;
-    }
-    const { frontmatter } = parseFrontmatter(entrySource);
-    const frontmatterResult = validateFrontmatter(collection.type, frontmatter);
-    if (!frontmatterResult.success) {
-        for (const issue of frontmatterResult.errors) {
-            errors.push(`${sourcePath}: ${issue}`);
-        }
-    }
-    const resolvedFrontmatter = frontmatterResult.success
-        ? frontmatterResult.data
-        : frontmatter;
-    const relativeSlug = slugFromFile(file);
-    const slug = resolveEntrySlug(relativeSlug, slugPrefix);
-    const title = typeof resolvedFrontmatter?.title === "string"
-        ? resolvedFrontmatter.title
-        : titleFromSlug(slug);
-    const description = typeof resolvedFrontmatter?.description === "string"
-        ? resolvedFrontmatter.description
-        : undefined;
-    const hidden = typeof resolvedFrontmatter?.hidden === "boolean"
-        ? resolvedFrontmatter.hidden
-        : undefined;
-    return {
-        collectionId: collection.id,
-        description,
-        frontmatter: resolvedFrontmatter,
-        hidden: hidden || undefined,
-        kind: "entry",
-        relativePath: sourcePath,
-        slug,
-        sourcePath,
-        title,
-        type: collection.type,
-    };
-};
-export const buildContentIndex = async (source, config) => {
-    const errors = [];
-    const index = {
-        byCollection: new Map(),
-        bySlug: new Map(),
-        entries: [],
-        errors,
-    };
-    for (const collection of config.collections) {
-        const root = normalizePath(collection.root ?? "");
-        const slugPrefix = normalizePath(collection.slugPrefix ?? "");
-        let files = [];
-        try {
-            files = await listContentFiles(source, root);
-        }
-        catch (error) {
-            errors.push(error instanceof Error ? error.message : `Failed to read ${root || "."}`);
-            continue;
-        }
-        const collectionEntries = [];
-        const resolvedEntries = await Promise.all(files.map(async (file) => await buildEntryFromFile({
-            collection,
-            errors,
-            file,
-            root,
-            slugPrefix,
-            source,
-        })));
-        for (const entry of resolvedEntries) {
-            if (!entry) {
-                continue;
-            }
-            collectionEntries.push(entry);
-            addEntry(entry, index, errors);
-        }
-        const sortConfig = {
-            ...sortDefaults[collection.type],
-            ...collection.sort,
-        };
-        const sortField = sortConfig.field ?? "title";
-        const sortDirection = sortConfig.direction ?? "asc";
-        collectionEntries.sort((left, right) => {
-            const leftValue = left.kind === "entry"
-                ? left.frontmatter[sortField]
-                : undefined;
-            const rightValue = right.kind === "entry"
-                ? right.frontmatter[sortField]
-                : undefined;
-            return compareValues(leftValue, rightValue, sortDirection);
-        });
-        index.byCollection.set(collection.id, collectionEntries);
-        const collectionIndex = getCollectionIndex(collection, slugPrefix);
-        if (collectionIndex) {
-            const indexEntry = {
-                collectionId: collection.id,
-                description: collectionIndex.description,
-                kind: "index",
-                slug: collectionIndex.slug,
-                title: collectionIndex.title ?? titleFromSlug(collectionIndex.slug),
-                type: collection.type,
-            };
-            addEntry(indexEntry, index, errors);
-        }
-    }
-    return index;
-};
-const NEWLINE_REGEX = /\r?\n/;
-const HEADING_REGEX = /^(#{2,4})\s+(.*)$/;
-const LEADING_H1_REGEX = /^#\s+([^\r\n]+)(?:\r?\n(?:\r?\n)?)?/;
-export const extractToc = (source) => {
-    const withoutCode = source.replaceAll(/```[\s\S]*?```/g, "");
-    const lines = withoutCode.split(NEWLINE_REGEX);
-    const toc = [];
-    for (const line of lines) {
-        const match = HEADING_REGEX.exec(line.trim());
-        if (!match) {
-            continue;
-        }
-        const [, hashes = "", heading = ""] = match;
-        if (!(hashes && heading)) {
-            continue;
-        }
-        toc.push({
-            id: slugify(heading.trim()),
-            level: hashes.length,
-            title: heading.trim(),
-        });
-    }
-    return toc;
-};
-const stripMatchingLeadingH1 = (source, title) => {
-    const trimmed = source.trimStart();
-    const match = LEADING_H1_REGEX.exec(trimmed);
-    if (!match) {
-        return trimmed.trim();
-    }
-    const [headingLine = "", headingTitle = ""] = match;
-    if (slugify(headingTitle) !== slugify(title)) {
-        return trimmed.trim();
-    }
-    return trimmed.slice(headingLine.length).trim();
-};
-export const formatMarkdownPage = (title, source) => {
-    const content = stripMatchingLeadingH1(source, title);
-    if (!content) {
-        return `# ${title}`;
-    }
-    return `# ${title}\n\n${content}`;
-};
-export const formatMarkdownPageSection = (title, url, source) => {
-    const content = stripMatchingLeadingH1(source, title);
-    if (!content) {
-        return `# ${title} (${url})`;
-    }
-    return `# ${title} (${url})\n\n${content}`;
-};
-const shouldIncludeSearchEntry = (entry, pageMetadataMap, config) => {
-    const pageMeta = pageMetadataMap.get(entry.slug);
-    if (pageMeta?.hidden || pageMeta?.noindex) {
-        return false;
-    }
-    if (config.seo?.indexing !== "all" &&
-        entry.kind === "entry" &&
-        entry.hidden === true) {
-        return false;
-    }
-    return true;
-};
-const stripFrontmatter = (source) => parseFrontmatter(source).body.trim();
-const getDocsCollection = (config) => config.collections.find((collection) => collection.type === "docs");
-const getDocsNavigation = (config) => getDocsCollection(config)?.navigation ?? config.navigation;
-const getDocsCollectionWithNavigation = (config) => {
-    const docsCollection = getDocsCollection(config);
-    const docsNavigation = getDocsNavigation(config);
-    return docsCollection &&
-        docsNavigation &&
-        docsCollection.navigation !== docsNavigation
-        ? { ...docsCollection, navigation: docsNavigation }
-        : docsCollection;
-};
-const getOpenApiSourceKey = (source) => `${source.source}::${source.directory ?? ""}::${(source.include ?? []).join("|")}`;
-const toOpenApiSourceObject = (value) => {
-    if (typeof value === "string") {
-        return { source: value };
-    }
-    return value;
-};
-const collectOpenApiSources = (collection) => {
-    const sources = [];
-    for (const item of ensureArray(collection?.openapi)) {
-        if (!item) {
-            continue;
-        }
-        sources.push(toOpenApiSourceObject(item));
-    }
-    const groups = collection?.navigation?.groups ?? [];
-    for (const group of groups) {
-        if (!group.openapi) {
-            continue;
-        }
-        sources.push(toOpenApiSourceObject(group.openapi));
-    }
-    const seen = new Set();
-    return sources.filter((source) => {
-        const key = getOpenApiSourceKey(source);
-        if (seen.has(key)) {
-            return false;
-        }
-        seen.add(key);
-        return true;
-    });
-};
-const formatOpenApiPageContent = (operation) => {
-    const parts = [`Method: ${operation.method}`, `Path: ${operation.path}`];
-    if (operation.description) {
-        parts.push(operation.description);
-    }
-    if (operation.tags.length) {
-        parts.push(`Tags: ${operation.tags.join(", ")}`);
-    }
-    if (operation.parameters.length) {
-        parts.push(`Parameters:\n${JSON.stringify(operation.parameters, null, 2)}`);
-    }
-    if (operation.requestBody) {
-        parts.push(`Request Body:\n${JSON.stringify(operation.requestBody, null, 2)}`);
-    }
-    if (operation.responses) {
-        parts.push(`Responses:\n${JSON.stringify(operation.responses, null, 2)}`);
-    }
-    return parts.join("\n\n");
-};
-const getGroupedOpenApiSourceKey = (source) => getOpenApiSourceKey(toOpenApiSourceObject(source));
-const collectUtilityOpenApiPages = (pagesByIdentifier, pagesBySource, operations, directory, openApiSource, slugPrefix) => {
-    const sourceKey = getOpenApiSourceKey(openApiSource);
-    const includeIdentifiers = openApiSource.include?.length
-        ? new Set(openApiSource.include)
-        : null;
-    for (const operation of operations) {
-        const identifier = openApiIdentifier(operation.method, operation.path);
-        if (includeIdentifiers && !includeIdentifiers.has(identifier)) {
-            continue;
-        }
-        const baseSlug = normalizePath(openApiSlug(operation.method, operation.path, directory));
-        const slug = slugPrefix
-            ? normalizePath(`${slugPrefix}/${baseSlug}`)
-            : baseSlug;
-        const page = {
-            content: formatOpenApiPageContent(operation),
-            description: operation.description,
-            identifier,
-            slug,
-            sourceKey,
-            title: operation.summary ?? identifier,
-        };
-        pagesByIdentifier.set(identifier, page);
-        if (!pagesBySource.has(sourceKey)) {
-            pagesBySource.set(sourceKey, []);
-        }
-        pagesBySource.get(sourceKey)?.push(page);
-    }
-};
-const addUtilityPagesFromSourceKey = (pages, pagesBySource, sourceKey) => {
-    for (const page of pagesBySource.get(sourceKey) ?? []) {
-        pages.set(page.slug, page);
-    }
-};
-const addReferencedUtilityPages = (pages, pagesByIdentifier, pageReferences, hiddenPages, groupHidden = false) => {
-    for (const pageReference of pageReferences ?? []) {
-        if (groupHidden || hiddenPages.has(pageReference)) {
-            continue;
-        }
-        const page = pagesByIdentifier.get(pageReference);
-        if (page) {
-            pages.set(page.slug, page);
-        }
-    }
-};
-const buildUtilityOpenApiPages = async (config, collection, source) => {
-    if (!collection || collection.type !== "docs") {
-        return [];
-    }
-    const docsNavigation = getDocsNavigation(config);
-    const hiddenPages = new Set(docsNavigation?.hidden);
-    const slugPrefix = normalizePath(collection.slugPrefix ?? "");
-    const byIdentifier = new Map();
-    const bySource = new Map();
-    const pages = new Map();
-    const sources = collectOpenApiSources(collection);
-    const resolved = await Promise.all(sources.map(async (item) => {
-        const rawSpec = await source.readFile(item.source);
-        const spec = parseOpenApiSpec(rawSpec, item.source);
-        const directory = item.directory ?? "api";
-        const { operations } = extractOpenApiOperations(spec, directory);
-        return { directory, operations, source: item };
-    }));
-    for (const { directory, operations, source: openApiSource } of resolved) {
-        collectUtilityOpenApiPages(byIdentifier, bySource, operations, directory, openApiSource, slugPrefix);
-    }
-    for (const openApiSource of ensureArray(collection.openapi)) {
-        if (!openApiSource) {
-            continue;
-        }
-        addUtilityPagesFromSourceKey(pages, bySource, getGroupedOpenApiSourceKey(openApiSource));
-    }
-    for (const group of docsNavigation?.groups ?? []) {
-        const groupHidden = group.hidden === true;
-        addReferencedUtilityPages(pages, byIdentifier, group.pages, hiddenPages, groupHidden);
-        if (groupHidden || !group.openapi) {
-            continue;
-        }
-        addUtilityPagesFromSourceKey(pages, bySource, getGroupedOpenApiSourceKey(group.openapi));
-    }
-    addReferencedUtilityPages(pages, byIdentifier, docsNavigation?.pages, hiddenPages);
-    return [...pages.values()];
-};
-export const buildSearchIndex = (index, config, utilityIndex) => {
-    const pageMetadataMap = buildPageMetadataMap(index);
-    const items = new Map();
-    for (const page of utilityIndex?.pages ?? []) {
-        items.set(page.slug, {
-            path: page.slug,
-            title: page.title,
-        });
-    }
-    for (const entry of index.entries) {
-        if (!shouldIncludeSearchEntry(entry, pageMetadataMap, config)) {
-            continue;
-        }
-        const pageMeta = pageMetadataMap.get(entry.slug);
-        items.set(entry.slug, {
-            href: pageMeta?.url,
-            path: entry.slug,
-            title: pageMeta?.sidebarTitle ?? entry.title,
-        });
-    }
-    return [...items.values()];
-};
-export const buildUtilityIndex = async (index, source, config) => {
-    const pageMetadataMap = buildPageMetadataMap(index);
-    const pages = new Map();
-    for (const entry of index.entries) {
-        if (entry.kind !== "entry") {
-            continue;
-        }
-        if (!shouldIncludeSearchEntry(entry, pageMetadataMap, config)) {
-            continue;
-        }
-        const rawContent = await source.readFile(entry.relativePath);
-        pages.set(entry.slug, {
-            content: stripFrontmatter(rawContent),
-            description: entry.description,
-            slug: entry.slug,
-            title: entry.title,
-        });
-    }
-    for (const page of await buildUtilityOpenApiPages(config, getDocsCollectionWithNavigation(config), source)) {
-        pages.set(page.slug, page);
-    }
-    const sortedPages = [...pages.values()];
-    // oxlint-disable-next-line eslint-plugin-unicorn/no-array-sort
-    sortedPages.sort((left, right) => left.slug.localeCompare(right.slug));
-    return {
-        description: config.description,
-        name: config.name,
-        pages: sortedPages,
-        slug: config.slug,
-    };
-};
-const toUtilityDocPath = (value) => {
-    const clean = normalizePath(value);
-    if (!clean || clean === "index") {
-        return "/";
-    }
-    return `/${clean}`;
-};
-const toUtilityTemplatedDocUrl = (value) => `${UTILITY_DOCS_ROOT_TOKEN}${toUtilityDocPath(value)}`;
-export const getPrebuiltUtilityLlmPagePath = (slug) => {
-    const normalized = normalizePath(slug);
-    return `_utility/llms-pages/${normalized || "index"}.mdx`;
-};
-export const buildUtilityArtifacts = (index) => {
-    const llmsLines = [
-        `# ${index.name}`,
-        index.description ? `> ${index.description}` : null,
-        "",
-        `Sitemap: ${toUtilityTemplatedDocUrl("sitemap.xml")}`,
-        `Skills: ${UTILITY_DOCS_ROOT_TOKEN}/.well-known/skills/index.json`,
-        "",
-        "## Docs",
-        ...index.pages.map((page) => {
-            const description = page.description ? `: ${page.description}` : "";
-            return `- [${page.title}](${toUtilityTemplatedDocUrl(page.slug)})${description}`;
-        }),
-    ];
-    const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${index.pages
-        .map((page) => `  <url><loc>${toUtilityTemplatedDocUrl(page.slug)}</loc></url>`)
-        .join("\n")}
-</urlset>`;
-    const llmsFull = index.pages
-        .map((page) => formatMarkdownPageSection(page.title, toUtilityTemplatedDocUrl(page.slug), page.content))
-        .join("\n\n");
-    const skillSlug = index.slug ?? slugify(index.name);
-    const skillDescription = `${index.name} documentation. ${index.description ?? ""}`.trim();
-    const skillsIndex = JSON.stringify({
-        skills: [
-            {
-                description: skillDescription,
-                files: ["SKILL.md"],
-                name: skillSlug,
-            },
-        ],
-    }, null, 2);
-    const topPages = index.pages.slice(0, 20);
-    const skillMdLines = [
-        "---",
-        `name: ${skillSlug}`,
-        `description: ${skillDescription} Use when working with ${index.name}, answering questions about its features, or helping users follow its guides.`,
-        "---",
-        "",
-        `# ${index.name}`,
-        "",
-        index.description ? `${index.description}\n` : "",
-        "## Documentation",
-        "",
-        `- Full docs index: ${UTILITY_DOCS_ROOT_TOKEN}/llms.txt`,
-        `- Complete docs content: ${UTILITY_DOCS_ROOT_TOKEN}/llms-full.txt`,
-        "- Append `.md` to any page URL for raw markdown",
-        "",
-        "## Key Pages",
-        "",
-        ...topPages.map((page) => {
-            const desc = page.description ? ` - ${page.description}` : "";
-            return `- [${page.title}](${toUtilityTemplatedDocUrl(page.slug)})${desc}`;
-        }),
-    ];
-    return [
-        {
-            content: sitemap,
-            contentType: "application/xml; charset=utf-8",
-            path: PREBUILT_UTILITY_SITEMAP_PATH,
-        },
-        {
-            content: llmsLines.filter((line) => line !== null).join("\n"),
-            contentType: "text/plain; charset=utf-8",
-            path: PREBUILT_UTILITY_LLMS_PATH,
-        },
-        {
-            content: llmsFull,
-            contentType: "text/plain; charset=utf-8",
-            path: PREBUILT_UTILITY_LLMS_FULL_PATH,
-        },
-        {
-            content: skillsIndex,
-            contentType: "application/json; charset=utf-8",
-            path: PREBUILT_UTILITY_SKILLS_INDEX_PATH,
-        },
-        {
-            content: skillMdLines.filter((line) => line !== null).join("\n"),
-            contentType: "text/markdown; charset=utf-8",
-            path: `${PREBUILT_UTILITY_SKILLS_MD_PREFIX}${skillSlug}/SKILL.md`,
-        },
-        ...index.pages.map((page) => ({
-            content: formatMarkdownPage(page.title, page.content),
-            contentType: "text/markdown; charset=utf-8",
-            path: getPrebuiltUtilityLlmPagePath(page.slug),
-        })),
-    ];
-};
-export const buildTocIndex = async (index, source) => {
-    const itemsBySlug = new Map();
-    for (const entry of index.entries) {
-        if (entry.kind !== "entry") {
-            continue;
-        }
-        const rawContent = await source.readFile(entry.relativePath);
-        itemsBySlug.set(entry.slug, extractToc(rawContent));
-    }
-    return itemsBySlug;
-};
-export const serializeContentIndex = (index) => JSON.stringify({
-    collections: Object.fromEntries(index.byCollection),
-    entries: index.entries,
-    version: 1,
-});
-export const serializeOpenApiIndex = (entries) => JSON.stringify({
-    entries,
-    version: 1,
-});
-export const loadPrebuiltContentIndex = async (source) => {
-    try {
-        const raw = await source.readFile(PREBUILT_INDEX_PATH);
-        const data = JSON.parse(raw);
-        if (data.version !== 1 || !Array.isArray(data.entries)) {
-            return null;
-        }
-        const bySlug = new Map();
-        const byCollection = new Map();
-        for (const entry of data.entries) {
-            bySlug.set(entry.slug, entry);
-        }
-        for (const [collectionId, entries] of Object.entries(data.collections ?? {})) {
-            byCollection.set(collectionId, entries);
-        }
-        return {
-            byCollection,
-            bySlug,
-            entries: data.entries,
-            errors: [],
-        };
-    }
-    catch {
-        return null;
-    }
-};
-export const loadPrebuiltOpenApiIndex = async (source) => {
-    try {
-        const raw = await source.readFile(PREBUILT_OPENAPI_INDEX_PATH);
-        const data = JSON.parse(raw);
-        if (data.version !== 1 || !Array.isArray(data.entries)) {
-            return null;
-        }
-        return data.entries;
-    }
-    catch {
-        return null;
-    }
-};
-export const serializeSearchIndex = (items) => JSON.stringify({
-    items,
-    version: 1,
-});
-export const loadPrebuiltSearchIndex = async (source) => {
-    try {
-        const raw = await source.readFile(PREBUILT_SEARCH_INDEX_PATH);
-        const data = JSON.parse(raw);
-        if (data.version !== 1 || !Array.isArray(data.items)) {
-            return null;
-        }
-        return data.items;
-    }
-    catch {
-        return null;
-    }
-};
-export const serializeTocIndex = (itemsBySlug) => JSON.stringify({
-    itemsBySlug: Object.fromEntries(itemsBySlug),
-    version: 1,
-});
-export const loadPrebuiltTocIndex = async (source) => {
-    try {
-        const raw = await source.readFile(PREBUILT_TOC_INDEX_PATH);
-        const data = JSON.parse(raw);
-        if (data.version !== 1 || typeof data.itemsBySlug !== "object") {
-            return null;
-        }
-        return new Map(Object.entries(data.itemsBySlug ?? {}));
-    }
-    catch {
-        return null;
-    }
-};
-export const serializeUtilityIndex = (index) => JSON.stringify({
-    ...index,
-    version: 1,
-});
-export const loadPrebuiltUtilityIndex = async (source) => {
-    try {
-        const raw = await source.readFile(PREBUILT_UTILITY_INDEX_PATH);
-        const data = JSON.parse(raw);
-        if (data.version !== 1 ||
-            typeof data.name !== "string" ||
-            !Array.isArray(data.pages)) {
-            return null;
-        }
-        return {
-            description: data.description,
-            name: data.name,
-            pages: data.pages,
-        };
-    }
-    catch {
-        return null;
-    }
-};
+export { prepareLlmsFullContent, toAgentMarkdown, } from "./markdown/agent-markdown.js";
+export { formatMarkdownPage, formatMarkdownPageSection, stripFrontmatter, } from "./markdown/format.js";
+export { absolutiseInternalLinks, sanitizePlaceholderUrls, } from "./markdown/links.js";
+export { formatOpenApiPageContent } from "./openapi-pages.js";
+export { buildSearchIndex } from "./search-index.js";
+export { loadPrebuiltContentIndex, loadPrebuiltOpenApiIndex, loadPrebuiltSearchIndex, loadPrebuiltTocIndex, loadPrebuiltUtilityIndex, serializeContentIndex, serializeOpenApiIndex, serializeSearchIndex, serializeTocIndex, serializeUtilityIndex, } from "./serialization.js";
+export { buildTocIndex, extractToc } from "./toc-index.js";
+export { buildUtilityArtifacts, buildUtilityIndex, getPrebuiltUtilityLlmPagePath, } from "./utility-index.js";