@blaaiz/docs-core 0.1.0

package/dist/generator.d.cts

@@ -0,0 +1,122 @@
+import { O as OpenApiInfo, a as OpenApiServer, b as OpenApiDocument } from './openapi-types-CJ6p5Cux.cjs';
+
+/**
+ * `@blaaiz/docs-core/generator` — builds the docs content tree from `docs.json`.
+ *
+ * One call turns the site's navigation file into everything fumadocs needs:
+ * generated API pages placed in their configured groups, and `meta.json` files
+ * encoding tab and group order. Authors reorganize the docs by editing
+ * `docs.json` — never by moving files.
+ *
+ * Node-only. A site that publishes an API reference injects `createOpenAPI` and
+ * `generateFiles` from its own `fumadocs-openapi` install, so this package takes
+ * no dependency on it. A site of prose alone injects nothing: with no API pages
+ * in `docs.json` the generator writes the `meta.json` files and `nav.json` and
+ * never touches `fumadocs-openapi`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The two fumadocs-openapi functions the generator needs, injected by the site
+ * (`createOpenAPI` from `fumadocs-openapi/server`, `generateFiles` from
+ * `fumadocs-openapi`). Typed loosely so this package needs no fumadocs types.
+ *
+ * @public
+ */
+interface FumadocsOpenApi {
+    readonly createOpenAPI: (...args: never[]) => unknown;
+    readonly generateFiles: (...args: never[]) => unknown;
+}
+/**
+ * Options for {@link generateDocsTree}.
+ *
+ * @public
+ */
+interface GenerateDocsTreeOptions {
+    /** The site's content directory (holds `docs.json`, spec files, and `docs/`). */
+    readonly contentDir: string;
+    /** Path to the navigation file. Default `<contentDir>/docs.json`. */
+    readonly docsJson?: string;
+    /** Output directory for the page tree. Default `<contentDir>/docs`. */
+    readonly outDir?: string;
+    /** Folder for generated API pages. Default `api`. */
+    readonly apiDir?: string;
+    /**
+     * `info` block of the merged OpenAPI document. Required when `docs.json`
+     * publishes API pages; ignored on a site of prose alone, which merges no
+     * documents.
+     */
+    readonly info?: OpenApiInfo;
+    /** Servers of the merged document. */
+    readonly servers?: readonly OpenApiServer[];
+    /** Same-origin proxy route for the try-it playground. */
+    readonly proxyUrl?: string;
+    /** URL base the fumadocs loader serves pages under. Default `/docs`. */
+    readonly baseUrl?: string;
+    /**
+     * The site's fumadocs-openapi functions. Required when `docs.json` publishes
+     * API pages; omit it on a site of prose alone.
+     */
+    readonly fumadocs?: FumadocsOpenApi;
+}
+/**
+ * A top-navigation link: one tab, pointing at its first page.
+ *
+ * @public
+ */
+interface NavLink {
+    readonly text: string;
+    readonly url: string;
+    /** The tab's icon name from `docs.json`, for the site to resolve. */
+    readonly icon?: string;
+}
+/**
+ * What the generator produced.
+ *
+ * @public
+ */
+interface GenerateDocsTreeResult {
+    readonly pages: number;
+    readonly metas: number;
+    /**
+     * Top-nav links, one per tab, each pointing at the tab's first page — written
+     * to `<contentDir>/nav.json` for the site's layout. Keeps the top nav in sync
+     * with `docs.json` instead of a hand-maintained list.
+     */
+    readonly navLinks: readonly NavLink[];
+    /**
+     * Page URL to HTTP method, written to `<contentDir>/api-methods.json` for the
+     * sidebar method badges (`apiMethodBadges` in `@blaaiz/docs-core/ui`).
+     */
+    readonly methodsByUrl: Readonly<Record<string, string>>;
+    /** The merged OpenAPI document (reusable for the runtime page renderer). */
+    readonly document: OpenApiDocument;
+}
+/**
+ * Build the docs content tree from `docs.json`.
+ *
+ * Reads the navigation, merges every referenced spec, generates one page per
+ * declared endpoint into its configured group folder, and writes the
+ * `meta.json` files that give the sidebar the navigation's exact structure and
+ * order. Operations present in a spec but not declared in `docs.json` get no
+ * page — the navigation decides what is published, as on Mintlify.
+ *
+ * A site of prose alone needs neither option: with no API pages in `docs.json`
+ * the run writes the `meta.json` files, `nav.json`, and an empty
+ * `api-methods.json`, and never loads `fumadocs-openapi`.
+ *
+ * @example
+ * ```ts
+ * // A site of prose alone.
+ * await generateDocsTree({ contentDir: 'content' });
+ * ```
+ *
+ * @param options - directories, document info, and the injected fumadocs functions
+ * @returns counts and the merged document
+ * @throws when `docs.json` publishes API pages and `fumadocs` or `info` is missing
+ * @public
+ */
+declare function generateDocsTree(options: GenerateDocsTreeOptions): Promise<GenerateDocsTreeResult>;
+
+export { type FumadocsOpenApi, type GenerateDocsTreeOptions, type GenerateDocsTreeResult, type NavLink, generateDocsTree };

