@writedocs/generator 0.8.1 → 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';
 
@@ -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/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/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

@@ -69,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
@@ -373,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(
@@ -425,7 +431,7 @@ 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 contextMenuItems = contextMenuOptions(config.contextMenu);
+const contextMenuItems = contextMenuOptions(config.contextMenu, { mcp: config.mcp });
 const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode && !entry.data.openapi;
 const siteUrl = resolveSiteUrl(config);
 
@@ -498,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>
@@ -516,11 +527,14 @@ const components = {
             )
           }
           {showCopyPageMenu && (
-            <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} options={contextMenuItems} />
+            <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 && (
@@ -585,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
@@ -648,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");
@@ -688,6 +704,40 @@ const components = {
   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

package/src/scripts/dropdowns.ts

@@ -4,56 +4,91 @@
 // written for the topbar's own switcher/tab dropdowns, but the same
 // `.wd-dropdown`/`.wd-dropdown-trigger`/`.wd-dropdown-menu`/
 // `.wd-dropdown-menu-panel` shape is now reused by TopBar.astro (switchers,
-// tabs, the small-screen topbar.links ellipsis) and CopyPageMenu.astro, and
-// exported from here so any future component - MobileMenu.astro included,
-// even though it doesn't render any `.wd-dropdown` markup today - can import
-// and call it too without needing to know whether some other component
-// already has.
+// tabs, the small-screen topbar.links ellipsis), CopyPageMenu.astro and
+// ApiLangSelect.astro, and exported from here so any of them can call it
+// without needing to know whether some other component already has.
 //
-// That "might get called more than once per page" scenario is exactly why
-// the two `document`-level listeners at the bottom are behind their own
-// module-level guard, separate from the existing per-trigger
-// `dataset.wdInit` guard: querying `.wd-dropdown` from more than one
-// component's own `<script>` (each already idempotent per-trigger) would,
-// without this, still add a fresh pair of document click/keydown listeners
-// on every single call - harmless individually, but wasteful if it keeps
-// happening across repeated calls (e.g. once per component that imports
-// this, or once per `astro:page-load` firing from more than one place).
+// These are show/hide buttons for a list of links (the W3C's "disclosure"
+// pattern for navigation), not ARIA menus: the button says whether it's
+// open (aria-expanded), the options are ordinary links and buttons that
+// Tab reaches. For the keyboard, on top of that: Down/Up open the list and
+// move between its options (Home/End jump to the ends); Escape closes it
+// and puts focus back on its button; tabbing out of it closes it.
+//
+// The document-level listeners are bound once per page load, and act on
+// whichever dropdowns are open at the time - so they keep working for the
+// ones a client-side navigation brings in.
 let globalListenersBound = false;
 
-export function initDropdowns(root: ParentNode) {
-  const dropdowns = Array.from(root.querySelectorAll<HTMLElement>('.wd-dropdown'));
-  if (dropdowns.length === 0) return;
+const triggerOf = (dropdown: Element) => dropdown.querySelector<HTMLElement>('.wd-dropdown-trigger');
+const optionsOf = (dropdown: Element) =>
+  Array.from(dropdown.querySelectorAll<HTMLElement>('.wd-dropdown-menu a[href], .wd-dropdown-menu button'));
 
-  const closeAll = () => {
-    dropdowns.forEach((d) => {
-      d.classList.remove('open');
-      d.querySelector('.wd-dropdown-trigger')?.setAttribute('aria-expanded', 'false');
-    });
-  };
+function open(dropdown: Element) {
+  closeAll(dropdown);
+  dropdown.classList.add('open');
+  triggerOf(dropdown)?.setAttribute('aria-expanded', 'true');
+}
 
-  dropdowns.forEach((dropdown) => {
-    const trigger = dropdown.querySelector<HTMLButtonElement>('.wd-dropdown-trigger');
+function close(dropdown: Element) {
+  dropdown.classList.remove('open');
+  triggerOf(dropdown)?.setAttribute('aria-expanded', 'false');
+  // Focus on an option that just got hidden would drop to the top of the
+  // page - it goes back to the button instead.
+  const focused = document.activeElement;
+  if (focused && focused !== triggerOf(dropdown) && dropdown.contains(focused)) triggerOf(dropdown)?.focus();
+}
+
+function closeAll(except?: Element) {
+  document.querySelectorAll('.wd-dropdown.open').forEach((d) => {
+    if (d !== except) close(d);
+  });
+}
+
+export function initDropdowns(root: ParentNode) {
+  root.querySelectorAll<HTMLElement>('.wd-dropdown').forEach((dropdown) => {
+    const trigger = triggerOf(dropdown);
     if (!trigger || trigger.dataset.wdInit) return;
     trigger.dataset.wdInit = 'true';
+
     trigger.addEventListener('click', (e) => {
       e.stopPropagation();
-      const isOpen = dropdown.classList.contains('open');
-      closeAll();
-      if (!isOpen) {
-        dropdown.classList.add('open');
-        trigger.setAttribute('aria-expanded', 'true');
+      if (dropdown.classList.contains('open')) close(dropdown);
+      else open(dropdown);
+    });
+
+    dropdown.addEventListener('keydown', (e) => {
+      if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) return;
+      const options = optionsOf(dropdown);
+      if (options.length === 0) return;
+      e.preventDefault();
+      if (!dropdown.classList.contains('open')) open(dropdown);
+      const at = options.indexOf(document.activeElement as HTMLElement);
+      let next: number;
+      if (e.key === 'Home') next = 0;
+      else if (e.key === 'End') next = options.length - 1;
+      else if (at === -1) next = e.key === 'ArrowUp' ? options.length - 1 : 0;
+      else next = Math.min(Math.max(at + (e.key === 'ArrowDown' ? 1 : -1), 0), options.length - 1);
+      options[next].focus();
+    });
+
+    // Focus moving somewhere outside the dropdown (Tab, Shift+Tab) closes
+    // it. No `relatedTarget` means focus went nowhere in particular - a
+    // click on the page, which the click-outside listener already handles.
+    dropdown.addEventListener('focusout', (e) => {
+      const to = e.relatedTarget as Node | null;
+      if (to && !dropdown.contains(to) && dropdown.classList.contains('open')) {
+        dropdown.classList.remove('open');
+        trigger.setAttribute('aria-expanded', 'false');
       }
     });
   });
 
   if (!globalListenersBound) {
     globalListenersBound = true;
-    // Bound once against `document`, not `root` - closeAll() above already
-    // closes every dropdown found on the page regardless of which root a
-    // given call was scoped to, so there's no reason for these two to be
-    // scoped any narrower or bound more than once.
-    document.addEventListener('click', closeAll);
+    // A click anywhere closes what's open - including a click on one of its
+    // options, which has done its job by then.
+    document.addEventListener('click', () => closeAll());
     document.addEventListener('keydown', (e) => {
       if (e.key === 'Escape') closeAll();
     });