@writedocs/generator 0.8.1 → 0.9.1

package/src/lib/config-schema.js

@@ -63,6 +63,7 @@ const dropdownSchema = z.lazy(
 const productSchema = z.lazy(
   () => withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
 );
+const MAX_TAB_LEVELS = 2;
 const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
 const navigationSchema = z.union([
   z.array(navItemSchema),
@@ -71,7 +72,39 @@ const navigationSchema = z.union([
   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()
-]);
+]).superRefine((navigation, ctx) => {
+  const CONTAINERS = ["tabs", "versions", "languages", "dropdowns", "products"];
+  const walk = (node, path, language, tabs) => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return;
+    const own = node;
+    for (const key of CONTAINERS) {
+      const items = own[key];
+      if (!Array.isArray(items)) continue;
+      if (key === "languages" && language !== null) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, key],
+          message: `The language "${language}" contains another "languages" list. A page can only be in one language - put the languages at one level, and the rest (tabs, versions, ...) inside each of them.`
+        });
+        continue;
+      }
+      if (key === "tabs" && tabs.length >= MAX_TAB_LEVELS) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, key],
+          message: `Tabs go at most ${MAX_TAB_LEVELS} levels deep, and these are a third level (inside "${tabs.join('" > "')}"). Each level of tabs is a row in the top bar - use a dropdown or groups for this level instead.`
+        });
+        continue;
+      }
+      items.forEach((item, i) => {
+        const inner = key === "languages" ? String(item?.language ?? "") : language;
+        const tab = item?.tab;
+        walk(item, [...path, key, i], inner, key === "tabs" ? [...tabs, String(tab ?? "")] : tabs);
+      });
+    }
+  };
+  walk(navigation, [], null, []);
+});
 const DEFAULT_PRIMARY = "#6366f1";
 const logoSchema = z.union([
   z.string(),
@@ -390,8 +423,9 @@ const apiSchema = z.object({
   // site can set this to `false` to never involve a third party.
   proxy: z.boolean().default(true)
 }).strict().default({ proxy: true });
-const CONTEXT_MENU_OPTIONS = ["copy", "view", "chatgpt", "claude", "perplexity"];
+const CONTEXT_MENU_OPTIONS = ["copy", "view", "chatgpt", "claude", "perplexity", "mcp", "cursor", "vscode"];
 const ASSISTANT_OPTIONS = ["chatgpt", "claude", "perplexity"];
+const MCP_MENU_OPTIONS = ["mcp", "cursor", "vscode"];
 const contextMenuSchema = z.union([
   z.boolean(),
   z.array(z.enum(CONTEXT_MENU_OPTIONS)),
@@ -399,10 +433,11 @@ const contextMenuSchema = z.union([
     openIn: z.array(z.enum(ASSISTANT_OPTIONS)).optional()
   }).strict()
 ]);
-function contextMenuOptions(value) {
+function contextMenuOptions(value, { mcp = true } = {}) {
+  const available = CONTEXT_MENU_OPTIONS.filter((option) => mcp || !MCP_MENU_OPTIONS.includes(option));
   if (value === false) return [];
-  if (value === void 0 || value === null || value === true) return [...CONTEXT_MENU_OPTIONS];
-  if (Array.isArray(value)) return CONTEXT_MENU_OPTIONS.filter((option) => value.includes(option));
+  if (value === void 0 || value === null || value === true) return [...available];
+  if (Array.isArray(value)) return available.filter((option) => value.includes(option));
   if (typeof value === "object") {
     const openIn = value.openIn;
     const assistants = Array.isArray(openIn) ? openIn : [...ASSISTANT_OPTIONS];
@@ -643,6 +678,62 @@ function desembrulharUnioes(issues, prefixo = []) {
   }
   return saida;
 }
+const LISTAS_DE_CONTAINER = ["tabs", "versions", "languages", "dropdowns", "products"];
+const ITENS_DE_CONTAINER = {
+  tab: { lista: "tabs", nome: "A tab" },
+  version: { lista: "versions", nome: "A version" },
+  language: { lista: "languages", nome: "A language" },
+  dropdown: { lista: "dropdowns", nome: "A dropdown" },
+  product: { lista: "products", nome: "A product" }
+};
+function containersEmPaginas(issues, raiz) {
+  const vistos = /* @__PURE__ */ new Set();
+  const saida = [];
+  for (const issue of issues) {
+    const achado = containerEmPaginas(issue.caminho, raiz);
+    if (!achado) {
+      saida.push(issue);
+      continue;
+    }
+    const chave = achado.caminho.join(".");
+    if (vistos.has(chave)) continue;
+    vistos.add(chave);
+    saida.push({ ...issue, code: "custom", caminho: achado.caminho, message: achado.mensagem, keys: void 0 });
+  }
+  return saida;
+}
+function containerEmPaginas(caminho, raiz) {
+  for (let k = 1; k < caminho.length; k++) {
+    if (typeof caminho[k] !== "number") continue;
+    const naRaiz = k === 1 && caminho[0] === "navigation";
+    if (!naRaiz && caminho[k - 1] !== "pages") continue;
+    const item = valorEm(raiz, caminho.slice(0, k + 1));
+    if (!item || typeof item !== "object" || Array.isArray(item) || "group" in item) continue;
+    const lugar = naRaiz ? "the navigation list" : 'a "pages" list';
+    const rotulo = (texto) => (naRaiz ? "The navigation list" : 'A "pages" list') + ` holds pages, groups and links only. ${texto}`;
+    const lista = LISTAS_DE_CONTAINER.find((l) => l in item);
+    if (lista) {
+      return {
+        caminho: caminho.slice(0, k + 1),
+        mensagem: `"${lista}" can't go inside ${lugar}. ` + rotulo(
+          naRaiz ? `To use ${lista}, make "navigation" an object: "navigation": { "${lista}": [ ... ] }, with the groups inside each of them.` : `Put "${lista}" on "navigation" itself, or on a tab, version, language, dropdown or product in place of its "pages".`
+        )
+      };
+    }
+    const tipo = Object.keys(ITENS_DE_CONTAINER).find((t) => t in item);
+    if (tipo) {
+      const { lista: dela, nome } = ITENS_DE_CONTAINER[tipo];
+      const nomeDoItem = item[tipo];
+      return {
+        caminho: caminho.slice(0, k + 1),
+        mensagem: `${nome}${typeof nomeDoItem === "string" ? ` ("${nomeDoItem}")` : ""} can't go inside ${lugar}. ` + rotulo(
+          naRaiz ? `${nome} goes in a "${dela}" list: "navigation": { "${dela}": [ ... ] }.` : `${nome} goes in a "${dela}" list.`
+        )
+      };
+    }
+  }
+  return null;
+}
 function createJsonLocator(rawText) {
   return criarLocalizador(rawText);
 }
@@ -830,7 +921,7 @@ function validateDocsConfig(rawText) {
       ok: false,
       data: null,
       kind: "schema",
-      issues: desembrulharUnioes(result.error.issues).map((i) => {
+      issues: containersEmPaginas(desembrulharUnioes(result.error.issues), raw).map((i) => {
         const alvoDaLinha = i.code === "unrecognized_keys" && i.keys?.length ? [...i.caminho, i.keys[0]] : i.caminho;
         return {
           path: i.caminho.join(".") || "(root)",
@@ -847,6 +938,8 @@ function validateDocsConfig(rawText) {
 }
 export {
   CONTEXT_MENU_OPTIONS,
+  MAX_TAB_LEVELS,
+  MCP_MENU_OPTIONS,
   ROOT_ALLOWED_EXTRA_KEYS,
   contextMenuOptions,
   createJsonLocator,

package/src/lib/config-schema.ts

@@ -207,6 +207,9 @@ export type NavigationConfig =
   | { global?: { dropdowns: DropdownItem[] }; dropdowns: DropdownItem[] }
   | { global?: { dropdowns: DropdownItem[] }; products: ProductItem[] };
 
+/** Levels of tabs a page can sit under - one row of the top bar each. */
+export const MAX_TAB_LEVELS = 2;
+
 const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
 
 const navigationSchema = z.union([
@@ -216,7 +219,42 @@ const navigationSchema = z.union([
   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>;
+]).superRefine((navigation, ctx) => {
+  // Every page under a language is in that language - a second `languages`
+  // inside it would make a page two languages at once. And tabs take a row
+  // of the top bar per level: two levels at most (TopBar.astro).
+  const CONTAINERS = ['tabs', 'versions', 'languages', 'dropdowns', 'products'] as const;
+  const walk = (node: unknown, path: (string | number)[], language: string | null, tabs: string[]) => {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+    const own = node as Record<string, unknown>;
+    for (const key of CONTAINERS) {
+      const items = own[key];
+      if (!Array.isArray(items)) continue;
+      if (key === 'languages' && language !== null) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [...path, key],
+          message: `The language "${language}" contains another "languages" list. A page can only be in one language - put the languages at one level, and the rest (tabs, versions, ...) inside each of them.`,
+        });
+        continue;
+      }
+      if (key === 'tabs' && tabs.length >= MAX_TAB_LEVELS) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [...path, key],
+          message: `Tabs go at most ${MAX_TAB_LEVELS} levels deep, and these are a third level (inside "${tabs.join('" > "')}"). Each level of tabs is a row in the top bar - use a dropdown or groups for this level instead.`,
+        });
+        continue;
+      }
+      items.forEach((item, i) => {
+        const inner = key === 'languages' ? String((item as { language?: unknown })?.language ?? '') : language;
+        const tab = (item as { tab?: unknown })?.tab;
+        walk(item, [...path, key, i], inner, key === 'tabs' ? [...tabs, String(tab ?? '')] : tabs);
+      });
+    }
+  };
+  walk(navigation, [], null, []);
+}) as z.ZodType<NavigationConfig>;
 
 const DEFAULT_PRIMARY = '#6366f1';
 
@@ -734,15 +772,21 @@ const apiSchema = z
 //
 //   (absent) or true         every option
 //   ["copy", "claude"]       only these, in the menu's own order
+//                            (copy, view, chatgpt, claude, perplexity,
+//                            mcp, cursor, vscode - the last three connect
+//                            AI tools to the site's MCP server, and are
+//                            left out when `mcp` is false)
 //   false (or [])            no menu, and no .md routes
 //   { "openIn": [...] }      the earlier form: copy and view, plus these
 //                            assistants - still accepted
 //
 // Read it through contextMenuOptions() below - never test the raw value for
 // truthiness: absent now means on.
-export const CONTEXT_MENU_OPTIONS = ['copy', 'view', 'chatgpt', 'claude', 'perplexity'] as const;
+export const CONTEXT_MENU_OPTIONS = ['copy', 'view', 'chatgpt', 'claude', 'perplexity', 'mcp', 'cursor', 'vscode'] as const;
 export type ContextMenuOption = (typeof CONTEXT_MENU_OPTIONS)[number];
 const ASSISTANT_OPTIONS = ['chatgpt', 'claude', 'perplexity'] as const;
+/** The options that point at the site's MCP server - see `mcp` below. */
+export const MCP_MENU_OPTIONS = ['mcp', 'cursor', 'vscode'] as const;
 
 const contextMenuSchema = z.union([
   z.boolean(),
@@ -758,11 +802,13 @@ export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
 
 /** The menu options a writedocs.json `contextMenu` value turns on, in menu
  *  order - [] when the menu is off. Takes the raw value too (link-check.js
- *  reads writedocs.json without the schema), so absent means every option. */
-export function contextMenuOptions(value: unknown): ContextMenuOption[] {
+ *  reads writedocs.json without the schema), so absent means every option.
+ *  With `mcp: false` (no MCP server), the MCP options are left out. */
+export function contextMenuOptions(value: unknown, { mcp = true }: { mcp?: boolean } = {}): ContextMenuOption[] {
+  const available = CONTEXT_MENU_OPTIONS.filter((option) => mcp || !(MCP_MENU_OPTIONS as readonly string[]).includes(option));
   if (value === false) return [];
-  if (value === undefined || value === null || value === true) return [...CONTEXT_MENU_OPTIONS];
-  if (Array.isArray(value)) return CONTEXT_MENU_OPTIONS.filter((option) => value.includes(option));
+  if (value === undefined || value === null || value === true) return [...available];
+  if (Array.isArray(value)) return available.filter((option) => value.includes(option));
   if (typeof value === 'object') {
     const openIn = (value as { openIn?: unknown }).openIn;
     const assistants = Array.isArray(openIn) ? openIn : [...ASSISTANT_OPTIONS];
@@ -1337,6 +1383,73 @@ function desembrulharUnioes(issues: IssueCru[], prefixo: (string | number)[] = [
   return saida;
 }
 
+const LISTAS_DE_CONTAINER = ['tabs', 'versions', 'languages', 'dropdowns', 'products'] as const;
+const ITENS_DE_CONTAINER: Record<string, { lista: string; nome: string }> = {
+  tab: { lista: 'tabs', nome: 'A tab' },
+  version: { lista: 'versions', nome: 'A version' },
+  language: { lista: 'languages', nome: 'A language' },
+  dropdown: { lista: 'dropdowns', nome: 'A dropdown' },
+  product: { lista: 'products', nome: 'A product' },
+};
+
+/** Um container (`{ "tabs": [...] }`, ou um item como `{ "tab": "API", ... }`)
+ *  dentro de uma lista de paginas - o `pages` de um grupo, de uma tab etc., ou
+ *  a `navigation` em forma de lista. O Zod tenta os tres formatos de item
+ *  (pagina, grupo, link) e reclama de cada um: "group is required", "pages is
+ *  required", "tabs is not an option" - tres erros, nenhum dizendo o que houve.
+ *  Aqui eles viram UM, no item, dizendo onde o container pode ficar. */
+function containersEmPaginas(issues: IssuePlano[], raiz: unknown): IssuePlano[] {
+  const vistos = new Set<string>();
+  const saida: IssuePlano[] = [];
+  for (const issue of issues) {
+    const achado = containerEmPaginas(issue.caminho, raiz);
+    if (!achado) {
+      saida.push(issue);
+      continue;
+    }
+    const chave = achado.caminho.join('.');
+    if (vistos.has(chave)) continue;
+    vistos.add(chave);
+    saida.push({ ...issue, code: 'custom', caminho: achado.caminho, message: achado.mensagem, keys: undefined });
+  }
+  return saida;
+}
+
+function containerEmPaginas(caminho: (string | number)[], raiz: unknown): { caminho: (string | number)[]; mensagem: string } | null {
+  for (let k = 1; k < caminho.length; k++) {
+    if (typeof caminho[k] !== 'number') continue;
+    const naRaiz = k === 1 && caminho[0] === 'navigation';
+    if (!naRaiz && caminho[k - 1] !== 'pages') continue;
+    const item = valorEm(raiz, caminho.slice(0, k + 1));
+    if (!item || typeof item !== 'object' || Array.isArray(item) || 'group' in item) continue;
+    const lugar = naRaiz ? 'the navigation list' : 'a "pages" list';
+    const rotulo = (texto: string) => (naRaiz ? 'The navigation list' : 'A "pages" list') + ` holds pages, groups and links only. ${texto}`;
+    const lista = LISTAS_DE_CONTAINER.find((l) => l in item);
+    if (lista) {
+      return {
+        caminho: caminho.slice(0, k + 1),
+        mensagem: `"${lista}" can't go inside ${lugar}. ` + rotulo(
+          naRaiz
+            ? `To use ${lista}, make "navigation" an object: "navigation": { "${lista}": [ ... ] }, with the groups inside each of them.`
+            : `Put "${lista}" on "navigation" itself, or on a tab, version, language, dropdown or product in place of its "pages".`
+        ),
+      };
+    }
+    const tipo = Object.keys(ITENS_DE_CONTAINER).find((t) => t in item);
+    if (tipo) {
+      const { lista: dela, nome } = ITENS_DE_CONTAINER[tipo];
+      const nomeDoItem = (item as Record<string, unknown>)[tipo];
+      return {
+        caminho: caminho.slice(0, k + 1),
+        mensagem: `${nome}${typeof nomeDoItem === 'string' ? ` ("${nomeDoItem}")` : ''} can't go inside ${lugar}. ` + rotulo(
+          naRaiz ? `${nome} goes in a "${dela}" list: "navigation": { "${dela}": [ ... ] }.` : `${nome} goes in a "${dela}" list.`
+        ),
+      };
+    }
+  }
+  return null;
+}
+
 /** Exported for `writedocs validate`'s content pass (lib/content-check.js),
  *  which reports writedocs.json problems of its own - navigation entries
  *  with no page, unknown icons - with the same line numbers as the schema
@@ -1589,7 +1702,7 @@ export function validateDocsConfig(rawText: string): ValidationResult {
       ok: false,
       data: null,
       kind: 'schema',
-      issues: desembrulharUnioes(result.error.issues as IssueCru[]).map((i) => {
+      issues: containersEmPaginas(desembrulharUnioes(result.error.issues as IssueCru[]), raw).map((i) => {
         // Para chave desconhecida o `path` do Zod aponta pro PAI (`footer`), e a
         // chave ofensora vem em `keys`. Para a LINHA vale a pena descer ate ela
         // (`footer.banana`), que e onde o cliente precisa olhar; o `path` fica

package/src/lib/config.ts

@@ -909,6 +909,9 @@ export interface SelectorOption {
   label: string;
   icon?: string;
   tag?: string;
+  // A product's `description` - shown under its name where there's room
+  // (the sidebar's product switcher, see lib/selector-placement.js).
+  description?: string;
   href: string;
   active: boolean;
   // Set when this option's own container is a `dropdowns` list (e.g. a
@@ -976,6 +979,7 @@ export function buildSelectors(
           label: labelOf(item),
           icon: iconOf(item),
           tag: 'tag' in item ? item.tag : undefined,
+          description: 'description' in item ? item.description : undefined,
           href: 'href' in item ? item.href : hrefForSlug(targetSlug),
           active: isActive,
           dropdown: dropdownMenuOf(item, hrefForSlug, isActive ? path[segIndex + 1] : undefined),

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

@@ -164,7 +164,7 @@ export const DESCRIPTIONS = {
   'seo.twitterCard': 'X/Twitter card style. Default "summary_large_image" with an `ogImage`, "summary" without.',
   'seo.keywords': 'Keywords for the <meta name="keywords"> tag.',
   'seo.noindex': 'Ask search engines not to index pages, and leave them out of sitemap.xml.',
-  contextMenu: 'The "Copy page" menu on every page - copy as Markdown, view as Markdown, open in ChatGPT, Claude or Perplexity - and a Markdown copy of each page at its address + ".md". On by default with every option. A list picks the options ("copy", "view", "chatgpt", "claude", "perplexity"); false turns it all off.',
+  contextMenu: 'The "Copy page" menu on every page - copy as Markdown, view as Markdown, open in ChatGPT, Claude or Perplexity, copy the MCP server URL, connect to Cursor or VS Code - and a Markdown copy of each page at its address + ".md". On by default with every option (the MCP ones only while `mcp` is on). A list picks the options ("copy", "view", "chatgpt", "claude", "perplexity", "mcp", "cursor", "vscode"); false turns it all off.',
   'contextMenu.openIn': 'The earlier form: which AI assistants the menu offers, besides copy and view. A list of options replaces it.',
   mcp: 'An MCP server at /mcp, so AI tools can search and read the docs. The build adds its index and a Cloudflare-ready _worker.js to dist/. Default true; false leaves them out.',
   redirects: 'Redirects from old addresses. Each matches one exact path.',

package/src/lib/mcp-links.js

@@ -0,0 +1,30 @@
+// The "Copy page" menu's MCP options (CopyPageMenu.astro): the site's MCP
+// server address, and the links that add it to Cursor and to VS Code. Used
+// at build time when writedocs.json has a `domain`, and in the browser
+// (from the page's own address) when it doesn't - so plain functions, no
+// Node APIs.
+
+/** The site's MCP server - served at /mcp (see docs/dev/docs/mcp.mdx). */
+export function mcpServerUrl(origin) {
+  return `${String(origin).replace(/\/+$/, '')}/mcp`;
+}
+
+function base64(text) {
+  // UTF-8 first, so a site name with accents survives btoa().
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Cursor's install link: the server's name, and its config as base64 JSON
+ *  (https://docs.cursor.com/deeplinks). */
+export function cursorInstallLink(name, url) {
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(name)}&config=${encodeURIComponent(base64(JSON.stringify({ url })))}`;
+}
+
+/** VS Code's install link: the server's config as URL-encoded JSON
+ *  (https://code.visualstudio.com/docs/copilot/chat/mcp-servers). */
+export function vscodeInstallLink(name, url) {
+  return `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name, type: 'http', url }))}`;
+}

package/src/lib/mintlify-convert.js

@@ -530,16 +530,16 @@ export function convertMintlifyConfig(docs) {
   if (docs.seo?.indexing === 'all') notes.add('seo.indexing', ['seo', 'indexing'], '`seo.indexing: "all"` has no equivalent - writedocs indexes every page that isn\'t marked noindex.');
 
   // context menu
-  // Mintlify's option names are writedocs' own for the five both have, so the
-  // list carries over as is. No `contextual` leaves the field out - the menu
-  // is on by default, with every option.
+  // Mintlify's option names are writedocs' own for the eight both have, so
+  // the list carries over as is. No `contextual` leaves the field out - the
+  // menu is on by default, with every option.
   const options = docs.contextual?.options;
   if (Array.isArray(options) && options.length) {
-    const known = ['copy', 'view', 'chatgpt', 'claude', 'perplexity'];
+    const known = ['copy', 'view', 'chatgpt', 'claude', 'perplexity', 'mcp', 'cursor', 'vscode'];
     out.contextMenu = known.filter((o) => options.includes(o));
     const other = options.filter((o) => typeof o !== 'string' || !known.includes(o));
     if (other.length) {
-      notes.add('contextual', ['contextual', 'options'], `Context menu options writedocs doesn't have were dropped: ${other.map((o) => (typeof o === 'string' ? o : o.title ?? 'custom')).join(', ')}.`, 'writedocs\' page menu offers copy, view as Markdown, and open in ChatGPT, Claude and Perplexity.');
+      notes.add('contextual', ['contextual', 'options'], `Context menu options writedocs doesn't have were dropped: ${other.map((o) => (typeof o === 'string' ? o : o.title ?? 'custom')).join(', ')}.`, 'writedocs\' page menu offers copy, view as Markdown, open in ChatGPT, Claude and Perplexity, and the MCP server: copy its URL, connect to Cursor or VS Code.');
     }
   }
 

package/src/lib/search-scope.js

@@ -0,0 +1,44 @@
+// What search knows about a page beyond its text: where it sits (the
+// section line under a result's title, and words a search can match - a
+// page under the "Webhooks" tab is found by "webhooks"), and which version,
+// language and product it belongs to (search shows those of the page the
+// reader is on, with a way to search everything). Built from a Section's
+// `path` (resolveSections() in lib/config.ts) and the page's breadcrumb
+// groups. src/scripts/search.ts reads both back.
+
+/** Every page outside any version, language and product - shown whatever
+ *  the reader is on. */
+export const ALL_SCOPES = 'all';
+
+const SCOPE_KINDS = { version: 'version', language: 'language', product: 'product' };
+
+function segmentValue(segment) {
+  const item = segment.items[segment.index] ?? {};
+  switch (segment.kind) {
+    case 'tab': return { id: item.tab, label: item.tab };
+    case 'dropdown': return { id: item.dropdown, label: item.dropdown };
+    case 'product': return { id: item.product, label: item.product };
+    case 'version': return { id: item.version, label: item.label ?? item.version };
+    case 'language': return { id: item.language, label: item.label ?? item.language };
+    default: return { id: '', label: '' };
+  }
+}
+
+/** `key` - the same for every page of one version/language/product
+ *  combination; `label` - how the search box names it ("v2 · English"). */
+export function searchScope(path = []) {
+  const parts = path.filter((s) => s.kind in SCOPE_KINDS).map((s) => ({ kind: s.kind, ...segmentValue(s) }));
+  if (parts.length === 0) return { key: ALL_SCOPES, label: '' };
+  return {
+    // Pagefind's `data-pagefind-filter="scope:..."` reads a comma as the next
+    // filter and the first colon as the end of the name.
+    key: parts.map((p) => `${p.kind}=${String(p.id).replace(/[,:]/g, '_')}`).join('/'),
+    label: parts.map((p) => p.label).join(' · '),
+  };
+}
+
+/** "API Reference › Webhooks › Events group": every level above the page,
+ *  navigation containers first, then its groups. */
+export function sectionTrail(path = [], groups = []) {
+  return [...path.map((s) => segmentValue(s).label), ...groups.map((g) => g.label)].filter(Boolean).join(' › ');
+}

package/src/lib/selector-placement.js

@@ -0,0 +1,30 @@
+// Where each level of a page's navigation path shows its switcher - one
+// entry per Selector (buildSelectors() in lib/config.ts), root first:
+//
+//   'tabs'      a row of tabs in the top bar (a second row for tabs inside tabs)
+//   'tab-menu'  the menu of the tab it sits in (dropdowns directly inside a tab)
+//   'sidebar'   the top of the sidebar: products inside a tab or a dropdown,
+//               like Mintlify's - they pick what the sidebar shows
+//   'topbar'    a switcher next to the site name (everything else)
+//
+// Without a sidebar on the page (`mode: custom` / `blank`), a 'sidebar'
+// switcher goes to the top bar instead. The mobile menu lists every level
+// either way.
+
+export function selectorPlacements(selectors, { sidebar = true } = {}) {
+  return selectors.map((sel, i) => {
+    const parent = selectors[i - 1]?.kind;
+    if (sel.kind === 'tab') return 'tabs';
+    if (sel.kind === 'dropdown' && parent === 'tab') return 'tab-menu';
+    if (sel.kind === 'product' && (parent === 'tab' || parent === 'dropdown')) return sidebar ? 'sidebar' : 'topbar';
+    return 'topbar';
+  });
+}
+
+/** Whether a page gets the mobile menu (its button in the top bar, and the
+ *  panel - TopBar.astro and MobileMenu.astro both ask this). On a phone the
+ *  top bar hides the tabs and switchers, so any page with navigation to
+ *  reach needs it - with a sidebar or without (`mode: custom`). */
+export function hasMobileMenu({ sidebar, selectors = [], globalDropdowns = [] }) {
+  return sidebar || selectors.length > 0 || globalDropdowns.length > 0;
+}

package/src/lib/tabs-strip-offset.js

@@ -0,0 +1,31 @@
+// The arithmetic behind a tab row that slides sideways (src/scripts/
+// tabs-strip.ts), kept apart from the DOM so it can be tested. Every
+// value is in pixels: `offset` is how far the row is slid to the left,
+// `view` the visible width, `track` the width of all the tabs together,
+// and `edge` how much of each end an arrow covers when it shows.
+
+/** How far the row can slide: 0 when every tab fits. */
+export function maxOffset(track, view) {
+  return Math.max(0, Math.round(track - view));
+}
+
+export function clampOffset(offset, max) {
+  return Math.min(Math.max(0, offset), max);
+}
+
+/** One arrow click: close to a whole visible width, minus what the arrows
+ *  cover, so the tab cut off at the edge becomes the first one shown. */
+export function stepOffset(offset, direction, { view, max, edge }) {
+  const distance = Math.max(view - 2 * edge, view / 2);
+  return clampOffset(offset + direction * distance, max);
+}
+
+/** The offset that shows the item spanning `start`..`end` (measured from the
+ *  row's own left edge) clear of the arrows, moving as little as possible.
+ *  An item wider than the space shows from its start. */
+export function revealOffset(offset, start, end, { view, max, edge }) {
+  let next = offset;
+  if (end > offset + view - edge) next = end - view + edge;
+  if (start < next + edge) next = start - edge;
+  return clampOffset(next, max);
+}

package/src/lib/writedocs-temp-dir.js

@@ -1,6 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { canonicalPath } from './canonical-path.js';
 
 /** Where writedocs' own generated/cached artifacts for a given content
  *  directory live: Astro's content-layer cache (`cacheDir`), the
@@ -36,7 +37,8 @@ import crypto from 'node:crypto';
  *  - all of them need to agree on the identical path, since one writes
  *  what another reads. */
 function namespaceLabel(contentDir) {
-  const resolved = path.resolve(contentDir);
+  // `c:\docs` and `C:\docs` are one project - one directory.
+  const resolved = canonicalPath(path.resolve(contentDir));
   const hash = crypto.createHash('sha1').update(resolved).digest('hex').slice(0, 12);
   const label = path.basename(resolved) || 'root';
   return `${label}-${hash}`;