@writedocs/generator 0.9.3 → 0.10.0

package/src/lib/hidden-sections.js

@@ -0,0 +1,58 @@
+// Hidden navigation items (`"hidden": true` on a tab, product, version,
+// language or dropdown): reachable only by their address.
+//
+// - Nothing lists one: its switcher, tab row or menu option is left out
+//   everywhere, and `/` never redirects into it (firstSlugAmong() in
+//   lib/config.ts skips it).
+// - Inside one, the level it sits on isn't shown - that switcher would
+//   list the other items at its level. Everything below it works as
+//   usual. (buildSelectors() marks that level `hidden`; the placement in
+//   lib/selector-placement.js leaves it out.)
+// - Its pages are a search space of their own: they search only among
+//   themselves, and the site's public search never finds them. With
+//   `"searchPublic": true` its search finds the public pages too. The
+//   build writes one index per space (cli/run-pagefind.js); a page names
+//   its space in the markup, and src/scripts/search.ts loads that index.
+//
+// Hidden isn't private: anyone with the address can read the pages. The
+// sitemap, llms.txt and the MCP index still list them unless a page sets
+// `noindex`.
+
+/** Whether a navigation item is hidden. */
+export function isHidden(item) {
+  return Boolean(item && typeof item === 'object' && item.hidden === true);
+}
+
+const NAME_FIELD = { tab: 'tab', version: 'version', language: 'language', dropdown: 'dropdown', product: 'product' };
+
+function slug(text) {
+  return String(text ?? '')
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/** A path's id, from the names of its levels - "product-admin",
+ *  "tab-api--version-v2". Readable in the index folder's name, and the
+ *  same on every build. */
+export function spaceIdOf(path) {
+  return path
+    .map((segment) => {
+      const item = segment.items[segment.index] ?? {};
+      return `${segment.kind}-${slug(item[NAME_FIELD[segment.kind]]) || segment.index}`;
+    })
+    .join('--');
+}
+
+/** The search space a section belongs to: the innermost hidden item on its
+ *  path - `{ id, searchPublic }` - or null for the public pages. */
+export function spaceOf(path = []) {
+  let space = null;
+  path.forEach((segment, i) => {
+    const item = segment.items[segment.index];
+    if (isHidden(item)) space = { id: spaceIdOf(path.slice(0, i + 1)), searchPublic: item.searchPublic === true };
+  });
+  return space;
+}

package/src/lib/json-schema-descriptions.js

@@ -43,9 +43,15 @@ const CONTAINERS = {
   },
 };
 