package/dist/generator.d.ts

@@ -0,0 +1,122 @@
+import { O as OpenApiInfo, a as OpenApiServer, b as OpenApiDocument } from './openapi-types-CJ6p5Cux.js';
+
+/**
+ * `@blaaiz/docs-core/generator` — builds the docs content tree from `docs.json`.
+ *
+ * One call turns the site's navigation file into everything fumadocs needs:
+ * generated API pages placed in their configured groups, and `meta.json` files
+ * encoding tab and group order. Authors reorganize the docs by editing
+ * `docs.json` — never by moving files.
+ *
+ * Node-only. A site that publishes an API reference injects `createOpenAPI` and
+ * `generateFiles` from its own `fumadocs-openapi` install, so this package takes
+ * no dependency on it. A site of prose alone injects nothing: with no API pages
+ * in `docs.json` the generator writes the `meta.json` files and `nav.json` and
+ * never touches `fumadocs-openapi`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The two fumadocs-openapi functions the generator needs, injected by the site
+ * (`createOpenAPI` from `fumadocs-openapi/server`, `generateFiles` from
+ * `fumadocs-openapi`). Typed loosely so this package needs no fumadocs types.
+ *
+ * @public
+ */
+interface FumadocsOpenApi {
+    readonly createOpenAPI: (...args: never[]) => unknown;
+    readonly generateFiles: (...args: never[]) => unknown;
+}
+/**
+ * Options for {@link generateDocsTree}.
+ *
+ * @public
+ */
+interface GenerateDocsTreeOptions {
+    /** The site's content directory (holds `docs.json`, spec files, and `docs/`). */
+    readonly contentDir: string;
+    /** Path to the navigation file. Default `<contentDir>/docs.json`. */
+    readonly docsJson?: string;
+    /** Output directory for the page tree. Default `<contentDir>/docs`. */
+    readonly outDir?: string;
+    /** Folder for generated API pages. Default `api`. */
+    readonly apiDir?: string;
+    /**
+     * `info` block of the merged OpenAPI document. Required when `docs.json`
+     * publishes API pages; ignored on a site of prose alone, which merges no
+     * documents.
+     */
+    readonly info?: OpenApiInfo;
+    /** Servers of the merged document. */
+    readonly servers?: readonly OpenApiServer[];
+    /** Same-origin proxy route for the try-it playground. */
+    readonly proxyUrl?: string;
+    /** URL base the fumadocs loader serves pages under. Default `/docs`. */
+    readonly baseUrl?: string;
+    /**
+     * The site's fumadocs-openapi functions. Required when `docs.json` publishes
+     * API pages; omit it on a site of prose alone.
+     */
+    readonly fumadocs?: FumadocsOpenApi;
+}
+/**
+ * A top-navigation link: one tab, pointing at its first page.
+ *
+ * @public
+ */
+interface NavLink {
+    readonly text: string;
+    readonly url: string;
+    /** The tab's icon name from `docs.json`, for the site to resolve. */
+    readonly icon?: string;
+}
+/**
+ * What the generator produced.
+ *
+ * @public
+ */
+interface GenerateDocsTreeResult {
+    readonly pages: number;
+    readonly metas: number;
+    /**
+     * Top-nav links, one per tab, each pointing at the tab's first page — written
+     * to `<contentDir>/nav.json` for the site's layout. Keeps the top nav in sync
+     * with `docs.json` instead of a hand-maintained list.
+     */
+    readonly navLinks: readonly NavLink[];
+    /**
+     * Page URL to HTTP method, written to `<contentDir>/api-methods.json` for the
+     * sidebar method badges (`apiMethodBadges` in `@blaaiz/docs-core/ui`).
+     */
+    readonly methodsByUrl: Readonly<Record<string, string>>;
+    /** The merged OpenAPI document (reusable for the runtime page renderer). */
+    readonly document: OpenApiDocument;
+}
+/**
+ * Build the docs content tree from `docs.json`.
+ *
+ * Reads the navigation, merges every referenced spec, generates one page per
+ * declared endpoint into its configured group folder, and writes the
+ * `meta.json` files that give the sidebar the navigation's exact structure and
+ * order. Operations present in a spec but not declared in `docs.json` get no
+ * page — the navigation decides what is published, as on Mintlify.
+ *
+ * A site of prose alone needs neither option: with no API pages in `docs.json`
+ * the run writes the `meta.json` files, `nav.json`, and an empty
+ * `api-methods.json`, and never loads `fumadocs-openapi`.
+ *
+ * @example
+ * ```ts
+ * // A site of prose alone.
+ * await generateDocsTree({ contentDir: 'content' });
+ * ```
+ *
+ * @param options - directories, document info, and the injected fumadocs functions
+ * @returns counts and the merged document
+ * @throws when `docs.json` publishes API pages and `fumadocs` or `info` is missing
+ * @public
+ */
+declare function generateDocsTree(options: GenerateDocsTreeOptions): Promise<GenerateDocsTreeResult>;
+
+export { type FumadocsOpenApi, type GenerateDocsTreeOptions, type GenerateDocsTreeResult, type NavLink, generateDocsTree };

