@writedocs/generator 0.8.0 → 0.9.0

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';
 
@@ -727,25 +765,58 @@ const apiSchema = z
   .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();
+// The "Copy page" menu shown next to a page's title - copy the page's
+// Markdown, view it, or open it in an AI assistant - and the .md copy of
+// every page it relies on ([...slug].md.ts). On by default, with every
+// option, like the MCP server. writedocs.json narrows or turns it off:
+//
+//   (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', '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(),
+  z.array(z.enum(CONTEXT_MENU_OPTIONS)),
+  z
+    .object({
+      openIn: z.array(z.enum(ASSISTANT_OPTIONS)).optional(),
+    })
+    .strict(),
+]);
 
 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.
+ *  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 [...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];
+    return CONTEXT_MENU_OPTIONS.filter((option) => option === 'copy' || option === 'view' || assistants.includes(option));
+  }
+  return [];
+}
+
 // 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
@@ -996,8 +1067,8 @@ export const docsConfigSchema = z.object({
   // 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).
+  // The "Copy page" menu - see contextMenuSchema above. Absent means on,
+  // with every option; read it through contextMenuOptions().
   contextMenu: contextMenuSchema.optional(),
   // The site's MCP server - an AI tool connects to `/mcp` and searches and
   // reads the docs. On by default: `writedocs build` writes the page index
@@ -1312,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
@@ -1564,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/content-check.js

@@ -434,6 +434,21 @@ export async function checkContent(contentDir, configText) {
       const { message, suggestion } = unknownIconMessage(icon);
       warnings.push(issue('writedocs.json', locate(jsonPath)?.line, message, suggestion));
     }
+    // No `domain`: the site builds, but everything that needs its full
+    // address goes without - flagged so it's a choice, not a surprise.
+    if (typeof config.domain !== 'string' || !config.domain.trim()) {
+      // `code` lets `writedocs convert` leave it out - it gives its own
+      // domain hint, with where the source tool kept that setting.
+      warnings.push({
+        code: 'no-domain',
+        ...issue(
+          'writedocs.json',
+          undefined,
+          'No "domain" set - there\'s no sitemap.xml, and llms.txt, the MCP server\'s page URLs and the "Open in…" links in the page menu use relative addresses or the address the page is opened from.',
+          'Set "domain" to the site\'s address, like "docs.example.com".'
+        ),
+      });
+    }
   }
   await checkOpenApi(contentDir, config, config ? createJsonLocator(configText) : null, openapiRefs, errors, warnings);
 

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

@@ -164,8 +164,8 @@ 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: 'Adds a "Copy page" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + ".md".',
-  'contextMenu.openIn': 'Which AI assistants the menu offers. Default: all three.',
+  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.',
   'redirects[].source': 'The old path, like "/old-page".',

package/src/lib/link-check.js

@@ -33,7 +33,7 @@ import { pathToFileURL } from 'node:url';
 import matter from 'gray-matter';
 import { visit } from 'unist-util-visit';
 import { findAllPages } from './pages.js';
-import { createJsonLocator } from './config-schema.js';
+import { createJsonLocator, contextMenuOptions } from './config-schema.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
 
 // The same github-slugger Astro builds page URLs and heading ids with -
@@ -423,7 +423,7 @@ export async function checkLinks(contentDir, configText) {
     // A link to a page's source file (docs/setup.mdx) instead of its URL.
     if (extension === '.mdx' || extension === '.md') {
       const bare = pathname.replace(/\.mdx?$/i, '').replace(/\/?$/, '/');
-      if (extension === '.md' && config.contextMenu && pages.has(bare)) return; // the page's Markdown copy
+      if (extension === '.md' && contextMenuOptions(config.contextMenu).length && pages.has(bare)) return; // the page's Markdown copy (on unless "contextMenu": false)
       // Written as a file path, so look it up as one: from the file's own
       // folder when relative.
       const filePath = isRelative && fileAbs ? path.resolve(path.dirname(fileAbs), decodeURI(value.split(/[?#]/)[0])) : path.join(contentDir, pathname);

package/src/lib/llms-index.ts

@@ -6,7 +6,7 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl, fileIdForEntry } from './config';
+import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl, fileIdForEntry, contextMenuOptions } from './config';
 import { buildLlmsTree, renderLlmsFiles } from './llms.js';
 import { navigationPageOrder } from './pages.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
@@ -59,10 +59,10 @@ export async function llmsIndexFiles(): Promise<Map<string, string> | null> {
     // page (Mintlify's external link) has no content of its own.
     if (entry.data.seo?.noindex || entry.data.url) continue;
     const slug = normalizeEntryId(entry.id);
-    // The .md route when it exists ([...slug].md.ts - with `contextMenu`,
+    // The .md route when it exists ([...slug].md.ts - unless `contextMenu` is off,
     // and never for an OpenAPI page, which renders from the spec), else the
     // HTML page.
-    const hasMarkdownRoute = config.contextMenu && !entry.data.openapi;
+    const hasMarkdownRoute = contextMenuOptions(config.contextMenu).length > 0 && !entry.data.openapi;
     const href = (siteUrl ?? '') + (hasMarkdownRoute ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`);
     let description = truncateDescription(entry.data.description);
     // Mirrors Mintlify: an OpenAPI operation page's description gets its

package/src/lib/mcp-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,13 +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 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 openIn = options.filter((o) => ['chatgpt', 'claude', 'perplexity'].includes(o));
-    out.contextMenu = { openIn };
-    const other = options.filter((o) => typeof o !== 'string' || !['copy', 'view', 'chatgpt', 'claude', 'perplexity'].includes(o));
+    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 always has copy and view-as-Markdown, plus 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/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}`;

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

@@ -16,6 +16,7 @@ import {
   flattenNav,
   firstSlugOfNavigation,
   mergeSeo,
+  contextMenuOptions,
   resolveSiteUrl,
   findAllPages,
 } from "../lib/config";
@@ -68,6 +69,7 @@ import Visibility from "../components/Visibility.astro";
 import { Tree, FileTree, Color, GitHub } from "../components/compound";
 import ApiPlayground from "../components/ApiPlayground.astro";
 import ApiReferencePanel from "../components/ApiReferencePanel.astro";
+import { searchScope, sectionTrail, ALL_SCOPES } from "../lib/search-scope.js";
 
 // A page is hand-written (the `pages` collection, sourced from anywhere
 // in the project - docs/ has no special status, see findAllPages() in
@@ -372,6 +374,11 @@ const selectors = buildSelectors(activeSection.path, hrefForSlug, activePagePosi
 // <html lang>: the `language` of the navigation level this page sits under,
 // if any. A hidden page has no level of its own (activeSection is only a
 // fallback for its chrome), so it keeps the default.
+// For search: the section line under this page's result (and words it can
+// be found by), and the version/language/product it belongs to - search
+// shows the reader's own first. A hidden page belongs to no section.
+const pageSearchScope = isHidden ? { key: ALL_SCOPES, label: "" } : searchScope(activeSection.path);
+const pageSectionTrail = isHidden ? "" : sectionTrail(activeSection.path, breadcrumbs);
 const languageSegment = isHidden ? undefined : activeSection.path.find((segment) => segment.kind === "language");
 const pageLang = languageSegment ? (languageSegment.items[languageSegment.index] as { language: string }).language : undefined;
 const globalDropdowns = buildGlobalDropdowns(
@@ -414,8 +421,9 @@ const showToc = pageMode === "default";
 // branch on separately.
 const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 
-// The "Copy page" dropdown (CopyPageMenu.astro) - opt-in via writedocs.json's
-// `contextMenu` field (see contextMenuSchema in lib/config.ts), and only
+// The "Copy page" menu (CopyPageMenu.astro) - on by default, with the
+// options writedocs.json's `contextMenu` leaves on (contextMenuOptions() in
+// lib/config-schema.ts; `false` turns it off), and only
 // shown where there's a real auto-rendered <h1> to sit next to: canvas
 // mode pages (custom/blank) have no such header (a hand-built landing
 // page controls its own layout, there's nothing standard to anchor the
@@ -423,7 +431,8 @@ const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 // spec rather than prose - see [...slug].md.ts's own comment on why
 // those are excluded from the .md route this menu links to in the first
 // place, which this mirrors on the UI side.
-const showCopyPageMenu = Boolean(config.contextMenu) && !isCanvasMode && !entry.data.openapi;
+const contextMenuItems = contextMenuOptions(config.contextMenu, { mcp: config.mcp });
+const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode && !entry.data.openapi;
 const siteUrl = resolveSiteUrl(config);
 
 const components = {
@@ -495,6 +504,11 @@ const components = {
       <div class="wd-canvas" data-pagefind-body>
         <Content components={components} />
         {entry.data.openapi && <ApiPlayground operation={entry.data.openapi} contentDir={contentDir} />}
+        {/* After the content: a result's excerpt shows the section only when
+            that's what matched. */}
+        <div hidden data-wd-search-scope={pageSearchScope.key} data-wd-search-scope-label={pageSearchScope.label} data-pagefind-filter={`scope:${pageSearchScope.key}`}>
+          {pageSectionTrail && <span data-pagefind-meta="section">{pageSectionTrail}</span>}
+        </div>
       </div>
     ) : (
       <article class={`wd-article ${pageMode === "wide" ? "wd-article-wide" : ""}`} data-pagefind-body>
@@ -513,11 +527,14 @@ const components = {
             )
           }
           {showCopyPageMenu && (
-            <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} contextMenu={config.contextMenu!} />
+            <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} siteName={config.name} options={contextMenuItems} />
           )}
         </div>
         <Content components={components} />
         {entry.data.openapi && <ApiPlayground operation={entry.data.openapi} contentDir={contentDir} />}
+        <div hidden data-wd-search-scope={pageSearchScope.key} data-wd-search-scope-label={pageSearchScope.label} data-pagefind-filter={`scope:${pageSearchScope.key}`}>
+          {pageSectionTrail && <span data-pagefind-meta="section">{pageSectionTrail}</span>}
+        </div>
         {!entry.data.hideFooterPagination && (
         <nav class="wd-prevnext" data-pagefind-ignore>
           {prev && (
@@ -582,6 +599,8 @@ const components = {
 </BaseLayout>
 
 <script>
+  import { mcpServerUrl, cursorInstallLink, vscodeInstallLink } from "../lib/mcp-links.js";
+
   // Astro assigns every h2-h4 an id automatically, but doesn't add a
   // clickable anchor next to it. rehype-autolink-headings can't be used
   // for this directly: Astro's own heading-id rehype plugin always runs
@@ -645,7 +664,7 @@ const components = {
   // isn't otherwise present in the DOM anywhere (the rendered HTML
   // content is not the same text).
   function initCopyPageMenu(root: ParentNode) {
-    root.querySelectorAll<HTMLButtonElement>(".wd-copy-page-primary").forEach((btn) => {
+    root.querySelectorAll<HTMLButtonElement>("button[data-copy-page]").forEach((btn) => {
       if (btn.dataset.wdInit) return;
       btn.dataset.wdInit = "true";
       const label = btn.querySelector<HTMLElement>(".wd-copy-page-primary-label");
@@ -672,6 +691,53 @@ const components = {
   initCopyPageMenu(document);
   document.addEventListener("astro:page-load", () => initCopyPageMenu(document));
 
+  // "Open in ChatGPT/Claude/Perplexity" on a site with no writedocs.json
+  // `domain`: the page's absolute .md URL isn't known at build time, so the
+  // link is completed here from the address the page is served from (see
+  // CopyPageMenu.astro) - same prompt the build writes when it does know.
+  function initAskLinks(root: ParentNode) {
+    root.querySelectorAll<HTMLAnchorElement>("a[data-ask-base][data-md-path]").forEach((link) => {
+      const url = new URL(link.dataset.mdPath ?? "/", window.location.origin).href;
+      link.href = link.dataset.askBase + encodeURIComponent(`Read ${url} so you can answer questions about it.`);
+    });
+  }
+  initAskLinks(document);
+  document.addEventListener("astro:page-load", () => initAskLinks(document));
+
+  // The menu's MCP options (CopyPageMenu.astro). "Copy MCP server URL"
+  // copies it and says so in its own label - inside the menu, which stays
+  // open to show it. "Connect to Cursor / VS Code" on a site with no
+  // `domain` get their install links here, for the address the page is
+  // served from.
+  function initMcpMenu(root: ParentNode) {
+    const serverUrl = (el: HTMLElement) => el.dataset.copyMcp || mcpServerUrl(window.location.origin);
+    root.querySelectorAll<HTMLButtonElement>("button[data-copy-mcp]").forEach((btn) => {
+      if (btn.dataset.wdInit) return;
+      btn.dataset.wdInit = "true";
+      const label = btn.querySelector<HTMLElement>(".wd-copy-page-item-title, .wd-copy-page-primary-label");
+      const originalLabel = label?.textContent ?? "";
+      btn.addEventListener("click", async (e) => {
+        e.stopPropagation();
+        try {
+          await navigator.clipboard.writeText(serverUrl(btn));
+        } catch {
+          return;
+        }
+        if (label) label.textContent = "Copied!";
+        window.setTimeout(() => {
+          if (label) label.textContent = originalLabel;
+        }, 1500);
+      });
+    });
+    root.querySelectorAll<HTMLAnchorElement>("a[data-mcp-install]").forEach((link) => {
+      const url = mcpServerUrl(window.location.origin);
+      const name = link.dataset.mcpName ?? document.title;
+      link.href = link.dataset.mcpInstall === "cursor" ? cursorInstallLink(name, url) : vscodeInstallLink(name, url);
+    });
+  }
+  initMcpMenu(document);
+  document.addEventListener("astro:page-load", () => initMcpMenu(document));
+
   // Show more/less toggle for ```js expandable code blocks - same
   // build-time-emitted-button + client-wired-click pattern as the copy
   // button above; codeBlockTransformer only adds this button when the
@@ -845,7 +911,7 @@ const components = {
     width: 100%;
   }
   /* Wraps the auto-rendered <h1> together with CopyPageMenu (only
-     rendered when writedocs.json's `contextMenu` is set - see
+     rendered when writedocs.json's `contextMenu` isn't off - see
      showCopyPageMenu above) so the two sit on one row, menu pinned to
      the right. Always present (even with no menu) rather than only
      wrapping the <h1> conditionally, so the <h1>'s own top/bottom