+const HIDDEN = {
+  hidden: 'Reachable only by its address: no tab, switcher or menu lists it, and inside it this level isn\'t shown. Its pages search only among themselves.',
+  searchPublic: 'For a hidden item: its search also finds the site\'s public pages.',
+};
+
 const containerEntries = Object.entries(CONTAINERS).flatMap(([type, fields]) => [
   ...Object.entries(fields).map(([field, text]) => [`${type}.${field}`, text]),
   ...Object.entries(CHILDREN).map(([field, text]) => [`${type}.${field}`, text]),
+  ...Object.entries(HIDDEN).map(([field, text]) => [`${type}.${field}`, text]),
 ]);
 
 const logo = (where) => ({

package/src/lib/link-check.js

@@ -35,6 +35,7 @@ import { visit } from 'unist-util-visit';
 import { findAllPages } from './pages.js';
 import { createJsonLocator, contextMenuOptions } from './config-schema.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
+import { folderAddresses } from './folder-redirects.js';
 
 // The same github-slugger Astro builds page URLs and heading ids with -
 // resolved through Astro itself, so the two can't drift apart.
@@ -295,6 +296,11 @@ export async function checkLinks(contentDir, configText) {
   const special = new Set(['/llms.txt', '/llms-full.txt', '/404.html', '/404/']);
   if (config.domain) ['/sitemap.xml', '/sitemap-index.xml'].forEach((p) => special.add(p));
   const knownUrls = [...pages.keys(), ...generated, ...redirects];
+  // Folder addresses with no page of their own redirect to one under them
+  // (lib/folder-redirects.js), so a link to one isn't broken.
+  const folders = new Set(
+    [...folderAddresses([...pages.keys(), ...generated].map((url) => url.replace(/^\/+|\/+$/g, '')))].map((folder) => `/${folder}/`)
+  );
 
   // Anchors a page can be linked to: its own, plus those of every snippet
   // it imports (they render inside it).
@@ -398,7 +404,7 @@ export async function checkLinks(contentDir, configText) {
         return;
       }
       // "/" always exists: the home page, or a redirect to the first page.
-      if (pageKey === '/' || generated.has(pageKey) || redirects.has(pageKey) || special.has(pageKey.replace(/\/$/, '') || '/')) return;
+      if (pageKey === '/' || generated.has(pageKey) || redirects.has(pageKey) || folders.has(pageKey) || special.has(pageKey.replace(/\/$/, '') || '/')) return;
       if (special.has(pathname)) return;
 
       // Mintlify-style relative link: resolved from the file's folder

package/src/lib/llms-index.ts

@@ -62,7 +62,7 @@ export async function llmsIndexFiles(): Promise<Map<string, string> | null> {
     // The .md route when it exists ([...slug].md.ts - unless `contextMenu` is off,
     // and never for an OpenAPI page, which renders from the spec), else the
     // HTML page.
-    const hasMarkdownRoute = contextMenuOptions(config.contextMenu).length > 0 && !entry.data.openapi;
+    const hasMarkdownRoute = contextMenuOptions(config.contextMenu).length > 0;
     const href = (siteUrl ?? '') + (hasMarkdownRoute ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`);
     let description = truncateDescription(entry.data.description);
     // Mirrors Mintlify: an OpenAPI operation page's description gets its

package/src/lib/mcp-index.ts

@@ -16,7 +16,7 @@ import {
   resolveSections,
   flattenNav,
 } from './config';
-import { markdownForAgents } from './agent-markdown.js';
+import { pageMarkdown } from './openapi-markdown';
 import { orderByNavigation } from './llms.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
 
@@ -72,14 +72,9 @@ export async function mcpIndex(): Promise<McpIndex> {
     .map((entry) => {
       const slug = normalizeEntryId(entry.id);
       const fileId = fileIdForEntry(contentDir, packageRoot, entry);
-      let content = markdownForAgents(entry.body ?? '', {
-        file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
-        contentDir,
-        variables: config.variables,
-      }).trim();
-      // An OpenAPI operation page renders from the spec, so its source body
-      // is near-empty - name the operation, at least.
-      if (entry.data.openapi) content = [`Operation: ${entry.data.openapi}`, content].filter(Boolean).join('\n\n');
+      // An API page's source is a near-empty stub - its operation, written
+      // out from the spec, follows its own text (lib/openapi-markdown.ts).
+      const content = pageMarkdown(entry, { contentDir, packageRoot, variables: config.variables });
       return {
         slug,
         fileId,

package/src/lib/openapi-markdown.ts

@@ -0,0 +1,154 @@
+// OpenAPI operations as Markdown, both ways:
+//
+// - descriptionHtml(): a spec's `description` fields are Markdown (CommonMark,
+//   and in practice GitHub tables too) - rendered to HTML for the API page,
+//   instead of printed as literal text with its `**`, backticks and pipes.
+//   Astro's own Markdown renderer, so a description reads like any page.
+//
+// - operationMarkdown() / pageMarkdown(): an operation page written out as
+//   Markdown - method and path, description, parameters, body, responses,
+//   examples. An API page's own source is a near-empty stub (it renders from
+//   the spec), so this is what its .md copy, llms-full.txt and the MCP
+//   index serve for it, and what "Copy page" copies.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createMarkdownProcessor } from '@astrojs/markdown-remark';
+import {
+  schemaRows,
+  exampleFromSchema,
+  primaryContentType,
+  findOperationFile,
+  type OpenApiOperation,
+  type SchemaRow,
+} from './openapi-render';
+import { parseOpenApiRef } from './openapi-ref.js';
+import { markdownForAgents } from './agent-markdown.js';
+
+let renderer: ReturnType<typeof createMarkdownProcessor> | null = null;
+const htmlCache = new Map<string, Promise<string>>();
+
+/** A spec description as HTML. Empty for no description. */
+export function descriptionHtml(markdown: string | null | undefined): Promise<string> {
+  const text = (markdown ?? '').trim();
+  if (!text) return Promise.resolve('');
+  let html = htmlCache.get(text);
+  if (!html) {
+    renderer ??= createMarkdownProcessor({ syntaxHighlight: false });
+    html = renderer.then((r) => r.render(text)).then((result) => result.code.trim());
+    htmlCache.set(text, html);
+  }
+  return html;
+}
+
+/** The operation a page's `openapi` frontmatter names, or null. */
+export function loadOperation(ref: string, contentDir: string): OpenApiOperation | null {
+  const parsed = parseOpenApiRef(ref);
+  if (!parsed) return null;
+  const file = findOperationFile(contentDir, parsed.method, parsed.path, parsed.spec);
+  return file ? (JSON.parse(fs.readFileSync(file, 'utf-8')) as OpenApiOperation) : null;
+}
+
+/** A description placed under a list item: every line indented to sit inside it. */
+function indented(text: string, spaces: number): string {
+  const pad = ' '.repeat(spaces);
+  return text
+    .trim()
+    .split('\n')
+    .map((line) => (line.trim() ? pad + line : ''))
+    .join('\n');
+}
+
+function fieldList(rows: SchemaRow[], depth = 0): string {
+  const pad = '  '.repeat(depth);
+  return rows
+    .map((row) => {
+      const head = `${pad}- \`${row.name}\` (${row.type}${row.required ? ', required' : ''})`;
+      const desc = row.description ? `\n${indented(row.description, pad.length + 2)}` : '';
+      const children = row.children.length ? `\n${fieldList(row.children, depth + 1)}` : '';
+      return head + desc + children;
+    })
+    .join('\n');
+}
+
+function jsonBlock(value: unknown): string {
+  return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}
+
+/** The operation, written out as Markdown (no title - the page has its own). */
+export function operationMarkdown(op: OpenApiOperation): string {
+  const out: string[] = [];
+  out.push(`**${op.method.toUpperCase()}** \`${op.path}\``);
+  if (op.servers?.[0]?.url) out.push(`Base URL: \`${op.servers[0].url}\``);
+  if (op.description?.trim()) out.push(op.description.trim());
+  else if (op.summary?.trim()) out.push(op.summary.trim());
+
+  if (op.security?.length) {
+    const auth = op.security.map((s) => (s.scheme ? `${s.name} (${s.type}, ${s.scheme})` : s.in ? `${s.name} (${s.type} in ${s.in})` : `${s.name} (${s.type})`));
+    out.push(`## Authorization\n\n${auth.map((a) => `- ${a}`).join('\n')}`);
+  }
+
+  for (const [where, title] of [['header', 'Header parameters'], ['path', 'Path parameters'], ['query', 'Query parameters']] as const) {
+    const params = op.parameters.filter((p) => p.in === where);
+    if (!params.length) continue;
+    const list = params
+      .map((p) => {
+        const head = `- \`${p.name}\` (${p.schema?.type ?? 'string'}${p.required ? ', required' : ''})`;
+        return p.description ? `${head}\n${indented(p.description, 2)}` : head;
+      })
+      .join('\n');
+    out.push(`## ${title}\n\n${list}`);
+  }
+
+  const bodyType = primaryContentType(op.requestBody?.content);
+  const bodySchema = bodyType ? op.requestBody?.content?.[bodyType]?.schema : undefined;
+  if (bodyType && bodySchema) {
+    const rows = schemaRows(bodySchema);
+    const parts = [`## Body\n\nContent type: \`${bodyType}\``];
+    if (rows.length) parts.push(fieldList(rows));
+    const example = exampleFromSchema(bodySchema);
+    if (example !== null && example !== undefined) parts.push(`Example:\n\n${jsonBlock(example)}`);
+    out.push(parts.join('\n\n'));
+  }
+
+  const responses = Object.entries(op.responses ?? {});
+  if (responses.length) {
+    const parts = ['## Responses'];
+    for (const [status, resp] of responses) {
+      parts.push(`### ${status}${resp.description?.trim() ? `\n\n${resp.description.trim()}` : ''}`);
+      const type = primaryContentType(resp.content);
+      const schema = type ? resp.content?.[type]?.schema : undefined;
+      if (schema) {
+        const rows = schemaRows(schema);
+        if (rows.length) parts.push(fieldList(rows));
+        const example = exampleFromSchema(schema);
+        if (example !== null && example !== undefined) parts.push(`Example:\n\n${jsonBlock(example)}`);
+      }
+    }
+    out.push(parts.join('\n\n'));
+  }
+  return out.join('\n\n');
+}
+
+interface PageEntry {
+  body?: string;
+  filePath?: string;
+  data: { openapi?: string };
+}
+
+/** A page as agents read it (its .md copy, llms-full.txt, the MCP index),
+ *  without the title: its own Markdown, and for an API page the operation
+ *  after it - in the order the page shows them. */
+export function pageMarkdown(
+  entry: PageEntry,
+  { contentDir, packageRoot, variables }: { contentDir: string; packageRoot: string; variables: Record<string, string> }
+): string {
+  const own = markdownForAgents(entry.body ?? '', {
+    file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
+    contentDir,
+    variables,
+  }).trim();
+  if (!entry.data.openapi) return own;
+  const op = loadOperation(entry.data.openapi, contentDir);
+  const operation = op ? operationMarkdown(op) : `Operation: ${entry.data.openapi}`;
+  return [own, operation].filter(Boolean).join('\n\n');
+}

package/src/lib/selector-placement.js

@@ -6,6 +6,8 @@
 //   'sidebar'   the top of the sidebar: products inside a tab or a dropdown,
 //               like Mintlify's - they pick what the sidebar shows
 //   'topbar'    a switcher next to the site name (everything else)
+//   'none'      not shown: the page is inside a hidden item on this level
+//               (lib/hidden-sections.js)
 //
 // Without a sidebar on the page (`mode: custom` / `blank`), a 'sidebar'
 // switcher goes to the top bar instead. The mobile menu lists every level
@@ -13,6 +15,7 @@
 
 export function selectorPlacements(selectors, { sidebar = true } = {}) {
   return selectors.map((sel, i) => {
+    if (sel.hidden) return 'none';
     const parent = selectors[i - 1]?.kind;
     if (sel.kind === 'tab') return 'tabs';
     if (sel.kind === 'dropdown' && parent === 'tab') return 'tab-menu';
@@ -26,5 +29,5 @@ export function selectorPlacements(selectors, { sidebar = true } = {}) {
  *  top bar hides the tabs and switchers, so any page with navigation to
  *  reach needs it - with a sidebar or without (`mode: custom`). */
 export function hasMobileMenu({ sidebar, selectors = [], globalDropdowns = [] }) {
-  return sidebar || selectors.length > 0 || globalDropdowns.length > 0;
+  return sidebar || selectors.some((sel) => !sel.hidden) || globalDropdowns.length > 0;
 }

package/src/pages/[...slug].astro

@@ -71,6 +71,8 @@ import ApiPlayground from "../components/ApiPlayground.astro";
 import ApiReferencePanel from "../components/ApiReferencePanel.astro";
 import { searchScope, sectionTrail, ALL_SCOPES } from "../lib/search-scope.js";
 import { selectorPlacements } from "../lib/selector-placement.js";
+import { spaceOf } from "../lib/hidden-sections.js";
+import { folderRedirects } from "../lib/folder-redirects.js";
 
 // A page is hand-written (the `pages` collection, sourced from anywhere
 // in the project - docs/ has no special status, see findAllPages() in
@@ -254,12 +256,34 @@ export async function getStaticPaths() {
       };
     });
 
-  return [...rootRedirect, ...pageRoutes, ...hiddenRoutes];
+  // Folder addresses with pages under them but none of their own
+  // (`/docs/creator/`) redirect to the first page under them
+  // (lib/folder-redirects.js). Preferred in the reader's order: navigation
+  // order, public sections before hidden ones, pages outside the
+  // navigation last.
+  const slugOf = (route: { params: { slug?: string } }) => route.params.slug ?? "index";
+  const inHiddenSection = sections.map((section) => spaceOf(section.path) !== null);
+  const contentRoutes = pageRoutes.filter((route) => !("redirectTo" in route.props));
+  const folderTargets = [
+    ...contentRoutes.filter((route) => !inHiddenSection[(route.props as { sectionIndex: number }).sectionIndex]).map(slugOf),
+    ...contentRoutes.filter((route) => inHiddenSection[(route.props as { sectionIndex: number }).sectionIndex]).map(slugOf),
+    ...hiddenRoutes.map(slugOf),
+  ];
+  const takenAddresses = new Set([
+    ...[...pageRoutes, ...hiddenRoutes].map(slugOf),
+    ...(config.redirects ?? []).map((r) => r.source.replace(/^\/+|\/+$/g, "")),
+  ]);
+  const folderRoutes = [...folderRedirects(folderTargets, takenAddresses)].map(([folder, target]) => ({
+    params: { slug: folder },
+    props: { redirectTo: `/${target}/`, temporary: true },
+  }));
+
+  return [...rootRedirect, ...pageRoutes, ...hiddenRoutes, ...folderRoutes];
 }
 
 interface Props {
   redirectTo?: string;
-  // The automatic "/" redirect: temporary, see below.
+  // The automatic "/" and folder redirects: temporary, see below.
   temporary?: boolean;
   entry?: DocsEntry;
   prev?: { slug: string; group: string | null } | null;
@@ -386,6 +410,9 @@ const selectors = buildSelectors(activeSection.path, hrefForSlug, activePagePosi
 // shows the reader's own first. A hidden page belongs to no section.
 const pageSearchScope = isHidden ? { key: ALL_SCOPES, label: "" } : searchScope(activeSection.path);
 const pageSectionTrail = isHidden ? "" : sectionTrail(activeSection.path, breadcrumbs);
+// A page under a hidden navigation item searches its own index, not the
+// site's (lib/hidden-sections.js, cli/run-pagefind.js).
+const pageSearchSpace = isHidden ? null : spaceOf(activeSection.path);
 const languageSegment = isHidden ? undefined : activeSection.path.find((segment) => segment.kind === "language");
 const pageLang = languageSegment ? (languageSegment.items[languageSegment.index] as { language: string }).language : undefined;
 const globalDropdowns = buildGlobalDropdowns(
@@ -443,7 +470,7 @@ const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 // those are excluded from the .md route this menu links to in the first
 // place, which this mirrors on the UI side.
 const contextMenuItems = contextMenuOptions(config.contextMenu, { mcp: config.mcp });
-const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode && !entry.data.openapi;
+const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode;
 const siteUrl = resolveSiteUrl(config);
 
 const components = {
@@ -517,7 +544,7 @@ const components = {
         {entry.data.openapi && <ApiPlayground operation={entry.data.openapi} contentDir={contentDir} />}
         {/* After the content: a result's excerpt shows the section only when
             that's what matched. */}
-        <div hidden data-wd-search-scope={pageSearchScope.key} data-wd-search-scope-label={pageSearchScope.label} data-pagefind-filter={`scope:${pageSearchScope.key}`}>
+        <div hidden data-wd-search-scope={pageSearchScope.key} data-wd-search-scope-label={pageSearchScope.label} data-wd-search-space={pageSearchSpace?.id} data-wd-search-public={pageSearchSpace?.searchPublic ? "true" : undefined} data-pagefind-filter={`scope:${pageSearchScope.key}`}>
           {pageSectionTrail && <span data-pagefind-meta="section">{pageSectionTrail}</span>}
         </div>
       </div>
@@ -543,7 +570,7 @@ const components = {
         </div>
         <Content components={components} />
         {entry.data.openapi && <ApiPlayground operation={entry.data.openapi} contentDir={contentDir} />}
-        <div hidden data-wd-search-scope={pageSearchScope.key} data-wd-search-scope-label={pageSearchScope.label} data-pagefind-filter={`scope:${pageSearchScope.key}`}>
+        <div hidden data-wd-search-scope={pageSearchScope.key} data-wd-search-scope-label={pageSearchScope.label} data-wd-search-space={pageSearchSpace?.id} data-wd-search-public={pageSearchSpace?.searchPublic ? "true" : undefined} data-pagefind-filter={`scope:${pageSearchScope.key}`}>
           {pageSectionTrail && <span data-pagefind-meta="section">{pageSectionTrail}</span>}
         </div>
         {!entry.data.hideFooterPagination && (

package/src/pages/[...slug].md.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { APIRoute } from 'astro';
 import { loadDocsConfig, normalizeEntryId, findAllPages, contextMenuOptions } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
-import { markdownForAgents } from '../lib/agent-markdown.js';
+import { pageMarkdown } from '../lib/openapi-markdown';
 
 // The raw-Markdown twin of [...slug].astro: every content page is also
 // reachable at the exact same slug with a literal ".md" suffix (e.g.
@@ -46,13 +46,6 @@ export async function getStaticPaths() {
   const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
 
   return entries
-    // OpenAPI operation pages (generated stubs, or hand-written pages that
-    // set `openapi:` frontmatter) render almost entirely from the spec at
-    // request time (see ApiPlayground.astro) rather than from prose in
-    // entry.body - a raw .md dump of one would be near-empty and useless
-    // as an LLM-facing "view this page as text" export, so they're left
-    // out of this route entirely rather than serving something misleading.
-    .filter((entry) => !entry.data.openapi)
     // A frontmatter `url` page's HTML route is a redirect to that link -
     // there's no page content to serve as Markdown.
     .filter((entry) => !entry.data.url)
@@ -81,11 +74,8 @@ export const GET: APIRoute = ({ props }) => {
   // What the page shows rather than its raw source: Mintlify's <Visibility>
   // for agents, imported snippets inlined, `variables` filled in - see
   // lib/agent-markdown.js (llms-full.txt uses the same).
-  const body = markdownForAgents(entry.body ?? '', {
-    file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
-    contentDir,
-    variables,
-  });
+  // An API page's operation is written out after its own text (lib/openapi-markdown.ts).
+  const body = pageMarkdown(entry, { contentDir, packageRoot, variables });
   const markdown = `# ${entry.data.title}\n\n${body}`;
   return new Response(markdown, {
     headers: { 'Content-Type': 'text/markdown; charset=utf-8' },

package/src/pages/llms-full.txt.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { APIRoute } from 'astro';
 import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl, fileIdForEntry } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
-import { markdownForAgents } from '../lib/agent-markdown.js';
+import { pageMarkdown } from '../lib/openapi-markdown';
 import { orderByNavigation } from '../lib/llms.js';
 
 // The "everything, concatenated" half of the llms.txt pair - see
@@ -43,13 +43,6 @@ export const GET: APIRoute = async () => {
   const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
 
   const unordered = entries
-    // Same exclusion [...slug].md.ts applies to its own per-page raw
-    // Markdown route, for the same reason: an OpenAPI operation page
-    // (generated stub, or a hand-written page that opts into rendering
-    // <ApiPlayground /> via `openapi:` frontmatter) renders almost
-    // entirely from the spec at request time, so entry.body alone is
-    // near-empty and not a meaningful "full content" contribution here.
-    .filter((entry) => !entry.data.openapi)
     // Same noindex exclusion llms.txt.ts applies to its own listing -
     // see that file's comment.
     .filter((entry) => !entry.data.seo?.noindex)
@@ -60,11 +53,8 @@ export const GET: APIRoute = async () => {
       // What the page shows, not its raw source: <Visibility> for agents,
       // imported snippets inlined, `variables` filled in - same as the .md
       // route (lib/agent-markdown.js).
-      const body = markdownForAgents(entry.body ?? '', {
-        file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
-        contentDir,
-        variables: config.variables,
-      });
+      // An API page's operation is written out after its own text (lib/openapi-markdown.ts).
+      const body = pageMarkdown(entry, { contentDir, packageRoot, variables: config.variables });
       // The page's own URL, so an agent can cite it.
       const url = `${siteUrl ?? ''}${slug === 'index' ? '/' : `/${slug}/`}`;
       return {

package/src/scripts/search.ts

@@ -53,7 +53,10 @@ export function initSearch(root: ParentNode) {
   let loadPromise: Promise<any> | null = null;
   function ensurePagefind() {
     if (!loadPromise) {
-      const pagefindUrl = '/pagefind/pagefind.js';
+      // A page under a hidden navigation item searches its own space's index
+      // (cli/run-pagefind.js, lib/hidden-sections.js); every other page, the site's.
+      const space = document.querySelector<HTMLElement>('[data-wd-search-scope]')?.dataset.wdSearchSpace;
+      const pagefindUrl = space ? `/pagefind-spaces/${encodeURIComponent(space)}/pagefind.js` : '/pagefind/pagefind.js';
       loadPromise = import(/* @vite-ignore */ pagefindUrl)
         .then((mod: any) => {
           pagefind = mod;