package/dist/generator.js

@@ -0,0 +1,177 @@
+import { parseNavigation, planDocsTree, mergeOpenApiDocuments } from './chunk-3ZX4WIE3.js';
+import { readFile, rm, mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function operationKeyOf(content) {
+  const match = /operations=\{(\[[\s\S]*?\])\}/.exec(content);
+  if (!match?.[1]) {
+    return null;
+  }
+  try {
+    const ops = JSON.parse(match[1]);
+    const op = ops[0];
+    return op ? `${op.method.toUpperCase()} ${op.path}` : null;
+  } catch {
+    return null;
+  }
+}
+var PROSE_ONLY_INFO = { title: "No API reference", version: "0.0.0" };
+function requireFumadocs(value, apiPageCount) {
+  const because = `docs.json publishes ${String(apiPageCount)} API page(s)`;
+  if (typeof value !== "object" || value === null) {
+    throw new Error(
+      `[docs-core] generateDocsTree: the 'fumadocs' option is required because ${because}. Pass { createOpenAPI, generateFiles } from the site's fumadocs-openapi install.`
+    );
+  }
+  const candidate = value;
+  for (const name of ["createOpenAPI", "generateFiles"]) {
+    if (typeof candidate[name] !== "function") {
+      throw new Error(
+        `[docs-core] generateDocsTree: fumadocs.${name} must be a function because ${because}. Import ${name} from ${name === "createOpenAPI" ? "'fumadocs-openapi/server'" : "'fumadocs-openapi'"}.`
+      );
+    }
+  }
+  return value;
+}
+async function generateDocsTree(options) {
+  const docsJson = options.docsJson ?? path.join(options.contentDir, "docs.json");
+  const outDir = options.outDir ?? path.join(options.contentDir, "docs");
+  const apiDir = options.apiDir ?? "api";
+  const navigation = parseNavigation(JSON.parse(await readFile(docsJson, "utf8")));
+  const plan = planDocsTree(navigation, { apiDir });
+  const placements = /* @__PURE__ */ new Map();
+  const groupPages = /* @__PURE__ */ new Map();
+  let pages = 0;
+  let document;
+  if (plan.apiPages.length === 0) {
+    document = mergeOpenApiDocuments([], { info: options.info ?? PROSE_ONLY_INFO });
+  } else {
+    const fumadocs = requireFumadocs(options.fumadocs, plan.apiPages.length);
+    if (options.info === void 0) {
+      throw new Error(
+        `[docs-core] generateDocsTree: the 'info' option is required because docs.json publishes ${String(plan.apiPages.length)} API page(s). Pass { title, version } for the merged OpenAPI document.`
+      );
+    }
+    const docs = await Promise.all(
+      plan.specs.map(
+        async (file) => JSON.parse(await readFile(path.join(options.contentDir, file), "utf8"))
+      )
+    );
+    document = mergeOpenApiDocuments(docs, {
+      info: options.info,
+      ...options.servers ? { servers: options.servers } : {}
+    });
+    for (const page of plan.apiPages) {
+      const operation = document.paths[page.apiPath]?.[page.method.toLowerCase()];
+      if (!operation) {
+        throw new Error(
+          `[docs-core] docs.json references ${page.method} ${page.apiPath}, but ${page.file} defines no such operation.`
+        );
+      }
+      const slug = operation.operationId ?? slugify(`${page.method} ${page.apiPath}`);
+      placements.set(`${page.method.toUpperCase()} ${page.apiPath}`, { ...page, slug });
+      const group = groupPages.get(page.dir) ?? [];
+      group.push({ order: page.order, slug });
+      groupPages.set(page.dir, group);
+    }
+    await rm(path.join(outDir, apiDir), { recursive: true, force: true });
+    const createOpenAPI = fumadocs.createOpenAPI;
+    const generateFiles = fumadocs.generateFiles;
+    await generateFiles({
+      input: createOpenAPI({
+        input: { blaaiz: document },
+        ...options.proxyUrl ? { proxyUrl: options.proxyUrl } : {}
+      }),
+      output: outDir,
+      per: "operation",
+      groupBy: "none",
+      beforeWrite(files) {
+        for (let i = files.length - 1; i >= 0; i -= 1) {
+          const file = files[i];
+          if (!file) {
+            continue;
+          }
+          const key = operationKeyOf(file.content);
+          const placement = key ? placements.get(key) : void 0;
+          if (!placement) {
+            files.splice(i, 1);
+            continue;
+          }
+          file.path = path.join(placement.dir, `${placement.slug}.mdx`);
+          pages += 1;
+        }
+      }
+    });
+  }
+  const metas = [
+    ...plan.metas,
+    ...plan.apiGroups.map((group) => ({
+      path: `${group.dir}/meta.json`,
+      content: {
+        title: group.title,
+        pages: (groupPages.get(group.dir) ?? []).sort((a, b) => a.order - b.order).map((page) => page.slug)
+      }
+    }))
+  ];
+  for (const meta of metas) {
+    const target = path.join(outDir, meta.path);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(meta.content, null, 2)}
+`);
+  }
+  const baseUrl = (options.baseUrl ?? "/docs").replace(/\/$/, "");
+  const docUrl = (file) => {
+    const clean = file.replace(/\/?index$/, "");
+    return clean ? `${baseUrl}/${clean}` : baseUrl;
+  };
+  const firstUrl = (items) => {
+    for (const item of items) {
+      if (item.kind === "group") {
+        const url = firstUrl(item.items);
+        if (url) {
+          return url;
+        }
+      } else if (item.kind === "doc") {
+        return docUrl(item.file);
+      } else {
+        const placement = placements.get(`${item.method.toUpperCase()} ${item.apiPath}`);
+        if (placement) {
+          return `${baseUrl}/${placement.dir}/${placement.slug}`;
+        }
+      }
+    }
+    return void 0;
+  };
+  const navLinks = [];
+  for (const tab of navigation) {
+    const url = firstUrl(tab.items);
+    if (url) {
+      navLinks.push({ text: tab.title, url, ...tab.icon ? { icon: tab.icon } : {} });
+    }
+  }
+  await writeFile(
+    path.join(options.contentDir, "nav.json"),
+    `${JSON.stringify(navLinks, null, 2)}
+`
+  );
+  const methodsByUrl = {};
+  for (const page of plan.apiPages) {
+    const placement = placements.get(`${page.method.toUpperCase()} ${page.apiPath}`);
+    if (placement) {
+      methodsByUrl[`${baseUrl}/${placement.dir}/${placement.slug}`] = page.method.toUpperCase();
+    }
+  }
+  await writeFile(
+    path.join(options.contentDir, "api-methods.json"),
+    `${JSON.stringify(methodsByUrl, null, 2)}
+`
+  );
+  return { pages, metas: metas.length, navLinks, methodsByUrl, document };
+}
+
+export { generateDocsTree };
+//# sourceMappingURL=generator.js.map
+//# sourceMappingURL=generator.js.map

package/dist/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/generator/index.ts"],"names":[],"mappings":"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","file":"generator.js","sourcesContent":["/**\n * `@blaaiz/docs-core/generator` — builds the docs content tree from `docs.json`.\n *\n * One call turns the site's navigation file into everything fumadocs needs:\n * generated API pages placed in their configured groups, and `meta.json` files\n * encoding tab and group order. Authors reorganize the docs by editing\n * `docs.json` — never by moving files.\n *\n * Node-only. A site that publishes an API reference injects `createOpenAPI` and\n * `generateFiles` from its own `fumadocs-openapi` install, so this package takes\n * no dependency on it. A site of prose alone injects nothing: with no API pages\n * in `docs.json` the generator writes the `meta.json` files and `nav.json` and\n * never touches `fumadocs-openapi`.\n *\n * @packageDocumentation\n */\n\nimport { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { mergeOpenApiDocuments } from '../adapters/index.js';\nimport { parseNavigation } from '../adapters/index.js';\nimport type { NavItem, OpenApiDocument, OpenApiInfo, OpenApiServer } from '../core/index.js';\nimport { planDocsTree } from '../core/index.js';\n\n/**\n * The two fumadocs-openapi functions the generator needs, injected by the site\n * (`createOpenAPI` from `fumadocs-openapi/server`, `generateFiles` from\n * `fumadocs-openapi`). Typed loosely so this package needs no fumadocs types.\n *\n * @public\n */\nexport interface FumadocsOpenApi {\n  readonly createOpenAPI: (...args: never[]) => unknown;\n  readonly generateFiles: (...args: never[]) => unknown;\n}\n\n/**\n * Options for {@link generateDocsTree}.\n *\n * @public\n */\nexport interface GenerateDocsTreeOptions {\n  /** The site's content directory (holds `docs.json`, spec files, and `docs/`). */\n  readonly contentDir: string;\n  /** Path to the navigation file. Default `<contentDir>/docs.json`. */\n  readonly docsJson?: string;\n  /** Output directory for the page tree. Default `<contentDir>/docs`. */\n  readonly outDir?: string;\n  /** Folder for generated API pages. Default `api`. */\n  readonly apiDir?: string;\n  /**\n   * `info` block of the merged OpenAPI document. Required when `docs.json`\n   * publishes API pages; ignored on a site of prose alone, which merges no\n   * documents.\n   */\n  readonly info?: OpenApiInfo;\n  /** Servers of the merged document. */\n  readonly servers?: readonly OpenApiServer[];\n  /** Same-origin proxy route for the try-it playground. */\n  readonly proxyUrl?: string;\n  /** URL base the fumadocs loader serves pages under. Default `/docs`. */\n  readonly baseUrl?: string;\n  /**\n   * The site's fumadocs-openapi functions. Required when `docs.json` publishes\n   * API pages; omit it on a site of prose alone.\n   */\n  readonly fumadocs?: FumadocsOpenApi;\n}\n\n/**\n * A top-navigation link: one tab, pointing at its first page.\n *\n * @public\n */\nexport interface NavLink {\n  readonly text: string;\n  readonly url: string;\n  /** The tab's icon name from `docs.json`, for the site to resolve. */\n  readonly icon?: string;\n}\n\n/**\n * What the generator produced.\n *\n * @public\n */\nexport interface GenerateDocsTreeResult {\n  readonly pages: number;\n  readonly metas: number;\n  /**\n   * Top-nav links, one per tab, each pointing at the tab's first page — written\n   * to `<contentDir>/nav.json` for the site's layout. Keeps the top nav in sync\n   * with `docs.json` instead of a hand-maintained list.\n   */\n  readonly navLinks: readonly NavLink[];\n  /**\n   * Page URL to HTTP method, written to `<contentDir>/api-methods.json` for the\n   * sidebar method badges (`apiMethodBadges` in `@blaaiz/docs-core/ui`).\n   */\n  readonly methodsByUrl: Readonly<Record<string, string>>;\n  /** The merged OpenAPI document (reusable for the runtime page renderer). */\n  readonly document: OpenApiDocument;\n}\n\ninterface GeneratedFile {\n  path: string;\n  content: string;\n}\n\nfunction slugify(value: string): string {\n  return value\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '');\n}\n\n/** The `METHOD path` key of the first operation a generated page renders. */\nfunction operationKeyOf(content: string): string | null {\n  const match = /operations=\\{(\\[[\\s\\S]*?\\])\\}/.exec(content);\n  if (!match?.[1]) {\n    return null;\n  }\n  try {\n    const ops = JSON.parse(match[1]) as { path: string; method: string }[];\n    const op = ops[0];\n    return op ? `${op.method.toUpperCase()} ${op.path}` : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * The `info` a docs-only run reports on its (empty) merged document. Nothing\n * renders it: with no API pages there is no reference view to title.\n */\nconst PROSE_ONLY_INFO: OpenApiInfo = { title: 'No API reference', version: '0.0.0' };\n\n/**\n * The fumadocs functions, checked. Called only when the navigation publishes\n * API pages, so the message can name the exact reason they are needed.\n */\nfunction requireFumadocs(value: unknown, apiPageCount: number): FumadocsOpenApi {\n  const because = `docs.json publishes ${String(apiPageCount)} API page(s)`;\n  if (typeof value !== 'object' || value === null) {\n    throw new Error(\n      `[docs-core] generateDocsTree: the 'fumadocs' option is required because ${because}. ` +\n        \"Pass { createOpenAPI, generateFiles } from the site's fumadocs-openapi install.\",\n    );\n  }\n  const candidate = value as Record<string, unknown>;\n  for (const name of ['createOpenAPI', 'generateFiles'] as const) {\n    if (typeof candidate[name] !== 'function') {\n      throw new Error(\n        `[docs-core] generateDocsTree: fumadocs.${name} must be a function because ${because}. ` +\n          `Import ${name} from ${name === 'createOpenAPI' ? \"'fumadocs-openapi/server'\" : \"'fumadocs-openapi'\"}.`,\n      );\n    }\n  }\n  return value as FumadocsOpenApi;\n}\n\n/**\n * Build the docs content tree from `docs.json`.\n *\n * Reads the navigation, merges every referenced spec, generates one page per\n * declared endpoint into its configured group folder, and writes the\n * `meta.json` files that give the sidebar the navigation's exact structure and\n * order. Operations present in a spec but not declared in `docs.json` get no\n * page — the navigation decides what is published, as on Mintlify.\n *\n * A site of prose alone needs neither option: with no API pages in `docs.json`\n * the run writes the `meta.json` files, `nav.json`, and an empty\n * `api-methods.json`, and never loads `fumadocs-openapi`.\n *\n * @example\n * ```ts\n * // A site of prose alone.\n * await generateDocsTree({ contentDir: 'content' });\n * ```\n *\n * @param options - directories, document info, and the injected fumadocs functions\n * @returns counts and the merged document\n * @throws when `docs.json` publishes API pages and `fumadocs` or `info` is missing\n * @public\n */\nexport async function generateDocsTree(\n  options: GenerateDocsTreeOptions,\n): Promise<GenerateDocsTreeResult> {\n  const docsJson = options.docsJson ?? path.join(options.contentDir, 'docs.json');\n  const outDir = options.outDir ?? path.join(options.contentDir, 'docs');\n  const apiDir = options.apiDir ?? 'api';\n\n  const navigation = parseNavigation(JSON.parse(await readFile(docsJson, 'utf8')));\n  const plan = planDocsTree(navigation, { apiDir });\n\n  // Where each planned API page lands. Both stay empty on a prose-only site.\n  const placements = new Map<string, { dir: string; order: number; slug: string }>();\n  const groupPages = new Map<string, { order: number; slug: string }[]>();\n  let pages = 0;\n  let document: OpenApiDocument;\n\n  if (plan.apiPages.length === 0) {\n    // A site of prose alone. Nothing to merge, nothing to generate, and — most\n    // importantly — nothing removed: a hand-written folder named `api` is the\n    // site's own content, not our output.\n    document = mergeOpenApiDocuments([], { info: options.info ?? PROSE_ONLY_INFO });\n  } else {\n    const fumadocs = requireFumadocs(options.fumadocs, plan.apiPages.length);\n    if (options.info === undefined) {\n      throw new Error(\n        `[docs-core] generateDocsTree: the 'info' option is required because docs.json ` +\n          `publishes ${String(plan.apiPages.length)} API page(s). ` +\n          'Pass { title, version } for the merged OpenAPI document.',\n      );\n    }\n\n    // Merge exactly the specs the navigation references.\n    const docs = await Promise.all(\n      plan.specs.map(\n        async (file) =>\n          JSON.parse(await readFile(path.join(options.contentDir, file), 'utf8')) as unknown,\n      ),\n    );\n    document = mergeOpenApiDocuments(docs, {\n      info: options.info,\n      ...(options.servers ? { servers: options.servers } : {}),\n    });\n\n    // Resolve each planned page's slug from the merged document.\n    for (const page of plan.apiPages) {\n      const operation = document.paths[page.apiPath]?.[page.method.toLowerCase()] as\n        { operationId?: string } | undefined;\n      if (!operation) {\n        throw new Error(\n          `[docs-core] docs.json references ${page.method} ${page.apiPath}, ` +\n            `but ${page.file} defines no such operation.`,\n        );\n      }\n      const slug = operation.operationId ?? slugify(`${page.method} ${page.apiPath}`);\n      placements.set(`${page.method.toUpperCase()} ${page.apiPath}`, { ...page, slug });\n      const group = groupPages.get(page.dir) ?? [];\n      group.push({ order: page.order, slug });\n      groupPages.set(page.dir, group);\n    }\n\n    // Fresh API tree, then generate pages and route each into its planned folder.\n    await rm(path.join(outDir, apiDir), { recursive: true, force: true });\n    const createOpenAPI = fumadocs.createOpenAPI as (input: unknown) => unknown;\n    const generateFiles = fumadocs.generateFiles as (input: unknown) => Promise<void>;\n    await generateFiles({\n      input: createOpenAPI({\n        input: { blaaiz: document },\n        ...(options.proxyUrl ? { proxyUrl: options.proxyUrl } : {}),\n      }),\n      output: outDir,\n      per: 'operation',\n      groupBy: 'none',\n      beforeWrite(files: GeneratedFile[]) {\n        for (let i = files.length - 1; i >= 0; i -= 1) {\n          const file = files[i];\n          if (!file) {\n            continue;\n          }\n          const key = operationKeyOf(file.content);\n          const placement = key ? placements.get(key) : undefined;\n          if (!placement) {\n            files.splice(i, 1); // not declared in docs.json -> not published\n            continue;\n          }\n          file.path = path.join(placement.dir, `${placement.slug}.mdx`);\n          pages += 1;\n        }\n      },\n    });\n  }\n\n  // Meta files: the plan's static ones, plus page order for each API group.\n  const metas = [\n    ...plan.metas,\n    ...plan.apiGroups.map((group) => ({\n      path: `${group.dir}/meta.json`,\n      content: {\n        title: group.title,\n        pages: (groupPages.get(group.dir) ?? [])\n          .sort((a, b) => a.order - b.order)\n          .map((page) => page.slug),\n      },\n    })),\n  ];\n  for (const meta of metas) {\n    const target = path.join(outDir, meta.path);\n    await mkdir(path.dirname(target), { recursive: true });\n    await writeFile(target, `${JSON.stringify(meta.content, null, 2)}\\n`);\n  }\n\n  // Top-nav links: each tab points at its first page. The URL of an API page\n  // needs its resolved slug, which is why this runs here, not in the planner.\n  const baseUrl = (options.baseUrl ?? '/docs').replace(/\\/$/, '');\n  const docUrl = (file: string): string => {\n    const clean = file.replace(/\\/?index$/, '');\n    return clean ? `${baseUrl}/${clean}` : baseUrl;\n  };\n  const firstUrl = (items: readonly NavItem[]): string | undefined => {\n    for (const item of items) {\n      if (item.kind === 'group') {\n        const url = firstUrl(item.items);\n        if (url) {\n          return url;\n        }\n      } else if (item.kind === 'doc') {\n        return docUrl(item.file);\n      } else {\n        const placement = placements.get(`${item.method.toUpperCase()} ${item.apiPath}`);\n        if (placement) {\n          return `${baseUrl}/${placement.dir}/${placement.slug}`;\n        }\n      }\n    }\n    return undefined;\n  };\n  const navLinks: NavLink[] = [];\n  for (const tab of navigation) {\n    const url = firstUrl(tab.items);\n    if (url) {\n      navLinks.push({ text: tab.title, url, ...(tab.icon ? { icon: tab.icon } : {}) });\n    }\n  }\n  await writeFile(\n    path.join(options.contentDir, 'nav.json'),\n    `${JSON.stringify(navLinks, null, 2)}\\n`,\n  );\n\n  // Page URL -> HTTP method, for the sidebar method badges.\n  const methodsByUrl: Record<string, string> = {};\n  for (const page of plan.apiPages) {\n    const placement = placements.get(`${page.method.toUpperCase()} ${page.apiPath}`);\n    if (placement) {\n      methodsByUrl[`${baseUrl}/${placement.dir}/${placement.slug}`] = page.method.toUpperCase();\n    }\n  }\n  await writeFile(\n    path.join(options.contentDir, 'api-methods.json'),\n    `${JSON.stringify(methodsByUrl, null, 2)}\\n`,\n  );\n\n  return { pages, metas: metas.length, navLinks, methodsByUrl, document };\n}\n"]}