@writedocs/generator 0.1.0

package/src/lib/config.ts

@@ -0,0 +1,2131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { z } from 'astro/zod';
+import { writedocsTempDir } from './writedocs-temp-dir.js';
+
+// ---------------------------------------------------------------------
+// Pages & groups - the leaf content any container ultimately bottoms out
+// at. A group can nest other groups arbitrarily deep, and can optionally
+// link its own label to a page (`page`) independent of expanding or
+// collapsing its children - see NavTree.astro for how that renders.
+// ---------------------------------------------------------------------
+
+const navPageSchema = z.string();
+
+// A group ordinarily lists its own children by hand (`pages`), but can
+// instead auto-generate them from an OpenAPI spec via `openapi: { src,
+// path }` - resolved by loadDocsConfig() (via expandOpenApiInNavigation()
+// below, reading the manifest generate-api-pages.js writes for this exact
+// group) into a real `{ group, pages }` node - one sub-group per tag -
+// before anything else in this file ever sees it, so
+// resolveSections()/flattenNav()/buildNavTree()/etc. only ever need to
+// understand the ordinary pages-array shape. `.strict()` on both variants
+// is load-bearing (see withChildren()'s own comment on this pattern
+// below): without it, a group written with both `pages` and `openapi` at
+// once would silently have one dropped instead of rejected.
+const navGroupPagesSchema: z.ZodType<{ group: string; page?: string; pages: NavItem[] }> = z.lazy(() =>
+  z
+    .object({
+      group: z.string(),
+      page: z.string().optional(),
+      pages: z.array(navItemSchema),
+    })
+    .strict()
+);
+
+const navGroupOpenApiSchema = z.object({
+  group: z.string(),
+  openapi: z
+    .object({
+      // Path to an OpenAPI 3.x spec, relative to the content directory
+      // (alongside writedocs.json) - same convention the old top-level
+      // `openapi` field used. See generate-api-pages.js (the pre-Astro
+      // build/dev step that actually parses this and writes the
+      // manifest/operation JSON this group's pages are expanded from).
+      src: z.string(),
+      // Base URL path every page generated from this spec is namespaced
+      // under, e.g. "/api" -> pages served at /api/<tag>/<operation>/.
+      // Also doubles as this spec's own unique key under
+      // writedocsTempDir()'s openapi/<path>/ directory (manifest.json + operations/*.json),
+      // so two openapi groups in the same writedocs.json must use different
+      // `path` values - generate-api-pages.js throws a clear error if
+      // they collide.
+      path: z.string(),
+    })
+    .strict(),
+}).strict();
+
+export type GroupNavItem =
+  | { group: string; page?: string; pages: NavItem[] }
+  | { group: string; openapi: { src: string; path: string } };
+
+const navGroupSchema: z.ZodType<GroupNavItem> = z.union([navGroupPagesSchema, navGroupOpenApiSchema]);
+
+// A bare external link sitting directly in a `pages` array, alongside
+// page slugs and groups - e.g. a "Support" link to an external help
+// desk shown right in the sidebar, rather than only reachable via
+// navigation.global.dropdowns. Discriminated from navGroupSchema by
+// its required `label`/`href` keys (vs `group`/`pages`/`openapi`), so a
+// plain (non-strict at the union level) schema is enough for Zod to pick
+// the right branch; `.strict()` here still catches a typo'd extra key.
+const navLinkSchema = z.object({ label: z.string(), href: z.string() }).strict();
+
+const navItemSchema: z.ZodType<NavItem> = z.lazy(() =>
+  z.union([navPageSchema, navGroupSchema, navLinkSchema])
+);
+
+export type NavItem = string | GroupNavItem | { label: string; href: string };
+
+// ---------------------------------------------------------------------
+// Containers: tabs, versions, languages, dropdowns, products.
+//
+// This schema is modeled directly on Mintlify's writedocs.json
+// (https://mintlify.com/writedocs.json / mintlify.com/docs/organize/navigation):
+// all five container kinds are structurally identical except for their
+// own identifying field. Each owns *exactly one* of {pages, tabs,
+// versions, languages, dropdowns, products} as its content, or is a bare
+// external `href` link with no content of its own. That symmetry is what
+// lets any of them nest inside any other - a tab can contain versions, a
+// version can contain languages, a language can contain tabs, and so on,
+// bottoming out at a `pages` array. `withChildren()` is the single place
+// that shape is defined, instead of hand-writing the union five times.
+// ---------------------------------------------------------------------
+
+export type NavChildren =
+  | { pages: NavItem[] }
+  | { tabs: TabItem[] }
+  | { versions: VersionItem[] }
+  | { languages: LanguageItem[] }
+  | { dropdowns: DropdownItem[] }
+  | { products: ProductItem[] }
+  | { href: string };
+
+export type TabItem = { tab: string; icon?: string } & NavChildren;
+export type VersionItem = { version: string; label?: string; tag?: string; default?: boolean } & NavChildren;
+export type LanguageItem = { language: string; label?: string } & NavChildren;
+export type DropdownItem = { dropdown: string; icon?: string } & NavChildren;
+export type ProductItem = { product: string; icon?: string; description?: string } & NavChildren;
+
+// `.strict()` on every variant is load-bearing, not decoration: Zod
+// objects silently strip unrecognized keys by default, so without it a
+// node written with two children fields at once (e.g. both `pages` and
+// `versions`) would just have the second one dropped instead of
+// rejected - defeating the entire "exactly one child kind per level"
+// rule this schema exists to enforce (mirroring Mintlify's own "a tab
+// cannot contain both anchors and groups at the same level").
+function withChildren<Base extends z.ZodRawShape>(base: Base) {
+  return z.union([
+    z.object({ ...base, pages: z.array(navItemSchema) }).strict(),
+    z.object({ ...base, tabs: z.array(tabSchema).min(1) }).strict(),
+    z.object({ ...base, versions: z.array(versionSchema).min(1) }).strict(),
+    z.object({ ...base, languages: z.array(languageSchema).min(1) }).strict(),
+    z.object({ ...base, dropdowns: z.array(dropdownSchema).min(1) }).strict(),
+    z.object({ ...base, products: z.array(productSchema).min(1) }).strict(),
+    z.object({ ...base, href: z.string() }).strict(),
+  ]);
+}
+
+// Each of these five is defined via z.lazy() because withChildren()
+// references all five by name (mutual recursion) - safe because none of
+// them are actually *called* until a real writedocs.json is parsed, by which
+// point every const below has been assigned. The same pattern already
+// used for navItemSchema/navGroupSchema above.
+const tabSchema: z.ZodType<TabItem> = z.lazy(() =>
+  withChildren({ tab: z.string(), icon: z.string().optional() })
+);
+
+const versionSchema: z.ZodType<VersionItem> = z.lazy(() =>
+  withChildren({
+    version: z.string(),
+    label: z.string().optional(),
+    tag: z.string().optional(),
+    default: z.boolean().optional(),
+  })
+);
+
+const languageSchema: z.ZodType<LanguageItem> = z.lazy(() =>
+  withChildren({ language: z.string(), label: z.string().optional() })
+);
+
+const dropdownSchema: z.ZodType<DropdownItem> = z.lazy(() =>
+  withChildren({ dropdown: z.string(), icon: z.string().optional() })
+);
+
+const productSchema: z.ZodType<ProductItem> = z.lazy(() =>
+  withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
+);
+
+// ---------------------------------------------------------------------
+// Root navigation: a flat array (shorthand for one implicit section - the
+// common case) or an object choosing exactly one primary organizational
+// pattern, per Mintlify's convention ("choose one primary organizational
+// pattern at the root level of your navigation").
+//
+// `global.dropdowns` is the one exception to "exactly one pattern": it's
+// not a primary pattern, it's a persistent set of topbar dropdown
+// triggers that render on every page regardless of which tab/version/
+// language/product is active - equivalent to Mintlify's
+// `navigation.global.anchors`. This replaces the earlier `{tabs,
+// dropdowns}` shape (both present at once), which doesn't generalize
+// once versions/languages/products are also root-level choices.
+// ---------------------------------------------------------------------
+
+export type NavigationConfig =
+  | NavItem[]
+  | { global?: { dropdowns: DropdownItem[] }; tabs: TabItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; versions: VersionItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; languages: LanguageItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; dropdowns: DropdownItem[] }
+  | { global?: { dropdowns: DropdownItem[] }; products: ProductItem[] };
+
+const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
+
+const navigationSchema = z.union([
+  z.array(navItemSchema),
+  z.object({ global: globalSchema.optional(), tabs: z.array(tabSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), versions: z.array(versionSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), languages: z.array(languageSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), dropdowns: z.array(dropdownSchema).min(1) }).strict(),
+  z.object({ global: globalSchema.optional(), products: z.array(productSchema).min(1) }).strict(),
+]) as z.ZodType<NavigationConfig>;
+
+const DEFAULT_PRIMARY = '#6366f1';
+
+// A logo is either one path used for both color modes, or a
+// { light, dark, label } object - each image shown only while that mode
+// is active (see BaseLayout.astro's .wd-logo-light/.wd-logo-dark CSS).
+// The topbar shows *only* the image by default - no site name text next
+// to it, since a real logo asset usually already is a wordmark. `label`
+// is the opt-in way to add text back next to the image (e.g. a product
+// name alongside a symbol-only mark); it only exists on the object form,
+// since a single shared image path is just as easy to bake the label
+// into directly.
+//
+// `light`/`dark` are themselves optional (unlike the string form, which
+// is inherently "both"): a site with no logo *images* at all can still
+// set `styles.logo: { label: "..." }` to override the topbar's fallback
+// text without providing any image - see BaseLayout.astro's
+// hasLogoImage/logoLabel/brandLabel derivation, where an object with
+// only `label` set already resolves correctly (brandLabel = logoLabel,
+// same as if an image were also present) without needing any change
+// there; only this schema needed loosening; light/dark were previously
+// both required whenever the object form was used at all.
+//
+// Standalone const (rather than inlined into stylesSchema.logo below) so
+// footer.logo further down can share the exact same union instead of an
+// independently-written copy - see footerSchema's own comment on why a
+// footer logo needs this at all.
+const logoSchema = z.union([
+  z.string(),
+  z.object({ light: z.string().optional(), dark: z.string().optional(), label: z.string().optional() }).strict(),
+]);
+
+// Same {light, dark}-with-fallback shape applies to `colors.dark`: any
+// of primary/text left unset there falls back to the light-mode value
+// already given above, so a site only has to specify what actually
+// differs in dark mode. There used to be a `background`/`dark.background`
+// pair here too, doing effectively the same job as `background.colors`
+// further down (see that field's own comment) - two writedocs.json fields
+// both named "background" that visually looked interchangeable but
+// weren't quite (one drove --wd-background site-wide, the other only
+// the <body> canvas), which was confusing to author against and easy to
+// half-configure by setting only one. Removed in favor of `background`
+// alone being the single place to set any background color - see that
+// field's comment for what it now covers.
+// One side of `styles.navbar` (light or dark) - either a bare background
+// color (the original shape) or `{ background, accent? }` once a site
+// wants its own accent color (the active-tab fill / hover underline)
+// inside the navbar specifically, independent of the sitewide
+// `styles.colors.primary`. Deliberately does NOT carry a text/icon color
+// field at all - see `navbar`'s own comment below (stylesSchema) for why
+// that's resolved automatically instead of being configurable. Kept as a
+// standalone const rather than inlined so `light`/`dark` share the exact
+// same union rather than two independently-written (and possibly
+// drifting) copies of it.
+const navbarColorValueSchema = z.union([
+  z.string(),
+  z
+    .object({
+      background: z.string(),
+      accent: z.string().optional(),
+    })
+    .strict(),
+]);
+
+// One font declaration - almost exactly Mintlify's own `fonts` shape (see
+// docs/dev/docs/site-config.mdx's own "Fonts" section for the research this
+// was based on): a bare Google Fonts family name (`family` alone - Google
+// Fonts loads it automatically, see googleFontsHref() below), or a local/
+// externally-hosted font file (`source` + `format` together; `source` is
+// either a project-relative path like the other five asset-fallback fields
+// this schema already has - see collectConfiguredAssetPaths() - or a full
+// https:// URL to an externally-hosted font). `weight` does two things at
+// once, both driven by BaseLayout.astro: it narrows which file actually
+// loads (folded into the Google Fonts URL's `:wght@` axis, or the
+// generated `@font-face` rule's own `font-weight` descriptor for a
+// `source` font - see googleFontsHref()/fontFaceRule() below), *and* it's
+// applied as a real CSS `font-weight` on h1-h6 (for `heading`) or `body`
+// (for `body`) - see BaseLayout's own `wdFontWeightHeading`/
+// `wdFontWeightBody`. Both halves matter: loading only the 400-weight file
+// while leaving h1-h6 at the browser's UA-default `font-weight: bold`
+// faux-bolds that file back to looking bold anyway, with no visible
+// change from configuring a lighter weight at all - the bug this second
+// half fixes (caught from real user-reported behavior, not anticipated
+// up front). Left unset anywhere in `styles.fonts` renders no font-weight
+// rule at all, keeping today's plain browser-default bold headings/normal
+// body text unchanged for a site that hasn't touched this field.
+const fontVariantSchema = z
+  .object({
+    family: z.string(),
+    weight: z.number().optional(),
+    source: z.string().optional(),
+    format: z.enum(['woff', 'woff2']).optional(),
+  })
+  .strict();
+
+export type FontVariant = z.infer<typeof fontVariantSchema>;
+
+// The top-level shape adds `heading`/`body`: each independently optional,
+// each falling back to the top-level family/weight/source/format when
+// unset (see resolveFonts() below) - so a site can set one font for
+// everything (`fonts.family` alone), or split headings and body text
+// without needing to repeat itself for whichever side isn't changing.
+const fontsSchema = z
+  .object({
+    family: z.string(),
+    weight: z.number().optional(),
+    source: z.string().optional(),
+    format: z.enum(['woff', 'woff2']).optional(),
+    heading: fontVariantSchema.optional(),
+    body: fontVariantSchema.optional(),
+  })
+  .strict();
+
+export type FontsConfig = z.infer<typeof fontsSchema>;
+
+const stylesSchema = z
+  .object({
+    colors: z
+      .object({
+        primary: z.string().default(DEFAULT_PRIMARY),
+        text: z.string().optional(),
+        dark: z
+          .object({
+            primary: z.string().optional(),
+            text: z.string().optional(),
+          })
+          .optional(),
+      })
+      .default({ primary: DEFAULT_PRIMARY }),
+    logo: logoSchema.optional(),
+    favicon: z.string().optional(),
+    // No default value here (unlike `colors.primary`'s DEFAULT_PRIMARY) -
+    // resolveFonts() below is where "Inter" actually gets applied as the
+    // site-wide default whenever this field is left unset entirely, so
+    // that fallback lives in one place alongside the rest of the
+    // resolution logic rather than being duplicated as a schema default
+    // *and* a resolver fallback.
+    fonts: fontsSchema.optional(),
+    // The Shiki theme *name* (not a full theme object/JSON - see
+    // https://shiki.style/themes for the built-in list) each fenced
+    // (```) MDX code block, and the API playground's request/response
+    // snippets, use in light/dark mode - read out of writedocs.json by both
+    // astro.config.mjs (Shiki's dual-theme markdown config) and
+    // ApiReferencePanel.astro (its own separate <Code/> usages, which
+    // don't inherit markdown.shikiConfig) via resolveCodeblockTheme()
+    // below, the single source of truth for the 'github-light'/
+    // 'github-dark' fallback. Left per-key optional (not defaulted in
+    // the schema itself) so a site can override just one side (e.g.
+    // only `dark`) and still get the ordinary default for the other.
+    codeblocks: z
+      .object({
+        light: z.string().optional(),
+        dark: z.string().optional(),
+        // Maps a fenced (```) block's own language tag to whichever real
+        // Shiki grammar actually highlights it, before that tag ever
+        // reaches Shiki - see resolveCodeblockLangAlias() below for the
+        // one built-in entry (mdx -> jsx) this ships with by default and
+        // why. A site can add its own entries for any other language tag
+        // that either doesn't tokenize well under its own grammar, or
+        // that a site wants to write under a shorter/friendlier fence tag
+        // than Shiki's own bundled id (e.g. `groovy: 'java'` for a close-
+        // enough approximation Shiki doesn't ship a dedicated grammar for
+        // at all) - merged with, not replacing, the built-in default, so
+        // adding one of a site's own doesn't require re-declaring mdx.
+        langAlias: z.record(z.string(), z.string()).optional(),
+      })
+      .strict()
+      .optional(),
+    // The topbar's own background, independent of `background` below (the
+    // page's) - a site may want its navbar to stand out (a dark or
+    // brand-colored bar over a light page) rather than blend into the
+    // page, which is the default when this is left unset. Same {light,
+    // dark} shape (and same per-key-optional, not defaulted here) as
+    // `codeblocks` right above, rather than nested under `colors` - it's a
+    // topbar-specific override, not a third general-purpose page color, so
+    // it reads more like "one more themed surface" alongside codeblocks
+    // than a sibling of primary/text. BaseLayout.astro's own
+    // lightNavbarBg/darkNavbarBg resolution is what falls each side back
+    // to the page background when unset.
+    //
+    // Each side (`light`/`dark`) is either a bare string - just the
+    // background color, exactly the original shape, kept for backwards
+    // compatibility - or `{ background, accent? }`, for when a site also
+    // wants the navbar's own active-tab-fill/hover-underline color to
+    // differ from the sitewide `styles.colors.primary` (`accent`'s only
+    // job - see BaseLayout.astro's lightNavbarAccent). Deliberately no
+    // text/icon color field here at all: BaseLayout.astro always resolves
+    // the navbar's plain text/icon color itself, picking black or white by
+    // contrast against whatever `background` resolves to
+    // (contrastTextColor() below) the moment this field is configured at
+    // all (string or object) - never a value read from writedocs.json. A
+    // manually-set text color is a legibility footgun a site author can
+    // get wrong (or drift out of sync after later changing `background`
+    // without remembering to update it too) in a way "compute it
+    // correctly, every time" simply can't - there's no legitimate reason
+    // to want *illegible* navbar text, unlike `accent`, which is a real
+    // aesthetic choice. Real bug this fixes: a site setting `navbar.light`
+    // to the same value as `colors.primary` (a plausible thing to reach
+    // for - "brand-colored navbar") made every topbar label/icon/link
+    // render in the default near-black text color against that same
+    // saturated background, all but unreadable - and an earlier version of
+    // this feature that let a writedocs.json-supplied color double as the text
+    // color reintroduced the identical bug one level down, just requiring
+    // one more (still guessable-wrong) field to trigger it.
+    navbar: z
+      .object({
+        light: navbarColorValueSchema.optional(),
+        dark: navbarColorValueSchema.optional(),
+      })
+      .strict()
+      .optional(),
+    // The single place to configure any background color: `colors` is a
+    // solid color (falls back to '#ffffff'/'#0b1120' when unset - see
+    // BaseLayout.astro's lightBackground/darkBackground resolution), and
+    // `images` layers an image on top of it (or is the whole background
+    // by itself, if `colors` is left at its default). This one pair now
+    // drives everything background-related site-wide - --wd-background
+    // (dropdowns/modals/kbd chips/footer/topbar-fallback/etc., see every
+    // `var(--wd-background)` call site) *and* the <body> canvas behind the
+    // main/toc columns - rather than the two being independently
+    // configurable fields that happened to look alike but didn't affect
+    // the same things (see this schema's own comment on `colors.dark`
+    // above for why that split was removed). Both are per-mode optional,
+    // same "only specify what differs" pattern as codeblocks/navbar above.
+    // The topbar and footer still get their own explicit opaque
+    // background (topbar.css/footer.css) specifically so an `images`
+    // background doesn't show through them; see those files' own
+    // comments. The sidebar column has no background of its own (base.css)
+    // and lets it show through, same as the main/toc columns.
+    background: z
+      .object({
+        colors: z
+          .object({
+            light: z.string().optional(),
+            dark: z.string().optional(),
+          })
+          .strict()
+          .optional(),
+        images: z
+          .object({
+            light: z.string().optional(),
+            dark: z.string().optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .default({ colors: { primary: DEFAULT_PRIMARY } });
+
+// `href` is always required - a link with nowhere to go isn't a link.
+// `label`/`icon` are each individually optional, but not both at once
+// (enforced by the .refine() below, same shape as scriptEntrySchema's own
+// exactly-one-of check above) - a link needs *something* visible to render,
+// whichever of the two, and can have both (icon rendered to the left of the
+// label - see TopBar.astro/SiteFooter.astro, the two renderers of this
+// shape). An icon-only link (no label) is the common case for something
+// like a bare GitHub mark in the topbar; label-only (no icon) is every
+// plain text link this already supported before `icon` existed - both
+// still need to keep working unchanged, hence neither field being outright
+// required on its own.
+const topbarLinkSchema = z
+  .object({
+    label: z.string().optional(),
+    href: z.string(),
+    // Same string shape as every other writedocs.json `icon` field (a plain
+    // Lucide name, or the explicit "collection:icon-name" form for
+    // anything else - see resolveIcon()/AppIcon.astro) - not documented
+    // again here since that convention is already established elsewhere
+    // in this file (tabs/switchers/socials all take the identical shape).
+    icon: z.string().optional(),
+  })
+  .strict()
+  .refine((link) => Boolean(link.label) || Boolean(link.icon), {
+    message: 'Each topbar.links/footer column link needs a "label", an "icon", or both - a link with neither has nothing to render.',
+  });
+
+// One column of the footer (BaseLayout.astro's <footer class="wd-footer">) -
+// an optional heading (e.g. "Resources", "Community") plus a list of links,
+// reusing the exact same {label, icon, href} shape as topbar.links above (a
+// footer link is the same thing rendered in a different place, no reason
+// for a second, identical-but-differently-named schema). `title` is
+// optional so a single-column footer with no heading (just a bare list of
+// links) is valid too.
+const footerColumnSchema = z
+  .object({
+    title: z.string().optional(),
+    links: z.array(topbarLinkSchema).default([]),
+  })
+  .strict();
+
+// Off by default (empty `columns`, same convention as `topbar` above - a
+// footer with nothing configured just doesn't render at all, see
+// BaseLayout.astro's `hasFooterContent` check) rather than `.optional()`
+// like contextMenu: unlike that field, an empty/default footer has no
+// build-output or routing implications to gate, it's purely visual, so
+// there's no reason to distinguish "unset" from "set to nothing" the way
+// contextMenu needs to.
+// Same {light, dark, label} union as `styles.logo` (via the shared
+// logoSchema above) - unset by default, in which case the footer just
+// shows the sitewide `styles.logo` (BaseLayout.astro's existing
+// logoLight/logoDark/logoLabel, already threaded into SiteFooter as-is).
+// Set here, it replaces that entirely rather than filling in only the
+// missing side of it - a footer.logo with only `dark` set shows *just*
+// the dark-mode image, not styles.logo's light image plus this dark one -
+// the same all-or-nothing-relative-to-styles.logo resolution BaseLayout.astro
+// already applies.
+const footerSchema = z
+  .object({
+    columns: z.array(footerColumnSchema).default([]),
+    logo: logoSchema.optional(),
+  })
+  .strict()
+  .default({ columns: [] });
+
+export type FooterColumn = z.infer<typeof footerColumnSchema>;
+export type FooterConfig = z.infer<typeof footerSchema>;
+
+// Shared by both writedocs.json's top-level `seo` (site-wide defaults) and a
+// page's own frontmatter `seo` (per-page overrides) - see
+// content.config.ts's docsSchema, which imports this exact schema rather
+// than redeclaring the same shape a second time. mergeSeo() below is what
+// actually combines the two, field by field, at render time.
+export const seoFieldsSchema = z
+  .object({
+    // Open Graph / Twitter card image - a relative path (resolved against
+    // `domain` below into an absolute URL, since most social crawlers
+    // require one) or an already-absolute https:// URL.
+    ogImage: z.string().optional(),
+    // og:type - "website" for most pages, "article" for blog-post-shaped
+    // content, etc. Defaults to "website" if never set anywhere.
+    ogType: z.string().optional(),
+    twitterCard: z.enum(['summary', 'summary_large_image']).optional(),
+    keywords: z.array(z.string()).optional(),
+    // Renders <meta name="robots" content="noindex, nofollow" /> and
+    // (see astro.config.mjs's sitemap `filter`) excludes the page from
+    // sitemap.xml entirely - both driven off this one flag, since listing
+    // a page in the sitemap while also telling crawlers not to index it
+    // would be self-contradictory.
+    noindex: z.boolean().optional(),
+  })
+  .strict();
+
+export type SeoFields = z.infer<typeof seoFieldsSchema>;
+
+/** Field-by-field merge of a page's own `seo` frontmatter over writedocs.json's
+ *  site-wide `seo` defaults - a page only overrides the specific fields it
+ *  sets, falling back to the site default for everything else, rather than
+ *  a page's (possibly partial) `seo` object replacing the site's wholesale. */
+export function mergeSeo(site: SeoFields, page?: SeoFields): SeoFields {
+  if (!page) return site;
+  return {
+    ogImage: page.ogImage ?? site.ogImage,
+    ogType: page.ogType ?? site.ogType,
+    twitterCard: page.twitterCard ?? site.twitterCard,
+    keywords: page.keywords ?? site.keywords,
+    noindex: page.noindex ?? site.noindex,
+  };
+}
+
+// Controls for the OpenAPI API playground's "Try it" modal - separate
+// from a group's own `openapi: { src, path }` field (which spec to use,
+// and where) since this is about how a *request* it sends behaves, not
+// about the spec itself.
+const apiSchema = z
+  .object({
+    // Whether the Try-it modal's Send button routes its request through
+    // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
+    // than calling the API directly from the browser. Almost no
+    // real-world API sends back Access-Control-Allow-Origin headers
+    // permitting an arbitrary docs site's origin, so a direct browser
+    // fetch() from the Try-it modal fails for most real APIs without
+    // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
+    // actual request-forwarding logic. Defaults to enabled; a site can
+    // set this to `false` to always call the API directly instead (the
+    // API is already CORS-permissive, same-origin in some deployments,
+    // or the site owner doesn't want requests routed through a third
+    // party at all).
+    proxy: z.boolean().default(true),
+  })
+  .strict()
+  .default({ proxy: true });
+
+// The "Copy page" dropdown shown next to a page's title - copy the raw
+// Markdown to the clipboard, open the raw Markdown in a new tab, or
+// deep-link into an AI assistant with a prompt pointing at it. Opt-in:
+// undefined (the field simply absent from writedocs.json) means the feature
+// is off entirely - no menu rendered, no .md routes generated at build
+// time either (see [...slug].md.ts) - rather than defaulting to on,
+// since it changes both the UI and the build output. Once a site does
+// write a `contextMenu` key (even `{}`), copying/viewing-as-Markdown are
+// always included (they need nothing but the page's own content); only
+// `openIn` (the AI-assistant deep-links, which need an absolute URL to
+// point the assistant at) is independently configurable.
+const contextMenuSchema = z
+  .object({
+    openIn: z.array(z.enum(['chatgpt', 'claude', 'perplexity'])).default(['chatgpt', 'claude', 'perplexity']),
+  })
+  .strict();
+
+export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
+
+// One entry in writedocs.json's `redirects` array - wired almost directly into
+// Astro's own `redirects` config option (astro.config.mjs), which is what
+// actually generates the redirect pages. `permanent` is deliberately not
+// part of this schema: with no server/adapter (this project always builds
+// `output: 'static'` with none installed), Astro's own docs say a static
+// redirect "does not support status codes" at all - it's always a client-
+// side `<meta http-equiv="refresh">` page, full stop. Accepting a
+// `permanent` field here that silently did nothing would be worse than
+// not offering it.
+const redirectSchema = z
+  .object({
+    source: z.string(),
+    destination: z.string(),
+  })
+  .strict();
+
+export type RedirectConfig = z.infer<typeof redirectSchema>;
+
+// A site-wide banner rendered above the topbar on every page (except
+// `mode: blank`, which drops all site chrome including this - see
+// BaseLayout.astro). Optional/undefined by default, same convention as
+// `contextMenu` above - a site with no banner configured gets no banner
+// markup at all, not an empty one.
+const bannerSchema = z
+  .object({
+    content: z.string(),
+    // Persisted via localStorage once dismissed (see BaseLayout.astro's
+    // initBanner()) - a static site has no server-side session to track
+    // this against, so "dismissed" only ever means "dismissed in this
+    // browser". A banner without `dismissible` reappears on every visit,
+    // appropriate for something that should stay visible until the site
+    // author removes it from writedocs.json themselves (e.g. "this version is
+    // deprecated"), not something a reader can permanently clear.
+    dismissible: z.boolean().default(false),
+    type: z.enum(['info', 'warning', 'critical']).default('info'),
+  })
+  .strict();
+
+export type BannerConfig = z.infer<typeof bannerSchema>;
+
+// Content for the custom 404 page (src/pages/404.astro) - Astro's own
+// file-based convention (a static build emits this as 404.html at the
+// site root; most static hosts pick it up automatically for unmatched
+// routes). Both fields are optional with hardcoded fallbacks in 404.astro
+// itself, so a site doesn't have to set either to get a reasonably
+// branded 404 page (still rendered inside the normal BaseLayout/topbar
+// chrome, just with placeholder content).
+const notFoundSchema = z
+  .object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .strict()
+  .default({});
+
+export type NotFoundConfig = z.infer<typeof notFoundSchema>;
+
+// One <script> tag to inject - exactly one of `src` (an external/local
+// file, rendered as `<script src="...">`) or `content` (inline JS,
+// rendered via `<script is:inline set:html="...">`) has to be set, not
+// both and not neither - enforced by the `.refine()` below rather than
+// leaving both optional and silently rendering an empty tag if a site
+// author gets this wrong.
+const scriptEntrySchema = z
+  .object({
+    src: z.string().optional(),
+    content: z.string().optional(),
+  })
+  .strict()
+  .refine((v) => (v.src ? !v.content : !!v.content), {
+    message: 'Each scripts.head/scripts.body entry needs exactly one of "src" or "content", not both or neither.',
+  });
+
+export type ScriptEntry = z.infer<typeof scriptEntrySchema>;
+
+// Raw third-party script injection - analytics snippets, chat widgets,
+// anything that needs a real <script> tag writedocs.json's own structured
+// fields (styles, integrations-style config, ...) don't have a dedicated
+// slot for yet. `head` renders right before </head>; `body` renders right
+// before </body> (after everything else has already loaded/hydrated -
+// see BaseLayout.astro), matching where a third-party script's own
+// install instructions usually say to put it.
+const scriptsSchema = z
+  .object({
+    head: z.array(scriptEntrySchema).default([]),
+    body: z.array(scriptEntrySchema).default([]),
+  })
+  .strict()
+  .default({ head: [], body: [] });
+
+export type ScriptsConfig = z.infer<typeof scriptsSchema>;
+
+// writedocs.json's `integrations` - a curated, high-value subset of analytics
+// providers, each getting its own minimal config object (just the id(s)
+// it actually needs) rather than requiring a site author to hand-write
+// the provider's own install snippet through the generic `scripts` field
+// above. This is deliberately its own thing, not built as sugar over
+// `scripts` the way the roadmap once implied it might be - most of these
+// providers' real snippets need `defer`/`async`/`data-*` attributes
+// ScriptEntry's plain `{ src?, content? }` shape has no way to express,
+// so BaseLayout.astro renders each provider with its own bespoke markup
+// instead of generating a ScriptEntry array to feed through the generic
+// renderer. Every snippet shape below was sourced from that provider's
+// own current official docs (fetched directly, not recalled from
+// training data) while building this feature - see
+// docs/dev/docs/integrations.mdx for links and dates.
+//
+// Every provider field is optional and independent - a site can turn on
+// any subset (including all of them at once, for a migration period) or
+// none. No "the" analytics field; a site picks whichever provider(s) it
+// actually uses.
+
+const ga4IntegrationSchema = z
+  .object({
+    // A GA4 "Measurement ID", always shaped like "G-XXXXXXXXXX" - not
+    // validated against that shape here, since Google could change the
+    // prefix/length without this schema needing to track it.
+    measurementId: z.string(),
+  })
+  .strict();
+
+const googleTagManagerIntegrationSchema = z
+  .object({
+    // A GTM container id, shaped like "GTM-XXXXXXX".
+    containerId: z.string(),
+  })
+  .strict();
+
+const plausibleIntegrationSchema = z
+  .object({
+    domain: z.string(),
+    // Plausible's own hosted script URL by default - override for a
+    // self-hosted instance, a reverse-proxy path (Plausible's own
+    // documented way to dodge ad-blockers), or one of Plausible's
+    // documented script *extensions* (e.g.
+    // "https://plausible.io/js/script.hash.outbound-links.js").
+    src: z.string().default('https://plausible.io/js/script.js'),
+  })
+  .strict();
+
+const fathomIntegrationSchema = z
+  .object({
+    // Fathom's own short "Site ID", not a full URL or measurement id.
+    siteId: z.string(),
+  })
+  .strict();
+
+const posthogIntegrationSchema = z
+  .object({
+    // PostHog calls this a "project API key" (starts with "phc_") in its
+    // own docs - `apiKey` here rather than that exact name, matching this
+    // schema's own plainer naming convention for the equivalent id on
+    // every other provider above.
+    apiKey: z.string(),
+    // PostHog is region-sharded (US/EU) with no single universal default
+    // - "https://us.i.posthog.com" is PostHog's own default for a new
+    // project, but a site on their EU cloud (or a self-hosted instance)
+    // must override this to the host shown in their own project
+    // settings, or events silently go nowhere.
+    apiHost: z.string().default('https://us.i.posthog.com'),
+  })
+  .strict();
+
+const umamiIntegrationSchema = z
+  .object({
+    websiteId: z.string(),
+    // Unlike Plausible/PostHog, Umami has no single hosted default that
+    // works for most users - it's commonly self-hosted, and even Umami
+    // Cloud users get a per-region script URL. Defaults to Umami Cloud's
+    // own documented script URL, which only happens to be correct for a
+    // Cloud user on that specific region; anyone self-hosting (the more
+    // common case for this particular provider) must override it to
+    // their own instance's own /script.js path.
+    src: z.string().default('https://cloud.umami.is/script.js'),
+  })
+  .strict();
+
+// AI chat over the site's own docs content, via a third-party provider
+// (DocsBot, currently the only one wired up) rather than a self-hosted
+// RAG pipeline - see the roadmap's own "AI chat over docs content" line
+// in docs/dev/docs/roadmap.mdx, which this fulfills via integration
+// rather than by building the retrieval/generation stack in-house.
+// Deliberately named `askAi` here, not `docsbot` - this is the
+// writedocs.json-facing, provider-neutral name for the feature (matching
+// the "Ask AI" label this kind of button/widget is conventionally
+// given in docs sites generally), independent of which vendor happens
+// to sit behind it today. `id` matches DocsBot's own embed config
+// field name exactly (`DocsBotAI.init({ id: 'teamId/botId' })`) - it's
+// a single opaque "teamId/botId" string DocsBot treats as one value,
+// not two separate ids, so this schema doesn't split it either.
+const askAiIntegrationSchema = z
+  .object({
+    id: z.string(),
+  })
+  .strict();
+
+const integrationsSchema = z
+  .object({
+    ga4: ga4IntegrationSchema.optional(),
+    googleTagManager: googleTagManagerIntegrationSchema.optional(),
+    plausible: plausibleIntegrationSchema.optional(),
+    fathom: fathomIntegrationSchema.optional(),
+    posthog: posthogIntegrationSchema.optional(),
+    umami: umamiIntegrationSchema.optional(),
+    askAi: askAiIntegrationSchema.optional(),
+  })
+  .strict()
+  .default({});
+
+export type IntegrationsConfig = z.infer<typeof integrationsSchema>;
+
+export const docsConfigSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  styles: stylesSchema,
+  navigation: navigationSchema,
+  // Platform name -> profile/page URL (e.g. `{ "github": "https://
+  // github.com/...", "twitter": "https://twitter.com/..." }`), free-form
+  // rather than an enum of known platforms - the key doubles as the icon
+  // reference BaseLayout.astro's footer resolves via resolveIcon() below
+  // (bare `"github"` -> `lucide:github`; use an explicit
+  // `"simple-icons:whatever"` key instead when the bare lucide name isn't
+  // right for a given platform). Rendered as a row of icon links in the
+  // footer - see hasFooterContent/`.wd-footer-socials` in BaseLayout.astro.
+  socials: z.record(z.string(), z.string()).default({}),
+  topbar: z
+    .object({ links: z.array(topbarLinkSchema).default([]) })
+    .default({ links: [] }),
+  // Columns of links below the page content - see footerSchema/
+  // footerColumnSchema above. Renders alongside `socials` above (as a row
+  // of icon links) in the same <footer> - see BaseLayout.astro.
+  footer: footerSchema,
+  api: apiSchema,
+  // The site's own deployed domain, e.g. "docs.example.com" or
+  // "https://docs.example.com" (the scheme is optional - resolveSiteUrl()
+  // below normalizes either form to a full https:// origin). Powers three
+  // things that all need an absolute origin to work: sitemap.xml
+  // generation (astro.config.mjs only registers @astrojs/sitemap when this
+  // is set - a sitemap of relative URLs isn't meaningful), the canonical
+  // <link> and og:url/twitter meta tags (BaseLayout.astro), and resolving
+  // a relative `seo.ogImage` into an absolute URL for social crawlers.
+  // Left optional and simply skipped (with a log message, not an error) at
+  // every one of those call sites when unset - most fixtures/local builds
+  // have no real deployed domain yet.
+  domain: z.string().optional(),
+  // Site-wide meta tag defaults - see seoFieldsSchema above. A page's own
+  // frontmatter `seo` (content.config.ts's docsSchema) overrides these
+  // field by field via mergeSeo(), rather than needing to repeat every
+  // field on every page.
+  seo: seoFieldsSchema.default({}),
+  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
+  // default (no menu, no .md routes).
+  contextMenu: contextMenuSchema.optional(),
+  // See redirectSchema above. Wired directly into Astro's own `redirects`
+  // config option in astro.config.mjs.
+  redirects: z.array(redirectSchema).default([]),
+  // Site-wide `[[key]]` substitution values, applied to page prose text
+  // at build time (see the remarkSubstituteVariables plugin wired into
+  // astro.config.mjs) - e.g. `{ "productName": "Acme" }` lets every page
+  // write `[[productName]]` once instead of hardcoding it everywhere.
+  // Double square brackets, not the more familiar `{{key}}` - MDX
+  // reserves single curly braces for embedded JS expressions, so
+  // `{{productName}}` in an .mdx file parses as a JS object-literal
+  // expression (`{productName}`, shorthand syntax) rather than literal
+  // text, and throws `ReferenceError: productName is not defined` at
+  // render time - see remarkSubstituteVariables' own comment in
+  // mdx-substitute-variables.js for the full explanation. Deliberately a
+  // flat string map, not typed values - this is text substitution into
+  // prose, not a templating language.
+  variables: z.record(z.string(), z.string()).default({}),
+  // See bannerSchema above. Absent by default (no banner rendered).
+  banner: bannerSchema.optional(),
+  // See notFoundSchema above.
+  notFound: notFoundSchema,
+  // See scriptsSchema above.
+  scripts: scriptsSchema,
+  // See integrationsSchema above.
+  integrations: integrationsSchema,
+});
+
+export type DocsConfig = z.infer<typeof docsConfigSchema>;
+
+/** Normalizes writedocs.json's `domain` into a full origin with no trailing
+ *  slash (e.g. "docs.example.com" -> "https://docs.example.com"), or null
+ *  if the site hasn't set one. The single source of truth for "does this
+ *  site have a real deployed URL" - astro.config.mjs (sitemap
+ *  registration), BaseLayout.astro (canonical/OG/Twitter URLs), and
+ *  resolveAbsoluteUrl() below all call this rather than reading
+ *  config.domain directly, so the http(s):// normalization only happens
+ *  in one place. */
+export function resolveSiteUrl(config: Pick<DocsConfig, 'domain'>): string | null {
+  if (!config.domain) return null;
+  const withScheme = /^https?:\/\//i.test(config.domain) ? config.domain : `https://${config.domain}`;
+  return withScheme.replace(/\/+$/, '');
+}
+
+/** Resolves a possibly-relative asset path (e.g. `seo.ogImage: "/card.png"`)
+ *  against the site's own domain into an absolute URL - social crawlers
+ *  (Facebook/Twitter/Slack unfurls) generally require an absolute
+ *  og:image/twitter:image URL, a same-origin relative path isn't reliably
+ *  respected. Returns the value unchanged if it's already absolute, or if
+ *  there's no siteUrl to resolve it against (a relative path is still
+ *  better than nothing in that case - most social crawlers do at least
+ *  attempt to fetch it relative to the page they scraped). */
+export function resolveAbsoluteUrl(siteUrl: string | null, value: string): string {
+  if (/^https?:\/\//i.test(value)) return value;
+  if (!siteUrl) return value;
+  return `${siteUrl}${value.startsWith('/') ? '' : '/'}${value}`;
+}
+
+/** The resolved (never-undefined) Shiki theme names for light/dark code
+ *  blocks - shared by astro.config.mjs (sitewide MDX code-fence
+ *  highlighting) and ApiReferencePanel.astro (the API playground's own
+ *  separate <Code/> usages, which don't inherit markdown.shikiConfig at
+ *  all - see astro.config.mjs's own comment on that) so both read the
+ *  same writedocs.json field and fall back to the same defaults instead of
+ *  each hardcoding its own copy. */
+export function resolveCodeblockTheme(config: DocsConfig): { light: string; dark: string } {
+  return {
+    light: config.styles.codeblocks?.light ?? 'github-light',
+    dark: config.styles.codeblocks?.dark ?? 'github-dark',
+  };
+}
+
+// mdx is a real, bundled Shiki grammar (@shikijs/langs' mdx.mjs - it does
+// exist, this isn't a "Shiki doesn't know this language" situation), but in
+// practice it tokenizes ```mdx fences into one single run per line with no
+// internal token boundaries at all - every character, JSX tag or not,
+// lands in the exact same TextMate scope and renders in the theme's plain
+// foreground color. Confirmed directly against real built output: every
+// span in a ```mdx block's compiled HTML carries the identical inline
+// color, none of the tag/attribute/string distinction a JS or JSX fence
+// gets. Aliasing to jsx - a close structural match for the JSX-heavy
+// snippets these fences are actually used for in this codebase's own docs
+// (`<Callout>`, `<Card>`, etc.) - actually highlights the tags/attributes,
+// at the cost of not distinctly coloring the markdown-prose portions
+// interleaved between them (jsx's grammar doesn't know about those) - a
+// worthwhile trade given the alternative is no color at all. See
+// astro.config.mjs's own shikiConfig.langAlias for where this actually
+// gets used. */
+const DEFAULT_CODEBLOCK_LANG_ALIAS: Record<string, string> = { mdx: 'jsx' };
+
+/** The resolved fence-language alias map - the built-in mdx -> jsx default
+ *  above, merged with (not replaced by) whatever a site adds under its own
+ *  writedocs.json styles.codeblocks.langAlias, so a site can extend this list
+ *  without having to redeclare the built-in entry to keep it. Same
+ *  "shared resolver, not each consumer re-deriving its own defaults"
+ *  pattern resolveCodeblockTheme() right above already establishes -
+ *  though today only astro.config.mjs actually consumes this one, unlike
+ *  that one, since ApiReferencePanel.astro's own <Code/> usages never
+ *  render a `mdx`-tagged snippet (API operation samples are curl/js/
+ *  python/etc., not MDX markup) to begin with. */
+export function resolveCodeblockLangAlias(config: DocsConfig): Record<string, string> {
+  return { ...DEFAULT_CODEBLOCK_LANG_ALIAS, ...config.styles.codeblocks?.langAlias };
+}
+
+const DEFAULT_FONT_FAMILY = 'Inter';
+
+export interface ResolvedFonts {
+  base: FontVariant;
+  heading: FontVariant | null;
+  body: FontVariant | null;
+}
+
+/** Resolves writedocs.json's `styles.fonts` into the three font declarations
+ *  BaseLayout.astro actually needs to render: `base` (the site-wide
+ *  default - every element gets this unless `heading`/`body` narrows it
+ *  further), and `heading`/`body`, each `null` when not independently
+ *  configured (letting BaseLayout fall back to `base` for whichever side
+ *  wasn't overridden, rather than this function silently copying `base`
+ *  into both and losing the distinction between "explicitly set to the
+ *  same font" and "just inheriting the default"). The one hardcoded
+ *  default in this whole feature lives right here: no `styles.fonts` at
+ *  all resolves to plain Inter, loaded for real (a Google Fonts `<link>`,
+ *  not just a name in a fallback stack that only renders correctly for a
+ *  reader who happens to already have Inter installed - see base.css's
+ *  old `font-family` rule, which was exactly that, before this feature
+ *  existed). */
+export function resolveFonts(config: DocsConfig): ResolvedFonts {
+  const fonts = config.styles.fonts;
+  const base: FontVariant = fonts
+    ? { family: fonts.family, weight: fonts.weight, source: fonts.source, format: fonts.format }
+    : { family: DEFAULT_FONT_FAMILY };
+  return { base, heading: fonts?.heading ?? null, body: fonts?.body ?? null };
+}
+
+/** The Google Fonts CSS2 API URL for every font in `fonts` that isn't a
+ *  `source`-based (local/externally-hosted) font - `null` if there's
+ *  nothing to load this way at all (every configured font has its own
+ *  `source`). One request covers every family needed (`&family=` repeated
+ *  per unique family+weight pair, deduped so the same pair - e.g. `base`
+ *  and `body` both left at the site default - isn't requested twice)
+ *  rather than a separate `<link>` per font. `display=swap` avoids an
+ *  invisible-text flash while the font file loads (renders in the
+ *  fallback stack immediately, swaps once the real font is ready) -
+ *  Google's own recommended default for exactly this use case. */
+export function googleFontsHref(fonts: ResolvedFonts): string | null {
+  const entries = [fonts.base, fonts.heading, fonts.body].filter(
+    (f): f is FontVariant => f !== null && !f.source
+  );
+  if (entries.length === 0) return null;
+  const seen = new Set<string>();
+  const params: string[] = [];
+  for (const f of entries) {
+    const key = `${f.family}|${f.weight ?? ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const familyParam = f.family.trim().replace(/\s+/g, '+');
+    params.push(f.weight ? `family=${familyParam}:wght@${f.weight}` : `family=${familyParam}`);
+  }
+  return `https://fonts.googleapis.com/css2?${params.join('&')}&display=swap`;
+}
+
+/** A `@font-face` rule for one `source`-based font (local project path or
+ *  externally-hosted URL), or `''` for a Google Font (no `source` - see
+ *  googleFontsHref() above, the other half of font loading). `weight`
+ *  becomes the rule's `font-weight` *descriptor* here - it tells the
+ *  browser which weight this specific file represents, so a `font-weight`
+ *  CSS value requested elsewhere (BaseLayout.astro's own
+ *  `wdFontWeightHeading`/`wdFontWeightBody`, see its comment) picks the
+ *  real matching file instead of synthetically ("faux") bolding/
+ *  thinning a mismatched one. This function only ever produces the
+ *  `@font-face` rule itself - actually applying `font-weight` to any
+ *  element (h1-h6, body) is BaseLayout's job, not this one's. */
+export function fontFaceRule(font: FontVariant | null): string {
+  if (!font || !font.source) return '';
+  const weightDecl = font.weight !== undefined ? ` font-weight: ${font.weight};` : '';
+  return `@font-face { font-family: '${font.family}'; src: url('${font.source}') format('${font.format ?? 'woff2'}'); font-display: swap;${weightDecl} }`;
+}
+
+/** Splits one side of `styles.navbar` (the string-or-object union
+ *  navbarColorValueSchema allows) into its two parts, filling in the
+ *  fallback background when the field is unset at all. `accent` stays
+ *  `undefined` - not defaulted here - for both the bare-string case and
+ *  the object case where a site set `background` without `accent`;
+ *  BaseLayout.astro is what turns that `undefined` into "fall back to
+ *  --wd-primary" for the accent CSS var. There's no `foreground` here at
+ *  all to resolve - the navbar's text/icon color is never read from
+ *  writedocs.json, see `navbar`'s own schema comment (stylesSchema) for why. */
+export function resolveNavbarColor(
+  value: string | { background: string; accent?: string } | undefined,
+  fallbackBackground: string
+): { background: string; accent: string | undefined } {
+  if (!value) return { background: fallbackBackground, accent: undefined };
+  if (typeof value === 'string') return { background: value, accent: undefined };
+  return { background: value.background, accent: value.accent };
+}
+
+/** Picks black or white text for readable contrast against `hexColor`,
+ *  via the standard relative-luminance formula (ITU-R BT.601 weights -
+ *  the same "perceived brightness" approximation used all over the web
+ *  for exactly this "what text color goes on this swatch" problem, not
+ *  the more expensive WCAG relative-luminance formula, which isn't
+ *  needed for a binary choose-the-less-bad-option decision like this
+ *  one). Used two ways in BaseLayout.astro: for `--wd-navbar-accent-text`
+ *  (the active tab's own fill used to always be `var(--wd-primary)` with
+ *  hardcoded `color: #fff`, which only actually read fine because every
+ *  default/example primary color so far has been dark/saturated enough
+ *  for white text; once a site's navbar accent can be *any* color -
+ *  `styles.navbar.light.accent`, falling back to `styles.colors.primary`
+ *  when unset, see resolveNavbarColor() above - that assumption can't
+ *  hold unconditionally), and for `--wd-navbar-foreground` itself once
+ *  `styles.navbar` is configured at all (the navbar's plain text/icon
+ *  color - see `navbar`'s own schema comment for why that's always
+ *  computed, never a writedocs.json value). Malformed input (not a 6-digit
+ *  `#rrggbb` hex) falls back to white rather than throwing - same "don't
+ *  fail a build over a cosmetic color value" posture every other color
+ *  field here takes (none of them validate hex syntax either). */
+export function contrastTextColor(hexColor: string): '#000000' | '#ffffff' {
+  const match = /^#?([0-9a-f]{6})$/i.exec(hexColor.trim());
+  if (!match) return '#ffffff';
+  const hex = match[1];
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const luminance = (299 * r + 587 * g + 114 * b) / 1000;
+  return luminance > 150 ? '#000000' : '#ffffff';
+}
+
+/** Whether an href points off-site - has an explicit scheme (`https:`,
+ *  `mailto:`, `tel:`, ...) or is protocol-relative (`//...`) - versus a
+ *  same-site path, which this codebase always produces as a single
+ *  leading slash (hrefForSlug() in [...slug].astro). Used everywhere a
+ *  nav link is rendered to decide whether it should open in a new tab;
+ *  deliberately a plain string check rather than a schema-level flag,
+ *  so it applies uniformly to every href source (topbar.links, a
+ *  switcher/tab pill pointing at a bare `href` container, a global
+ *  dropdown's own link, a sidebar link leaf) without threading an
+ *  `external` field through every one of those call sites. */
+export function isExternalHref(href: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');
+}
+
+// ---------------------------------------------------------------------
+// Icons - writedocs.json's `icon` fields (TabItem, DropdownItem, ProductItem,
+// Card) are plain strings with no schema-level distinction between "an
+// emoji, paste it verbatim" and "an icon-set name, look it up". Resolved
+// here rather than validated in the schema, since both are valid uses of
+// the same string field and the right rendering only becomes obvious once
+// you look at the value's shape.
+// ---------------------------------------------------------------------
+
+export type IconResolution =
+  | { kind: 'iconify'; name: string } // ready for astro-icon/components' <Icon name=... />
+  | { kind: 'text'; value: string }; // literal text/emoji, rendered as-is
+
+const DEFAULT_ICON_COLLECTION = 'lucide';
+
+/** Resolves a writedocs.json `icon` string into either an Iconify icon id or
+ *  literal text, covering three forms:
+ *  - "collection:icon-name" (e.g. "mdi:server", "simple-icons:github")
+ *    - used as-is against whatever @iconify-json/* collections are
+ *    installed (see astro.config.mjs / package.json).
+ *  - a bare name using only letters/digits/hyphens (e.g. "smartphone",
+ *    "book-open") - defaults to the "lucide" collection, matching what
+ *    docs.json-examples/ already assumes for plain icon-name strings.
+ *  - anything else (an emoji, a symbol, arbitrary text) - rendered
+ *    verbatim, preserving the original "just paste an emoji" behavior
+ *    from before icon-library support existed. */
+export function resolveIcon(icon: string): IconResolution {
+  if (/^[a-z0-9-]+:[a-z0-9-]+$/i.test(icon)) return { kind: 'iconify', name: icon };
+  if (/^[a-z0-9-]+$/i.test(icon)) return { kind: 'iconify', name: `${DEFAULT_ICON_COLLECTION}:${icon}` };
+  return { kind: 'text', value: icon };
+}
+
+// ---------------------------------------------------------------------
+// OpenAPI navigation expansion - turns a group's `openapi: { src, path }`
+// shorthand into a concrete `{ group, pages }` (one sub-group per tag),
+// using the per-spec manifest generate-api-pages.js writes to
+// writedocsTempDir()'s openapi/<path>/manifest.json before Astro starts (both
+// `writedocs dev` and `writedocs build` run it first - see
+// src/cli/dev.js, src/cli/build.js). Applied once, here in
+// loadDocsConfig(), so every other function in this file
+// (resolveSections, flattenNav, buildNavTree, ...) only ever sees plain
+// page-slug strings and ordinary `{ group, pages }` nodes, and never
+// needs to know the `openapi` group shorthand exists. A writedocs.json can
+// have any number of these groups, each pointing at its own spec and
+// mounted under its own `path` - generate-api-pages.js namespaces each
+// spec's manifest/operations under that same `path`, so there's no
+// cross-spec collision as long as every group uses a distinct `path`.
+// ---------------------------------------------------------------------
+
+export interface OpenApiManifestEntry {
+  slug: string;
+  method: string;
+  path: string;
+  tags: string[];
+  title: string;
+  generated: boolean;
+}
+
+/** `specPath` is the owning group's own `openapi.path` (e.g. "/api") -
+ *  generate-api-pages.js writes each spec's manifest under a directory
+ *  named after that same value, so this only ever needs to know which
+ *  group is asking, not anything about the spec's contents itself. */
+function loadOpenApiManifest(contentDir: string, specPath: string): OpenApiManifestEntry[] | null {
+  const normalized = specPath.replace(/^\/+|\/+$/g, '');
+  const manifestPath = path.join(writedocsTempDir(contentDir), 'openapi', normalized, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return null; // stale/partial write from an interrupted previous run - treat as absent
+  }
+}
+
+/** Expands one group's `openapi: { src, path }` into the `pages` array
+ *  it stands in for - one sub-group per tag (in first-seen order),
+ *  untagged operations collected into a trailing "Other" group. Returns
+ *  an empty array (an empty, harmless group) rather than throwing if the
+ *  manifest is missing - generate-api-pages.js always runs before this
+ *  does (see src/cli/dev.js/build.js), so a missing manifest here means
+ *  generation hasn't happened yet rather than a user error worth
+ *  crashing the dev server over. */
+function expandOpenApiGroupPages(openapiRef: { src: string; path: string }, contentDir: string): NavItem[] {
+  const manifest = loadOpenApiManifest(contentDir, openapiRef.path);
+  if (!manifest) return [];
+
+  const seenTags: string[] = [];
+  const byTag = new Map<string, string[]>();
+  const untagged: string[] = [];
+  for (const op of manifest) {
+    const tag = op.tags[0];
+    if (!tag) {
+      untagged.push(op.slug);
+      continue;
+    }
+    if (!byTag.has(tag)) {
+      byTag.set(tag, []);
+      seenTags.push(tag);
+    }
+    byTag.get(tag)!.push(op.slug);
+  }
+  const groups: NavItem[] = seenTags.map((tag) => ({ group: tag, pages: byTag.get(tag)! }));
+  return untagged.length > 0 ? [...groups, { group: 'Other', pages: untagged }] : groups;
+}
+
+function expandOpenApiInPages(pages: NavItem[], contentDir: string): NavItem[] {
+  return pages.map((item): NavItem => {
+    if (typeof item === 'string') return item;
+    if ('href' in item) return item;
+    if ('openapi' in item) {
+      // A group using the { group, openapi: { src, path } } shorthand -
+      // replace it with a real { group, pages } node built from that
+      // spec's own manifest, so nothing downstream needs to know the
+      // shorthand ever existed.
+      return { group: item.group, pages: expandOpenApiGroupPages(item.openapi, contentDir) };
+    }
+    // An ordinary { group, page?, pages } - recurse into its own pages,
+    // since an openapi-group can be nested inside a hand-authored group
+    // too (e.g. wrapping it to add hand-written pages alongside the
+    // auto-generated ones).
+    return { ...item, pages: expandOpenApiInPages(item.pages, contentDir) };
+  });
+}
+
+/** Mirrors walkSections()'s traversal (tabs/versions/languages/
+ *  dropdowns/products, each bottoming out at `pages`), but rewrites
+ *  rather than collects - every `pages` array anywhere in the tree gets
+ *  run through expandOpenApiInPages(). */
+function expandOpenApiInContainer(node: NavChildren, contentDir: string): NavChildren {
+  if ('pages' in node) return { pages: expandOpenApiInPages(node.pages, contentDir) };
+  if ('href' in node) return node;
+  if ('tabs' in node) {
+    return { tabs: node.tabs.map((t) => ({ ...t, ...expandOpenApiInContainer(t, contentDir) })) };
+  }
+  if ('versions' in node) {
+    return { versions: node.versions.map((v) => ({ ...v, ...expandOpenApiInContainer(v, contentDir) })) };
+  }
+  if ('languages' in node) {
+    return { languages: node.languages.map((l) => ({ ...l, ...expandOpenApiInContainer(l, contentDir) })) };
+  }
+  if ('dropdowns' in node) {
+    return { dropdowns: node.dropdowns.map((d) => ({ ...d, ...expandOpenApiInContainer(d, contentDir) })) };
+  }
+  if ('products' in node) {
+    return { products: node.products.map((p) => ({ ...p, ...expandOpenApiInContainer(p, contentDir) })) };
+  }
+  return node;
+}
+
+function expandOpenApiInNavigation(navigation: NavigationConfig, contentDir: string): NavigationConfig {
+  if (Array.isArray(navigation)) return expandOpenApiInPages(navigation, contentDir);
+  const expanded = { ...navigation, ...expandOpenApiInContainer(navigation as Container, contentDir) };
+  if (navigation.global?.dropdowns) {
+    expanded.global = {
+      dropdowns: navigation.global.dropdowns.map(
+        (d) => ({ ...d, ...expandOpenApiInContainer(d, contentDir) }) as DropdownItem
+      ),
+    };
+  }
+  return expanded as NavigationConfig;
+}
+
+export function loadDocsConfig(contentDir: string): DocsConfig {
+  const configPath = path.join(contentDir, 'writedocs.json');
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `[writedocs] writedocs.json not found at ${configPath}. Run "writedocs init" to scaffold one.`
+    );
+  }
+  const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  const result = docsConfigSchema.safeParse(raw);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('\n');
+    throw new Error(`[writedocs] writedocs.json failed validation:\n${issues}`);
+  }
+  // A no-op pass over ordinary navigation trees (no openapi groups) -
+  // always run, rather than gated behind a global manifest check, since
+  // there's no longer a single global spec to check for.
+  result.data.navigation = expandOpenApiInNavigation(result.data.navigation, contentDir);
+  return result.data;
+}
+
+// --- Locating a page by file id, independent of its effective slug -----
+//
+// writedocs.json's `pages` arrays, and every helper above/below that walks
+// them (flattenNav, firstSlugOf, containerContainsSlug, buildNavTree, ...),
+// always identify a page by its file id - its path relative to the
+// content directory (project root), extension stripped, with a trailing
+// `/index` segment dropped (matching Astro's own default id computation -
+// see the `/index` note below) - regardless of how that page ends up
+// being served. docs/ is not special: a file at `docs/guides/x.mdx` has
+// file id `docs/guides/x`, the exact same rule applied to a file
+// anywhere else in the project.
+//
+// A page's actual URL is a separate question, and Astro's own glob()
+// content loader already has a first-class answer for it: if a page's
+// frontmatter sets `slug`, `entry.id` (and therefore the route Astro
+// builds for it) becomes that value verbatim instead of the file-path
+// default - see astro/dist/content/loaders/glob.js's generateIdDefault:
+// `if (data.slug) return data.slug`. content.config.ts's `slug` schema
+// field is deliberately the same field Astro already recognizes, so
+// nothing here needs to reimplement the override or track it separately -
+// it only needs a way to find a page BY file id (to resolve writedocs.json's
+// references) even once `entry.id` no longer equals it.
+//
+// --- Page discovery -------------------------------------------------
+//
+// Any .md/.mdx file anywhere under the content directory becomes a page
+// candidate the moment it has *any* frontmatter block at all - docs/ has
+// no special status here, it's just a folder like any other (a
+// conventional, recommended place to put most pages, not a requirement).
+// content.config.ts's `pages` collection is the same docsSchema applied
+// to exactly this file set. A file with zero frontmatter (no `---` block
+// whatsoever) is never a page candidate - a snippet (see
+// docs/dev/docs/snippets.mdx) typically has none, which is what lets it
+// live anywhere without tripping schema validation. A file that *does*
+// open a frontmatter block but is missing a required field (`title`)
+// still fails validation exactly as before - only "no frontmatter at
+// all" is new; a genuine mistake (frontmatter present, title forgotten)
+// stays a loud build error rather than being silently treated as
+// non-page content.
+//
+// A handful of directories are never scanned regardless of what's in
+// them - build output, dependencies, and writedocs' own working
+// directories, none of which a site author would ever intend as page
+// content. Only excluded at the content directory's own top level (a
+// hand-authored `guides/dist-notes.mdx` isn't mistaken for the build
+// output directory `dist/` just because a folder two levels down happens
+// to also be named `dist`).
+const EXCLUDED_TOP_LEVEL_DIRS = new Set(['node_modules', 'dist', '.astro', '.writedocs', 'public', '.git']);
+
+/** Recursively finds every .md/.mdx file under `contentDir` that has a
+ *  frontmatter block, skipping the handful of build/dependency
+ *  directories a real content directory tends to also contain (see
+ *  EXCLUDED_TOP_LEVEL_DIRS above) - docs/ is scanned exactly like any
+ *  other folder, no special-casing. Returns POSIX-relative paths (from
+ *  `contentDir`) suitable to hand straight to Astro's `glob()` loader as
+ *  a literal `pattern` array - see content.config.ts's `pages`
+ *  collection, and [...slug].astro, which needs the identical list to
+ *  decide whether calling `getCollection('pages')` is worth doing at all
+ *  (see content.config.ts's own comment on why an empty collection still
+ *  needs to exist, just backed by a no-op loader, to avoid Astro's "does
+ *  not exist or is empty" warning). Also reused directly by
+ *  astro.config.mjs's noindex/sitemap scan, so that scan always sees
+ *  exactly the same file set that actually becomes a page - no risk of
+ *  the two drifting apart. Synchronous and re-run from scratch wherever
+ *  it's called rather than cached and shared across modules - consistent
+ *  with how loadDocsConfig() itself is already called repeatedly across
+ *  this codebase instead of threaded through as shared state, and cheap
+ *  enough in practice (a docs site's own file count) not to matter. */
+export function findAllPages(contentDir: string): string[] {
+  const results: string[] = [];
+  function walk(dir: string, relBase: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile() || !/\.mdx?$/i.test(entry.name)) continue;
+      let raw: string;
+      try {
+        raw = fs.readFileSync(abs, 'utf-8');
+      } catch {
+        continue;
+      }
+      const { data } = matter(raw);
+      if (Object.keys(data).length === 0) continue; // no frontmatter at all - not a page
+      results.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  return results;
+}
+
+/** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
+ *  `public/` included - auto-loaded site-wide with zero `writedocs.json`
+ *  config, on top of (not instead of) the explicit `scripts` field
+ *  (bannerSchema and friends, above). Drop a file in, it loads;
+ *  there's no field naming which ones to use, matching the same "just
+ *  works" convention `docs/`'s own file discovery already follows (see
+ *  findAllPages() above / `content-pipeline.mdx`) - a site author already
+ *  drops content files in and expects them found, rather than also
+ *  listing every one in writedocs.json.
+ *
+ *  Two separate walks, because `public/` needs different treatment than
+ *  everywhere else:
+ *
+ *  - `css`/`js`: every `.css`/`.js` file outside `public/` (root, `docs/`,
+ *    `snippets/`, any custom folder) - reused as the walk-with-exclusions
+ *    shape from findAllPages() above, and its exact `EXCLUDED_TOP_LEVEL_DIRS`
+ *    set (skipped only at the project root, same as there), so `dist/`,
+ *    `node_modules/`, `.astro/`, `.writedocs/`, `.git/`, and (for this
+ *    half only - see below) `public/` are never walked into. BaseLayout.astro
+ *    reads each one's raw content and inlines it as a `<style>`/
+ *    `<script is:inline>` tag.
+ *  - `publicCss`/`publicJs`: every `.css`/`.js` file *inside* `public/`,
+ *    walked separately (starting from `<contentDir>/public` rather than
+ *    `contentDir` itself, so the same `EXCLUDED_TOP_LEVEL_DIRS` check
+ *    doesn't apply here - there's no `public/public/` or `public/dist/`
+ *    convention to guard against). Returned as public-URL-rooted hrefs
+ *    (a leading `/`, no `public` segment - `public/custom.css` becomes
+ *    `/custom.css`) rather than content-dir-relative paths, since these
+ *    files are already served as static assets at exactly that URL once
+ *    Astro copies `public/` into the build output. BaseLayout.astro
+ *    renders these as ordinary `<link rel="stylesheet">`/`<script src>`
+ *    tags pointing at that URL instead of inlining their content -
+ *    inlining would duplicate every byte (once in the page's own HTML,
+ *    once more as the independently-fetchable static file at that same
+ *    URL) for no benefit, where a `<link>`/`<script src>` gets normal
+ *    browser caching across pages instead of repeating the content on
+ *    every single page's markup.
+ *
+ *  Both halves are broader than they might sound - a stray `.js` file
+ *  kept in `docs/`, `snippets/`, or `public/` for an unrelated reason
+ *  (a snippet's own local helper, an image gallery's lightbox script
+ *  someone dropped in `public/` to reference from a raw `<script src>`
+ *  in an .mdx file, say) gets auto-injected sitewide the same as a
+ *  deliberate one; there's no separate "this one's just tooling" signal
+ *  to opt out of the convention short of renaming its extension.
+ *
+ *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
+ *  by their respective path for deterministic load order across rebuilds
+ *  - same reasoning as llms.txt's own alphabetical-by-slug sort (see
+ *  llms.txt.ts) - filesystem readdir order isn't guaranteed portable
+ *  across OSes or directory-walk order otherwise.
+ *
+ *  `css`/`js` return POSIX-separated paths relative to `contentDir`, not
+ *  absolute paths or file contents - BaseLayout.astro (the sole caller)
+ *  resolves and reads each one's content itself, right before inlining
+ *  it, so a file's content is always current as of that specific
+ *  request/build rather than cached here across a `writedocs dev`
+ *  session. `publicCss`/`publicJs` return the public-URL hrefs described
+ *  above - nothing to read, Astro's own static-file serving/copy already
+ *  handles those. */
+export function findRootAssets(
+  contentDir: string
+): { css: string[]; js: string[]; publicCss: string[]; publicJs: string[] } {
+  const css: string[] = [];
+  const js: string[] = [];
+  function walk(dir: string, relBase: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (/\.css$/i.test(entry.name)) css.push(rel);
+      else if (/\.js$/i.test(entry.name)) js.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  css.sort();
+  js.sort();
+
+  const publicCss: string[] = [];
+  const publicJs: string[] = [];
+  function walkPublic(dir: string, relBase: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkPublic(abs, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (/\.css$/i.test(entry.name)) publicCss.push(`/${rel}`);
+      else if (/\.js$/i.test(entry.name)) publicJs.push(`/${rel}`);
+    }
+  }
+  walkPublic(path.join(contentDir, 'public'), '');
+  publicCss.sort();
+  publicJs.sort();
+
+  return { css, js, publicCss, publicJs };
+}
+
+/** The root-relative URL paths (leading `/`, e.g. `/images/hero.svg`)
+ *  referenced by the writedocs.json/styles fields that point at a static asset
+ *  *by URL* rather than embedding it inline: `styles.favicon`,
+ *  `styles.logo` (both the plain-string and `{light, dark}` object forms),
+ *  `styles.background.images.{light,dark}`, and `seo.ogImage`. External
+ *  URLs (anything not starting with `/` - `https://...`, mainly) are
+ *  filtered out, since those need no local file resolution at all.
+ *  Deduped, since e.g. `logo.light` and `background.images.light`
+ *  coincidentally pointing at the same file shouldn't resolve/copy it
+ *  twice.
+ *
+ *  Used by `stylesAssetFallback()` (`styles-asset-integration.js`,
+ *  imported from `astro.config.mjs`) to let every one of these resolve
+ *  from *anywhere* in the project, not just `public/` - previously,
+ *  `public/` was the one place `styles.background.images` (etc.) had to
+ *  live, since Astro's own `publicDir` copy is the only thing that ever
+ *  served them; everywhere else in this codebase's own "drop a file
+ *  anywhere, it's found" convention (`findRootAssets()` right above,
+ *  `findAllPages()` for content) already worked project-wide. See that
+ *  integration's own comment for the actual resolution mechanism (a dev-time
+ *  middleware plus a post-build copy step, not a duplicated `publicDir`)
+ *  and why a straight copy-into-`public/`-on-disk approach was rejected.
+ *
+ *  Logo light/dark resolution here deliberately mirrors BaseLayout.astro's
+ *  own `logoLight`/`logoDark` derivation exactly (a plain-string `logo`
+ *  counts as both light and dark) - two independent implementations of
+ *  that same union-unwrapping would only be one accidental edit away from
+ *  disagreeing with each other. `footer.logo` (footerSchema) gets the
+ *  same treatment, independently of `styles.logo` - both are collected
+ *  unconditionally here (not just whichever one BaseLayout.astro would
+ *  actually end up using for a given page), since this function has no
+ *  page context to know which page modes render a footer at all; an
+ *  unreferenced path collected here that never actually renders anywhere
+ *  is harmless (nothing copies/resolves a file that's never requested),
+ *  but a real footer.logo file silently 404ing because this function
+ *  didn't know to resolve it is exactly the bug this comment is warning
+ *  future edits away from repeating.
+ *
+ *  Per-page frontmatter `seo.ogImage` overrides are deliberately out of
+ *  scope - those aren't visible from a `DocsConfig` alone (they live in
+ *  each page's own frontmatter, merged in per-request by [...slug].astro/
+ *  BaseLayout.astro), and resolving every page's own override would need
+ *  a full content scan this function has no reason to also become. A
+ *  page overriding `seo.ogImage` to something outside `public/` still
+ *  needs to put it there for now. */
+export function collectConfiguredAssetPaths(config: DocsConfig): string[] {
+  const logo = config.styles.logo;
+  const logoLight = typeof logo === 'string' ? logo : logo?.light;
+  const logoDark = typeof logo === 'string' ? logo : logo?.dark;
+  const footerLogo = config.footer.logo;
+  const footerLogoLight = typeof footerLogo === 'string' ? footerLogo : footerLogo?.light;
+  const footerLogoDark = typeof footerLogo === 'string' ? footerLogo : footerLogo?.dark;
+  const fonts = config.styles.fonts;
+  const raw: (string | undefined)[] = [
+    config.styles.favicon,
+    logoLight,
+    logoDark,
+    footerLogoLight,
+    footerLogoDark,
+    config.styles.background?.images?.light,
+    config.styles.background?.images?.dark,
+    config.seo?.ogImage,
+    // A `styles.fonts` `source` is only ever handled here when it's a
+    // project-relative path (the `p.startsWith('/')` filter below already
+    // excludes both Google Font names, which never start with "/", and a
+    // full https:// external font URL, which the browser fetches directly
+    // - neither needs resolving/copying through this pipeline at all).
+    fonts?.source,
+    fonts?.heading?.source,
+    fonts?.body?.source,
+  ];
+  const paths = raw.filter((p): p is string => Boolean(p) && p.startsWith('/'));
+  return Array.from(new Set(paths));
+}
+
+export interface DocsEntryLike {
+  id: string;
+  filePath?: string;
+}
+
+/** Recovers a content entry's writedocs.json-facing file id (its path
+ *  relative to the content directory, extension stripped, trailing
+ *  `/index` dropped), independent of any frontmatter `slug` override -
+ *  `entry.filePath` is always root-relative and POSIX-separated (how
+ *  Astro's content layer records it, relative to whatever `--root` Astro
+ *  itself was invoked with - see run-astro.js), so both it and the
+ *  content directory are resolved to absolute paths before comparing,
+ *  rather than string-matching a prefix that could be relative,
+ *  absolute, or platform-separated inconsistently.
+ *
+ *  The trailing-`/index`-drop mirrors Astro's own default id computation
+ *  exactly (`getContentEntryIdAndSlug()` in astro/dist/content/
+ *  utils.js: segments are joined then `.replace(/\/index$/, '')`) -
+ *  without it, a nested index file like `docs/guides/index.mdx` (Astro's
+ *  own default id: "docs/guides") would recover the wrong file id here
+ *  ("docs/guides/index"), and a writedocs.json reference written to match the
+ *  page's real URL would fail to resolve. A single-segment `index.mdx`
+ *  at the content root is unaffected either way - the regex requires a
+ *  preceding `/`, which a bare "index" doesn't have (matching Astro's
+ *  own behavior: a root-level index.mdx keeps file id "index", not "").
+ *
+ *  Full per-segment slugification (github-slugger, applied by Astro to
+ *  every path segment) is deliberately *not* replicated here - every
+ *  filename in this codebase's own fixtures and every filename this
+ *  function needs to have handled correctly is already slug-safe
+ *  (lowercase, hyphenated, no spaces/unicode), so slugification is
+ *  always a no-op in practice; only the `/index`-stripping behavior is
+ *  reproduced, since that's the one part of Astro's algorithm this
+ *  change newly exercises (a file that used to be a collection's own
+ *  base-root index, exempt from stripping, and is now nested one level
+ *  deeper).
+ *
+ *  Entries from the `generatedDocs` collection (auto-generated OpenAPI
+ *  stub pages - see content.config.ts / generate-api-pages.js) live
+ *  under writedocsTempDir()'s generated-docs/ directory - an OS temp
+ *  directory location entirely outside contentDir, not a subdirectory
+ *  of it - so `relativeToContentDir` for one of these always starts with
+ *  `..` (walking back out of contentDir to reach it), and the check
+ *  right below falls back to `entry.id` instead of computing a
+ *  nonsensical id relative to a directory the file was never actually
+ *  under. Those entries always set their own `slug` frontmatter
+ *  explicitly, so there's no independent "file path" identity worth
+ *  recovering for them the way there is for a hand-written page that
+ *  might move around - `entry.id` (Astro's already-resolved slug)
+ *  already IS the exact value generate-api-pages.js's own manifest
+ *  references them by. */
+export function fileIdForEntry(
+  contentDir: string,
+  packageRoot: string,
+  entry: DocsEntryLike
+): string {
+  if (!entry.filePath) return entry.id;
+  const absoluteContentDir = path.resolve(contentDir);
+  const absoluteFilePath = path.resolve(packageRoot, entry.filePath);
+  const relativeToContentDir = path.relative(absoluteContentDir, absoluteFilePath);
+  if (relativeToContentDir.startsWith('..')) return entry.id;
+  const posixRelative = relativeToContentDir.split(path.sep).join('/');
+  if (EXCLUDED_TOP_LEVEL_DIRS.has(posixRelative.split('/')[0])) return entry.id;
+  return posixRelative.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
+}
+
+/** Normalizes a raw `entry.id` into the bare, slash-free form every
+ *  route/href in this codebase assumes. Once a page sets a frontmatter
+ *  `slug`, `entry.id` becomes that value completely verbatim - Astro's
+ *  glob loader applies no normalization of its own (see
+ *  generateIdDefault in astro/dist/content/loaders/glob.js) - so
+ *  `slug: /` or `slug: /guides/new-name` (both natural things to write,
+ *  mirroring how every href elsewhere in writedocs.json already has a
+ *  leading slash) would otherwise produce broken multi-slash hrefs
+ *  wherever hrefForSlug wraps the value in its own `/${slug}/`, and a
+ *  bare "/" would additionally fail to be recognized as claiming root,
+ *  colliding with the synthetic root-redirect route. */
+export function normalizeEntryId(id: string): string {
+  const trimmed = id.replace(/^\/+/, '').replace(/\/+$/, '');
+  return trimmed === '' ? 'index' : trimmed;
+}
+
+export interface FlatNavEntry {
+  slug: string;
+  group: string | null;
+}
+
+export function flattenNav(navigation: NavItem[], group: string | null = null): FlatNavEntry[] {
+  return navigation.flatMap((item): FlatNavEntry[] => {
+    if (typeof item === 'string') {
+      return [{ slug: item, group }];
+    }
+    if ('href' in item) return []; // external link leaf, not a content page - no route/prev-next entry
+    // loadDocsConfig() always expands `{ group, openapi }` shorthand into
+    // a real `{ group, pages }` before anything reaches here (see
+    // expandOpenApiInNavigation() above) - this is just a defensive
+    // no-op for the shouldn't-happen case of an unexpanded node.
+    if ('openapi' in item) return [];
+    const ownPage: FlatNavEntry[] = item.page ? [{ slug: item.page, group: item.group }] : [];
+    return [...ownPage, ...flattenNav(item.pages, item.group)];
+  });
+}
+
+// --- Sections -------------------------------------------------------
+//
+// A Section is the atomic unit that owns one page tree and therefore one
+// sidebar - every real content page belongs to exactly one Section,
+// whichever `pages` leaf it's listed under, however deep in the
+// tabs/versions/languages/dropdowns/products tree that leaf lives.
+//
+// A Section's `path` records the full chain of containers from the
+// navigation root down to it, one PathSegment per level. This is
+// everything the topbar needs to render the right selector controls
+// (tabs bar, version dropdown, ...) and highlight the right option in
+// each - without the router or layout needing to know how deep or in
+// what order the site author nested things.
+
+export type PathSegment =
+  | { kind: 'tab'; items: TabItem[]; index: number }
+  | { kind: 'version'; items: VersionItem[]; index: number }
+  | { kind: 'language'; items: LanguageItem[]; index: number }
+  | { kind: 'dropdown'; items: DropdownItem[]; index: number }
+  | { kind: 'product'; items: ProductItem[]; index: number };
+
+export interface Section {
+  pages: NavItem[];
+  path: PathSegment[];
+}
+
+type Container = NavChildren;
+type NamedContainer = TabItem | VersionItem | LanguageItem | DropdownItem | ProductItem;
+
+function walkSections(node: Container, path: PathSegment[], out: Section[]): void {
+  if ('pages' in node) {
+    out.push({ pages: node.pages, path });
+    return;
+  }
+  if ('href' in node) return; // external link, not a Section
+  if ('tabs' in node) {
+    node.tabs.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'tab', items: node.tabs, index }], out)
+    );
+    return;
+  }
+  if ('versions' in node) {
+    node.versions.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'version', items: node.versions, index }], out)
+    );
+    return;
+  }
+  if ('languages' in node) {
+    node.languages.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'language', items: node.languages, index }], out)
+    );
+    return;
+  }
+  if ('dropdowns' in node) {
+    node.dropdowns.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'dropdown', items: node.dropdowns, index }], out)
+    );
+    return;
+  }
+  if ('products' in node) {
+    node.products.forEach((item, index) =>
+      walkSections(item, [...path, { kind: 'product', items: node.products, index }], out)
+    );
+    return;
+  }
+}
+
+export function resolveSections(navigation: NavigationConfig): Section[] {
+  if (Array.isArray(navigation)) return [{ pages: navigation, path: [] }];
+  const sections: Section[] = [];
+  walkSections(navigation as Container, [], sections);
+  // global.dropdowns sits outside the primary pattern, but its pages
+  // still need routes generated for them - walk each entry too, with an
+  // empty path (they don't participate in the tabs/version/etc.
+  // selector chain, only in the always-visible globalDropdowns list).
+  for (const dropdown of navigation.global?.dropdowns ?? []) {
+    walkSections(dropdown, [], sections);
+  }
+  return sections;
+}
+
+/** Which Section (by index into resolveSections()'s result) a page belongs to. */
+export function findSectionIndexForSlug(sections: Section[], slug: string): number {
+  const index = sections.findIndex((s) => flattenNav(s.pages).some((entry) => entry.slug === slug));
+  return index === -1 ? 0 : index;
+}
+
+/** The always-visible topbar dropdown list - independent of whichever
+ *  primary pattern/section is active (Mintlify's equivalent is
+ *  `navigation.global.anchors`). */
+export function resolveGlobalDropdowns(navigation: NavigationConfig): DropdownItem[] {
+  if (Array.isArray(navigation)) return [];
+  return navigation.global?.dropdowns ?? [];
+}
+
+/** The first real page slug reachable by descending into a container's
+ *  content, however deep - used to compute where a selector option (a
+ *  tab, a version, ...) navigates to when chosen. Null for an external
+ *  `href` leaf, which the caller renders as a plain link using the
+ *  node's own href instead. Versions prefer whichever entry is marked
+ *  `default` (falling back to the first), matching Mintlify's version
+ *  default rule. */
+/** Tries `firstSlugOf()` against each item in order, returning the first
+ *  non-null result - a plain `items[0]` pick (the previous behavior)
+ *  breaks the moment that first sibling happens to be a bare `href` leaf
+ *  (returns null, with nothing that tries the next one), which is a real
+ *  case now that any container - not just a nested dropdown - can be a
+ *  bare external link (e.g. a `tabs` array whose first entry is
+ *  `{ tab: "Status", href: "..." }`). */
+function firstSlugAmong(items: Container[]): string | null {
+  for (const item of items) {
+    const slug = firstSlugOf(item);
+    if (slug !== null) return slug;
+  }
+  return null;
+}
+
+export function firstSlugOf(node: Container): string | null {
+  if ('pages' in node) return flattenNav(node.pages)[0]?.slug ?? null;
+  if ('href' in node) return null;
+  if ('tabs' in node) return firstSlugAmong(node.tabs);
+  if ('versions' in node) {
+    // Try the `default`-tagged version(s) first (matching the old
+    // "preferred" pick), then fall through to the rest in order - same
+    // href-leaf-with-no-fallback concern as `tabs` above, just with an
+    // extra preference pass in front of it.
+    const defaults = node.versions.filter((v) => v.default);
+    const rest = node.versions.filter((v) => !v.default);
+    return firstSlugAmong([...defaults, ...rest]);
+  }
+  if ('languages' in node) return firstSlugAmong(node.languages);
+  if ('dropdowns' in node) return firstSlugAmong(node.dropdowns);
+  if ('products' in node) return firstSlugAmong(node.products);
+  return null;
+}
+
+/** For a version/language switcher, finds where the reader's current
+ *  page would live inside a *different* version/language's own subtree,
+ *  so switching keeps them on the same conceptual page instead of always
+ *  bouncing to that option's first page (see buildSelectors() below,
+ *  which is the only caller). "Same page" is approximated positionally
+ *  rather than by name, since nothing guarantees a version/language's
+ *  own identifier lines up with its pages' file paths - a version
+ *  tagged "2025-09" could just as easily keep its pages under a "v1"
+ *  folder with no relation to that string, so there's no naming
+ *  convention to key off safely; this heuristic only ever compares tree
+ *  position, never path text. (docs.json-examples/00-kitchen-sink/'s own
+ *  versions - "2025-09"/"2026-01" under Core Platform - happen to have
+ *  folder names that line up with their version strings, so it doesn't
+ *  demonstrate the mismatched-folder-name case directly; the guarantee
+ *  still doesn't exist regardless of what one fixture happens to do.)
+ *
+ *  Two things have to line up for a page to count as "the same" one:
+ *  first, `remainingPath` (whatever tab/product/dropdown was chosen
+ *  *below* the version/language being switched, on the reader's actual
+ *  page) has to exist at the same index in `item`'s own subtree too -
+ *  an option isn't guaranteed to nest the same way that many levels
+ *  down (a version could add/remove a tab), so any mismatch here bails
+ *  out to null immediately rather than guessing. Second, once both
+ *  bottom out at a leaf `pages` list, `position` (the reader's own page
+ *  index within *its* pages list) has to exist in `item`'s pages list
+ *  too - two versions/languages of the same docs are usually authored
+ *  with matching page order even when the file paths differ, so this
+ *  is a reasonable proxy for "the same page" without relying on names.
+ *
+ *  Returns null - meaning "no equivalent page, fall back to
+ *  firstSlugOf()" - on any structural mismatch or an out-of-range
+ *  position, rather than guessing at a wrong page. */
+export function equivalentPageIn(
+  item: Container,
+  remainingPath: PathSegment[],
+  position: number
+): string | null {
+  if ('pages' in item) return flattenNav(item.pages)[position]?.slug ?? null;
+  if ('href' in item) return null;
+  const [next, ...rest] = remainingPath;
+  if (!next) return null; // the reader's own page didn't go this deep - no basis to pick a branch
+  if ('tabs' in item && next.kind === 'tab') {
+    const target = item.tabs[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('versions' in item && next.kind === 'version') {
+    const target = item.versions[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('languages' in item && next.kind === 'language') {
+    const target = item.languages[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('dropdowns' in item && next.kind === 'dropdown') {
+    const target = item.dropdowns[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  if ('products' in item && next.kind === 'product') {
+    const target = item.products[next.index];
+    return target ? equivalentPageIn(target, rest, position) : null;
+  }
+  return null; // structural mismatch - this option nests differently at this depth
+}
+
+/** The first real page slug in the whole site, root navigation pattern
+ *  included - used to redirect `/` somewhere sensible when nothing in
+ *  the navigation happens to be a page literally named "index" (the
+ *  usual "docs/index.mdx is the homepage" convention). Mirrors
+ *  firstSlugOf()'s per-container descent, plus the flat-array root case
+ *  firstSlugOf() alone can't handle since a bare array isn't a Container. */
+export function firstSlugOfNavigation(navigation: NavigationConfig): string | null {
+  if (Array.isArray(navigation)) return flattenNav(navigation)[0]?.slug ?? null;
+  return firstSlugOf(navigation as Container);
+}
+
+/** Whether `slug` is reachable anywhere underneath a container, however
+ *  deep - used for computing active state on nodes that aren't part of
+ *  the active Section's own `path` (global dropdown entries). */
+export function containerContainsSlug(node: Container, slug: string): boolean {
+  if ('pages' in node) return flattenNav(node.pages).some((entry) => entry.slug === slug);
+  if ('href' in node) return false;
+  if ('tabs' in node) return node.tabs.some((t) => containerContainsSlug(t, slug));
+  if ('versions' in node) return node.versions.some((v) => containerContainsSlug(v, slug));
+  if ('languages' in node) return node.languages.some((l) => containerContainsSlug(l, slug));
+  if ('dropdowns' in node) return node.dropdowns.some((d) => containerContainsSlug(d, slug));
+  if ('products' in node) return node.products.some((p) => containerContainsSlug(p, slug));
+  return false;
+}
+
+function labelOf(item: NamedContainer): string {
+  if ('tab' in item) return item.tab;
+  if ('version' in item) return item.label ?? item.version;
+  if ('language' in item) return item.label ?? item.language;
+  if ('dropdown' in item) return item.dropdown;
+  return item.product;
+}
+
+function iconOf(item: NamedContainer): string | undefined {
+  return (item as { icon?: string }).icon;
+}
+
+// --- Topbar selectors -------------------------------------------------
+//
+// One Selector per PathSegment on the active Section's path. Tabs render
+// as the horizontal pill bar (all options always visible, exactly one
+// current); versions/languages/products, and dropdowns used as a nested
+// path segment, render as a single switcher control instead - the
+// trigger shows the *current* option, its menu lists the alternatives.
+// See BaseLayout.astro for the actual markup per kind.
+
+export interface SelectorOption {
+  label: string;
+  icon?: string;
+  tag?: string;
+  href: string;
+  active: boolean;
+  // Set when this option's own container is a `dropdowns` list (e.g. a
+  // tab whose content is `dropdowns` instead of `pages`) - the tab pill
+  // itself becomes a dropdown-trigger showing these as its menu, rather
+  // than a separate dropdown control rendered alongside it. Only ever
+  // populated one level deep (a dropdown option doesn't itself get a
+  // nested `dropdown` - matches the one level of "a tab/dropdown owns a
+  // dropdowns list" this is meant to cover).
+  dropdown?: SelectorOption[];
+}
+
+export interface Selector {
+  kind: PathSegment['kind'];
+  options: SelectorOption[];
+}
+
+/** An option's own `dropdowns` menu, if it has one (see SelectorOption.dropdown
+ *  above) - `activeSegment` is the *next* PathSegment after this option's own
+ *  segment, only passed when this option is the active one on its level, so a
+ *  sibling option that also happens to own `dropdowns` doesn't spuriously mark
+ *  one of its entries active just because some *other* option is currently
+ *  selected. */
+function dropdownMenuOf(
+  node: NavChildren,
+  hrefForSlug: (slug: string) => string,
+  activeSegment: PathSegment | undefined
+): SelectorOption[] | undefined {
+  if (!('dropdowns' in node)) return undefined;
+  return node.dropdowns.map((d, i) => ({
+    label: d.dropdown,
+    icon: iconOf(d),
+    href: 'href' in d ? d.href : hrefForSlug(firstSlugOf(d) ?? 'index'),
+    active: activeSegment?.kind === 'dropdown' && activeSegment.index === i,
+  }));
+}
+
+/** `activePagePosition` is the reader's current page's own index within
+ *  its Section's flattened pages list (-1 if it can't be found there,
+ *  which just disables the position-preserving behavior below) - see
+ *  [...slug].astro for how it's computed. Only version/language
+ *  switchers try to preserve position across options; tabs/dropdowns/
+ *  products keep linking to firstSlugOf() unconditionally, since those
+ *  represent genuinely different content (an "API Reference" tab isn't
+ *  "the same page" as a "Guides" tab just because they're both first),
+ *  unlike a version/language of what's meant to be the same docs. */
+export function buildSelectors(
+  path: PathSegment[],
+  hrefForSlug: (slug: string) => string,
+  activePagePosition: number = -1
+): Selector[] {
+  return path.map((segment, segIndex): Selector => {
+    const preservesPosition =
+      (segment.kind === 'version' || segment.kind === 'language') && activePagePosition >= 0;
+    const remainingPath = path.slice(segIndex + 1);
+    return {
+      kind: segment.kind,
+      options: (segment.items as NamedContainer[]).map((item, i) => {
+        const isActive = i === segment.index;
+        const equivalentSlug = preservesPosition
+          ? equivalentPageIn(item as Container, remainingPath, activePagePosition)
+          : null;
+        const targetSlug = equivalentSlug ?? firstSlugOf(item as Container) ?? 'index';
+        return {
+          label: labelOf(item),
+          icon: iconOf(item),
+          tag: 'tag' in item ? item.tag : undefined,
+          href: 'href' in item ? item.href : hrefForSlug(targetSlug),
+          active: isActive,
+          dropdown: dropdownMenuOf(item, hrefForSlug, isActive ? path[segIndex + 1] : undefined),
+        };
+      }),
+    };
+  });
+}
+
+// --- Global dropdowns ---------------------------------------------------
+//
+// Unlike path-segment selectors, global dropdowns aren't a mutually
+// exclusive "pick one" choice - `global.dropdowns` is an array where
+// *every* entry renders as its own always-visible trigger button
+// simultaneously (Mintlify's anchors work the same way). A trigger's
+// menu lists its own direct pages as quick links; a bare-href entry is
+// just a plain link with no menu; a deeply-nested entry (tabs/versions/
+// etc. instead of direct pages) falls back to linking straight to its
+// first page, since building a rich flyout for that combination isn't
+// worth the complexity for what's meant to be a quick-links affordance.
+
+export interface GlobalDropdownView {
+  label: string;
+  icon?: string;
+  href: string | null;
+  items: SelectorOption[];
+}
+
+export function buildGlobalDropdowns(
+  dropdowns: DropdownItem[],
+  currentSlug: string,
+  titleForSlug: (slug: string) => string,
+  hrefForSlug: (slug: string) => string
+): GlobalDropdownView[] {
+  return dropdowns.map((d): GlobalDropdownView => {
+    if ('href' in d) {
+      return { label: d.dropdown, icon: d.icon, href: d.href, items: [] };
+    }
+    if ('pages' in d) {
+      const items = flattenNav(d.pages).map((entry) => ({
+        label: titleForSlug(entry.slug),
+        href: hrefForSlug(entry.slug),
+        active: entry.slug === currentSlug,
+      }));
+      return { label: d.dropdown, icon: d.icon, href: null, items };
+    }
+    const slug = firstSlugOf(d);
+    return { label: d.dropdown, icon: d.icon, href: slug ? hrefForSlug(slug) : '#', items: [] };
+  });
+}
+
+// --- Sidebar (recursive) -------------------------------------------------
+
+// A group node's `pageSlug` is the page its own label links to (null if
+// it's a pure disclosure/label with no page of its own - the group only
+// groups). NavTree.astro renders depth-0 groups as static, non-collapsible
+// section titles (linked if `pageSlug` is set, plain text otherwise) and
+// every deeper group as a collapsible row styled like a page item, with a
+// chevron, defaulting open when it contains the active page - see
+// navTreeContainsSlug() below.
+export type NavTreeNode =
+  | { kind: 'page'; slug: string; title: string; method: string | null }
+  | { kind: 'group'; label: string; pageSlug: string | null; children: NavTreeNode[] }
+  | { kind: 'link'; label: string; href: string };
+
+/** Builds the sidebar's view model, preserving group nesting depth.
+ *  `methodForSlug` is optional (most sites have no OpenAPI pages at all)
+ *  and, when given, returns the HTTP method to badge a page with in the
+ *  sidebar (e.g. "GET") or null for an ordinary page - see
+ *  NavTree.astro for how that badge renders. */
+export function buildNavTree(
+  navigation: NavItem[],
+  titleForSlug: (slug: string) => string,
+  methodForSlug?: (slug: string) => string | null
+): NavTreeNode[] {
+  return navigation.map((item): NavTreeNode => {
+    if (typeof item === 'string') {
+      return {
+        kind: 'page',
+        slug: item,
+        title: titleForSlug(item),
+        method: methodForSlug?.(item) ?? null,
+      };
+    }
+    if ('href' in item) {
+      return { kind: 'link', label: item.label, href: item.href };
+    }
+    // loadDocsConfig() always expands `{ group, openapi }` shorthand into
+    // a real `{ group, pages }` before anything reaches here (see
+    // expandOpenApiInNavigation() in the OpenAPI section above) - this is
+    // just a defensive no-op for the shouldn't-happen case of an
+    // unexpanded node reaching the sidebar builder.
+    if ('openapi' in item) {
+      return { kind: 'group', label: item.group, pageSlug: null, children: [] };
+    }
+    return {
+      kind: 'group',
+      label: item.group,
+      pageSlug: item.page ?? null,
+      children: buildNavTree(item.pages, titleForSlug, methodForSlug),
+    };
+  });
+}
+
+/** Whether `slug` is the group's own attached page, or belongs to any page/group nested inside it. */
+export function navTreeContainsSlug(nodes: NavTreeNode[], slug: string): boolean {
+  return nodes.some((node) => {
+    if (node.kind === 'page') return node.slug === slug;
+    if (node.kind === 'link') return false;
+    return node.pageSlug === slug || navTreeContainsSlug(node.children, slug);
+  });
+}
+
+export interface BreadcrumbCrumb {
+  label: string;
+  href: string | null;
+}
+
+/** The chain of ancestor group labels (root first) that `slug` is nested
+ *  under within `nodes` - empty when the page sits at the top level of its
+ *  Section with no enclosing group at all, in which case the caller should
+ *  skip rendering breadcrumbs entirely (there'd be nothing to show but the
+ *  fixed home icon Breadcrumbs.astro always renders first).
+ *
+ *  Deliberately never includes the current page itself - only the groups
+ *  it's nested under (that's already the <h1> right below, repeating it
+ *  in the breadcrumb trail would just be noise). A group whose own
+ *  attached page (`pageSlug`, see NavTreeNode) *is* `slug` is excluded
+ *  from its own trail for the same reason - you're looking at that page,
+ *  it doesn't need to also list itself as its own ancestor. A group only
+ *  appears here when `slug` is nested *inside* it (its own page, if any,
+ *  links to that group's landing page - `href: null` for a label-only
+ *  group with no page of its own to link to). */
+export function ancestorGroupsForSlug(
+  nodes: NavTreeNode[],
+  slug: string,
+  hrefForSlug: (slug: string) => string
+): BreadcrumbCrumb[] {
+  for (const node of nodes) {
+    if (node.kind !== 'group') continue;
+    if (node.pageSlug === slug) return [];
+    if (navTreeContainsSlug(node.children, slug)) {
+      const crumb: BreadcrumbCrumb = { label: node.label, href: node.pageSlug ? hrefForSlug(node.pageSlug) : null };
+      return [crumb, ...ancestorGroupsForSlug(node.children, slug, hrefForSlug)];
+    }
+  }
+  return [];
+}