@writedocs/generator 0.8.1 → 0.9.1

package/astro.config.mjs

@@ -37,6 +37,7 @@ import { remarkExtractInlineReactComponents } from './src/lib/mdx-inline-react.j
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
 import { mcpDevServer } from './src/lib/mcp-dev-integration.js';
+import { canonicalPath } from './src/lib/canonical-path.js';
 import { report } from './src/lib/cli-report.js';
 import {
   loadDocsConfig,
@@ -54,7 +55,7 @@ const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
 // its dependencies' own module resolution keeps working), while build.js
 // does the actual cross-filesystem-safe copy into contentDir/dist as an
 // explicit final step once the build itself is done.
-const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = canonicalPath(process.env.WRITEDOCS_PACKAGE_ROOT || path.dirname(fileURLToPath(import.meta.url)));
 // Where this package's dependencies are: the node_modules folder that
 // contains an installed package (<project>/node_modules/@writedocs/
 // generator -> <project>/node_modules), or packageRoot itself in a checkout,

package/bin/writedocs.js

@@ -11,6 +11,7 @@ import { requireBuildKey } from '../src/cli/build-auth.js';
 import { log, step, plural, color, CliExit, errorText, stopActiveStep } from '../src/cli/output.js';
 import { startUpdateCheck, showUpdateNotice } from '../src/cli/update-check.js';
 import { readConfigText } from '../src/lib/config-file.js';
+import { canonicalPath } from '../src/lib/canonical-path.js';
 // O MESMO modulo que o build usa (via loadDocsConfig, que reexporta daqui) e
 // que a plataforma importa por `@writedocs/generator/config-schema` - e o que
 // faz os tres reportarem os mesmos problemas com as mesmas palavras, em vez de
@@ -32,7 +33,9 @@ import {
 } from '../src/lib/config-schema.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.resolve(__dirname, '..');
+// The drive letter in capitals, however the shell spelled it - see
+// src/lib/canonical-path.js.
+const packageRoot = canonicalPath(path.resolve(__dirname, '..'));
 // Read rather than hardcode - a literal version string here silently drifts
 // from package.json's own "version" the moment either one is bumped without
 // the other (exactly what `npm version <bump>` does: it only touches
@@ -64,7 +67,7 @@ program
   .option('--no-open', "don't open the preview in the browser")
   .action(async (dir, opts) => {
     await runDev({
-      contentDir: path.resolve(process.cwd(), dir),
+      contentDir: canonicalPath(path.resolve(process.cwd(), dir)),
       packageRoot,
       port: opts.port,
       verbose: Boolean(opts.verbose),
@@ -86,7 +89,7 @@ program
   .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
   .option('--verbose', "also print Astro's and Vite's own output")
   .action(async (dir, opts) => {
-    const contentDir = path.resolve(process.cwd(), dir);
+    const contentDir = canonicalPath(path.resolve(process.cwd(), dir));
     // Project-scoped, not global: a .env sitting next to this project's own
     // writedocs.json (WRITEDOCS_API_KEY) is picked up automatically, so
     // build doesn't need it exported by hand every
@@ -106,7 +109,7 @@ program
   .argument('[dir]', 'content directory (contains writedocs.json)', '.')
   .option('--config-only', 'check writedocs.json only, not the pages')
   .action(async (dir, options) => {
-    const contentDir = path.resolve(process.cwd(), dir);
+    const contentDir = canonicalPath(path.resolve(process.cwd(), dir));
     const configPath = path.join(contentDir, 'writedocs.json');
     if (!fs.existsSync(configPath)) {
       // Mesma mensagem que loadDocsConfig() ja da pro mesmo caso.
@@ -192,7 +195,7 @@ program
   .description('Check every internal link - pages, anchors and files - in the pages and writedocs.json')
   .argument('[dir]', 'content directory (contains writedocs.json)', '.')
   .action(async (dir) => {
-    const contentDir = path.resolve(process.cwd(), dir);
+    const contentDir = canonicalPath(path.resolve(process.cwd(), dir));
     const { preflightCheck } = await import('../src/cli/preflight.js');
     preflightCheck(contentDir);
     const configText = readConfigText(contentDir);
@@ -227,7 +230,7 @@ program
   .description('Check accessibility - color contrast, image alt text, headings, link text')
   .argument('[dir]', 'content directory (contains writedocs.json)', '.')
   .action(async (dir) => {
-    const contentDir = path.resolve(process.cwd(), dir);
+    const contentDir = canonicalPath(path.resolve(process.cwd(), dir));
     const { preflightCheck } = await import('../src/cli/preflight.js');
     preflightCheck(contentDir);
     const configText = readConfigText(contentDir);
@@ -276,7 +279,7 @@ program
     const { runConvert } = await import('../src/cli/convert.js');
     await runConvert({
       source: legacy ? 'writedocs' : 'mintlify',
-      contentDir: path.resolve(process.cwd(), dir),
+      contentDir: canonicalPath(path.resolve(process.cwd(), dir)),
       force: Boolean(options.force),
       dryRun: Boolean(options.dryRun),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/cli/build.js

@@ -1,3 +1,4 @@
+import { canonicalPath } from '../lib/canonical-path.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { runAstro } from './run-astro.js';
@@ -5,13 +6,19 @@ import { runPagefind } from './run-pagefind.js';
 import { preflightCheck, sameDriveCheck, writableInstallCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
 import { writeRedirectsFile } from './write-redirects-file.js';
+import { rewriteRedirectPages } from './rewrite-redirect-pages.js';
+import { readConfigText } from '../lib/config-file.js';
 import { writeMcpFiles } from './write-mcp-files.js';
+import { pagesWithoutStyles } from './check-built-styles.js';
 import { writedocsBuildStagingDir } from '../lib/writedocs-temp-dir.js';
 import { log, step, plural, duration, displayPath, formatProblems, color, CliExit } from './output.js';
 import { describeError, builtRoute, authorWarning, verboseLine } from './astro-output.js';
 import { reportApiPages } from './api-pages-output.js';
 
 export async function runBuild({ contentDir, packageRoot, verbose = false }) {
+  // One spelling of each folder throughout - see lib/canonical-path.js.
+  contentDir = canonicalPath(contentDir);
+  packageRoot = canonicalPath(packageRoot);
   const started = Date.now();
   preflightCheck(contentDir);
   writableInstallCheck(packageRoot);
@@ -108,11 +115,25 @@ export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   fs.rmSync(distDir, { recursive: true, force: true });
   fs.cpSync(stagingDir, distDir, { recursive: true });
   fs.rmSync(stagingDir, { recursive: true, force: true });
+  // Every page writedocs renders links the site's stylesheet. Builds have
+  // come out without it on every page while reporting success (the package
+  // folder spelled `c:`, fixed in lib/canonical-path.js) - so it's checked
+  // here, and a build like that stops instead of being deployed unstyled.
+  const unstyled = pagesWithoutStyles(distDir);
+  if (unstyled.length) {
+    log.error(`The build produced ${plural(unstyled.length, 'page')} without the site's styles - for example ${unstyled[0]}.`);
+    log.detail(color.dim('This is a fault in the build, not in your pages. Build again; if it happens again, report it with the output of --verbose.'));
+    throw new CliExit(1);
+  }
   // Astro's own writedocs.json `redirects` + the automatic "/" redirect only
   // ever produce client-side meta-refresh pages (see write-redirects-file.js)
   // - this turns those into real instant edge redirects on hosts that read
   // a `_redirects` file (Cloudflare Pages, Netlify), purely additively.
   writeRedirectsFile(distDir, contentDir);
+  // Every other host follows Astro's redirect pages - rewritten so the
+  // reader never sees one (rewrite-redirect-pages.js).
+  const siteConfig = JSON.parse(readConfigText(contentDir));
+  rewriteRedirectPages(distDir, { background: siteConfig.styles?.background?.colors });
   // The site's MCP server at /mcp: mcp-index.json is already in dist/ (an
   // Astro route); this adds the Cloudflare _worker.js that serves it - see
   // write-mcp-files.js for every host.

package/src/cli/check-built-styles.js

@@ -0,0 +1,33 @@
+// After a build: the pages writedocs rendered that came out without the
+// site's styles. Every page BaseLayout.astro renders carries
+// <meta name="generator" content="writedocs"> and links its stylesheet
+// (/_astro/*.css), or inlines it in a <style>. Other HTML in dist/ - a
+// redirect page, a file from public/ - isn't writedocs' to check.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MARKER = /<meta name="generator" content="writedocs"/;
+const STYLES = /<link[^>]+rel="stylesheet"[^>]+href="\/_astro\/[^"]+\.css"|<link[^>]+href="\/_astro\/[^"]+\.css"[^>]+rel="stylesheet"|<style[\s>]/;
+
+function htmlFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== '_astro' && entry.name !== 'pagefind') out.push(...htmlFiles(full));
+    } else if (entry.name.endsWith('.html')) out.push(full);
+  }
+  return out;
+}
+
+/** Paths (relative to `distDir`, with forward slashes) of writedocs pages
+ *  with no stylesheet. */
+export function pagesWithoutStyles(distDir) {
+  return htmlFiles(distDir)
+    .filter((file) => {
+      const html = fs.readFileSync(file, 'utf8');
+      return MARKER.test(html) && !STYLES.test(html);
+    })
+    .map((file) => path.relative(distDir, file).split(path.sep).join('/'))
+    .sort();
+}

package/src/cli/dev.js

@@ -1,3 +1,4 @@
+import { canonicalPath } from '../lib/canonical-path.js';
 import { runAstro } from './run-astro.js';
 import { preflightCheck, sameDriveCheck, writableInstallCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
@@ -14,6 +15,9 @@ import { shouldOpenBrowser, openBrowser } from './open-browser.js';
 const REPEAT_WINDOW_MS = 2000;
 
 export async function runDev({ contentDir, packageRoot, port, verbose = false, open = true }) {
+  // One spelling of each folder throughout - see lib/canonical-path.js.
+  contentDir = canonicalPath(contentDir);
+  packageRoot = canonicalPath(packageRoot);
   const started = Date.now();
   preflightCheck(contentDir);
   writableInstallCheck(packageRoot);

package/src/cli/rewrite-redirect-pages.js

@@ -0,0 +1,84 @@
+// Astro's static build writes every redirect - the site's `/` when no page
+// sits there, and writedocs.json's `redirects` - as a page with a 0-second
+// <meta http-equiv="refresh">. That page has no styles: the browser paints
+// it (white, with a "Redirecting from / to ..." link) before following the
+// refresh - a visible flash on every host that doesn't redirect at the edge
+// (Cloudflare Pages and Netlify do, from _redirects - write-redirects-file.js).
+//
+// After the build, each of those pages is rewritten so there's nothing to
+// see: a script at the top of <head> redirects before anything is painted
+// (keeping the query string and #anchor, which a meta refresh drops), the
+// page is the site's own background color in the reader's theme, and the
+// link is there for screen readers and as the no-script fallback, not on
+// screen. The meta refresh stays for browsers without JavaScript.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const REFRESH = /<meta http-equiv="refresh" content="0;url=([^"]*)"\s*\/?>/i;
+const ASTRO_REDIRECT = /<title>Redirecting to:/;
+const CANONICAL = /<link rel="canonical" href="([^"]*)"\s*\/?>/i;
+
+const DEFAULT_LIGHT = '#ffffff';
+const DEFAULT_DARK = '#0b1120';
+
+function decodeAttr(value) {
+  return value.replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+}
+function encodeAttr(value) {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** A color from writedocs.json, only if it's safe inside a <style>. */
+function cssColor(value, fallback) {
+  return typeof value === 'string' && /^[#a-zA-Z0-9(),.%\s-]{1,64}$/.test(value) ? value : fallback;
+}
+
+/** The page for a redirect to `target`. */
+export function redirectPageHtml({ target, canonical = null, background = {} }) {
+  const light = cssColor(background.light, DEFAULT_LIGHT);
+  const dark = cssColor(background.dark, DEFAULT_DARK);
+  // Inside <script>: a JSON string, with "<" escaped so a target can't end the script.
+  const js = JSON.stringify(target).replace(/</g, '\\u003c');
+  const attr = encodeAttr(target);
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="utf-8">',
+    `<script>location.replace(${js} + location.search + location.hash)</script>`,
+    `<meta http-equiv="refresh" content="0;url=${attr}">`,
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<meta name="robots" content="noindex">',
+    canonical ? `<link rel="canonical" href="${encodeAttr(canonical)}">` : '',
+    '<title>Redirecting…</title>',
+    // Same theme choice as every page (BaseLayout.astro): the stored one, else the system's.
+    "<script>try{var t=localStorage.getItem('wd-theme');if(t!=='light'&&t!=='dark')t=matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';document.documentElement.dataset.theme=t}catch(e){}</script>",
+    `<style>html{background:${light};color-scheme:light}html[data-theme=dark]{background:${dark};color-scheme:dark}@media (prefers-color-scheme:dark){html:not([data-theme]){background:${dark};color-scheme:dark}}body{margin:0}a{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap}</style>`,
+    '</head>',
+    `<body><a href="${attr}">Continue to ${attr}</a></body>`,
+    '</html>',
+    '',
+  ].filter(Boolean).join('\n');
+}
+
+/** Rewrites every Astro redirect page under `distDir`. Returns how many. */
+export function rewriteRedirectPages(distDir, { background } = {}) {
+  let count = 0;
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== '_astro' && entry.name !== 'pagefind') walk(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.html')) continue;
+      const html = fs.readFileSync(full, 'utf8');
+      const refresh = REFRESH.exec(html);
+      if (!refresh || !ASTRO_REDIRECT.test(html)) continue;
+      const canonical = CANONICAL.exec(html);
+      fs.writeFileSync(full, redirectPageHtml({ target: decodeAttr(refresh[1]), canonical: canonical ? decodeAttr(canonical[1]) : null, background }));
+      count++;
+    }
+  };
+  walk(distDir);
+  return count;
+}

package/src/cli/run-astro.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { canonicalPath } from '../lib/canonical-path.js';
 import { fileURLToPath } from 'node:url';
 
 const workerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'astro-worker.js');
@@ -21,6 +22,9 @@ const workerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'astr
  * Returns { child, exited } - `exited` resolves with the exit code.
  */
 export function runAstro(command, { packageRoot, contentDir, port, onEvent }) {
+  // One spelling of each folder for Astro and Vite - see canonical-path.js.
+  packageRoot = canonicalPath(packageRoot);
+  contentDir = canonicalPath(contentDir);
   const child = spawn(process.execPath, [workerPath, command], {
     stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
     // Explicit, not inherited: astro.config.mjs's own `outDir` lives

package/src/components/ApiLangSelect.astro

@@ -42,7 +42,6 @@ const first = options[0];
       type="button"
       class="wd-dropdown-trigger wd-api-lang-trigger"
       data-role={`${rolePrefix}-trigger`}
-      aria-haspopup="true"
       aria-expanded="false"
       aria-label={ariaLabel}
     >
@@ -52,7 +51,7 @@ const first = options[0];
         <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
       </svg>
     </button>
-    <div class="wd-dropdown-menu wd-api-lang-menu" role="menu">
+    <div class="wd-dropdown-menu wd-api-lang-menu">
       <div class="wd-dropdown-menu-panel wd-api-lang-menu-panel">
         {options.map((o, i) => (
           <button

package/src/components/CopyPageMenu.astro

@@ -23,18 +23,26 @@
 // (which need an absolute URL - from writedocs.json's `domain` when it's
 // set, else from the page's own address in the browser; see
 // enabledAssistants below).
-// Without `copy`, the dropdown gets a labeled trigger of its own; with only
-// `copy`, the primary button stands alone.
+// Without `copy`, the options get a labeled "Page options" trigger of their
+// own - or, when there's just one, that option is the button itself ("Open
+// in Claude"). With only `copy`, the primary button stands alone.
+//
+// The last three options connect AI tools to the site's MCP server (/mcp -
+// see docs/dev/docs/mcp.mdx): copy its address, or add it to Cursor or VS
+// Code through their install links (lib/mcp-links.js). [...slug].astro
+// leaves them out when writedocs.json turns `mcp` off.
 import { Icon } from 'astro-icon/components';
 import type { ContextMenuOption } from '../lib/config';
+import { mcpServerUrl, cursorInstallLink, vscodeInstallLink } from '../lib/mcp-links.js';
 
 interface Props {
   currentPath: string; // e.g. "/" or "/guides/foo/" - see hrefForSlug() in [...slug].astro
   siteUrl: string | null;
+  siteName: string;
   options: ContextMenuOption[];
 }
 
-const { currentPath, siteUrl, options } = Astro.props as Props;
+const { currentPath, siteUrl, siteName, options } = Astro.props as Props;
 
 // The [...slug].md.ts route this page is also served at - same
 // normalizeEntryId()-driven convention that file uses to build its own
@@ -42,6 +50,7 @@ const { currentPath, siteUrl, options } = Astro.props as Props;
 // slug with a literal ".md" appended instead of the trailing slash).
 const mdPath = currentPath === '/' ? '/index.md' : `${currentPath.replace(/\/$/, '')}.md`;
 const mdAbsoluteUrl = siteUrl ? `${siteUrl}${mdPath}` : null;
+const mcpUrl = siteUrl ? mcpServerUrl(siteUrl) : null;
 
 // Well-known query-string conventions for starting a new conversation
 // pre-seeded with a prompt (not an official API for any of the three -
@@ -60,29 +69,85 @@ const assistants = [
   { id: 'claude' as const, label: 'Claude', icon: 'simple-icons:claude', base: 'https://claude.ai/new?q=', home: 'https://claude.ai/new' },
   { id: 'perplexity' as const, label: 'Perplexity', icon: 'simple-icons:perplexity', base: 'https://www.perplexity.ai/search?q=', home: 'https://www.perplexity.ai/' },
 ];
+const editors = [
+  { id: 'cursor' as const, label: 'Cursor', icon: 'simple-icons:cursor', link: cursorInstallLink, home: 'https://docs.cursor.com/context/mcp' },
+  { id: 'vscode' as const, label: 'VS Code', icon: 'simple-icons:visualstudiocode', link: vscodeInstallLink, home: 'https://code.visualstudio.com/docs/copilot/chat/mcp-servers' },
+];
+
+// Every link needs an absolute URL - the page's .md for an assistant, the
+// MCP server for an editor. With a `domain` it's known at build time and the
+// link is complete in the HTML. Without one, the page script ([...slug].astro)
+// completes it from the address the page is actually served from, using the
+// data-* attributes below; until then the link goes to the tool's own page.
+type Item = {
+  id: ContextMenuOption;
+  title: string;
+  desc: string;
+  icon: string;
+  group: 'page' | 'mcp';
+  href?: string;
+  newTab?: boolean;
+  attrs?: Record<string, string | undefined>;
+};
+const items: Item[] = [];
+if (options.includes('view')) {
+  items.push({ id: 'view', title: 'View as Markdown', desc: 'View this page as plain text', icon: 'lucide:external-link', group: 'page', href: mdPath, newTab: true });
+}
+for (const a of assistants.filter((a) => options.includes(a.id))) {
+  items.push({
+    id: a.id,
+    title: `Open in ${a.label}`,
+    desc: 'Ask questions about this page',
+    icon: a.icon,
+    group: 'page',
+    href: mdAbsoluteUrl ? a.base + encodeURIComponent(promptFor(mdAbsoluteUrl)) : a.home,
+    newTab: true,
+    attrs: mdAbsoluteUrl ? undefined : { 'data-ask-base': a.base, 'data-md-path': mdPath },
+  });
+}
+if (options.includes('mcp')) {
+  items.push({ id: 'mcp', title: 'Copy MCP server URL', desc: 'Connect AI tools to these docs', icon: 'simple-icons:modelcontextprotocol', group: 'mcp', attrs: { 'data-copy-mcp': mcpUrl ?? '' } });
+}
+for (const e of editors.filter((e) => options.includes(e.id))) {
+  items.push({
+    id: e.id,
+    title: `Connect to ${e.label}`,
+    desc: `Use these docs in ${e.label}`,
+    icon: e.icon,
+    group: 'mcp',
+    // An editor's own link scheme (cursor://, vscode:) - opens the app, not a tab.
+    href: mcpUrl ? e.link(siteName, mcpUrl) : e.home,
+    attrs: mcpUrl ? undefined : { 'data-mcp-install': e.id, 'data-mcp-name': siteName },
+  });
+}
 
-// The assistant needs the page's absolute URL to fetch it. With a `domain`
-// it's known at build time and the link is complete in the HTML. Without
-// one, the page script (initCopyPageMenu() in [...slug].astro) completes it
-// from the address the page is actually served from - `data-ask-base` +
-// the prompt for that URL, the same prompt promptFor() writes.
-const enabledAssistants = assistants.filter((a) => options.includes(a.id));
-const assistantHref = (a: (typeof assistants)[number]) => (mdAbsoluteUrl ? a.base + encodeURIComponent(promptFor(mdAbsoluteUrl)) : a.home);
 const showCopy = options.includes('copy');
-const showView = options.includes('view');
-const hasDropdown = showView || enabledAssistants.length > 0;
+// One option and no "Copy page": that option is the button.
+const single = !showCopy && items.length === 1 ? items[0] : null;
+const hasDropdown = items.length > 0 && !single;
 ---
-{(showCopy || hasDropdown) && (
-<div class="wd-copy-page-split">
+{(showCopy || items.length > 0) && (
+<div class="wd-copy-page-split" data-pagefind-ignore="all">
   {showCopy && (
-    <button type="button" class:list={['wd-copy-page-primary', { 'wd-copy-page-alone': !hasDropdown }]} data-md-path={mdPath} aria-label="Copy page as Markdown">
+    <button type="button" class:list={['wd-copy-page-primary', { 'wd-copy-page-alone': !hasDropdown }]} data-copy-page data-md-path={mdPath} aria-label="Copy page as Markdown">
       <Icon name="lucide:copy" class="wd-copy-page-icon" />
       <span class="wd-copy-page-primary-label">Copy page</span>
     </button>
   )}
+  {single && (single.href ? (
+    <a class="wd-copy-page-primary wd-copy-page-alone" href={single.href} target={single.newTab ? '_blank' : undefined} rel={single.newTab ? 'noopener' : undefined} {...single.attrs}>
+      <Icon name={single.icon} class="wd-copy-page-icon" />
+      <span class="wd-copy-page-primary-label">{single.title}</span>
+    </a>
+  ) : (
+    <button type="button" class="wd-copy-page-primary wd-copy-page-alone" {...single.attrs}>
+      <Icon name={single.icon} class="wd-copy-page-icon" />
+      <span class="wd-copy-page-primary-label">{single.title}</span>
+    </button>
+  ))}
   {hasDropdown && (
   <div class="wd-dropdown wd-copy-page">
-    <button type="button" class:list={['wd-dropdown-trigger', 'wd-copy-page-caret-trigger', { 'wd-copy-page-labeled-trigger': !showCopy }]} aria-haspopup="true" aria-expanded="false" aria-label={showCopy ? 'More copy options' : 'Page options'}>
+    <button type="button" class:list={['wd-dropdown-trigger', 'wd-copy-page-caret-trigger', { 'wd-copy-page-labeled-trigger': !showCopy }]} aria-expanded="false" aria-label={showCopy ? 'More copy options' : 'Page options'}>
       {!showCopy && (
         <>
           <Icon name="lucide:sparkles" class="wd-copy-page-icon" />
@@ -93,25 +158,29 @@ const hasDropdown = showView || enabledAssistants.length > 0;
         <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
       </svg>
     </button>
-    <div class="wd-dropdown-menu wd-copy-page-menu" role="menu">
+    <div class="wd-dropdown-menu wd-copy-page-menu">
       <div class="wd-dropdown-menu-panel wd-copy-page-menu-panel">
-        {showView && (
-        <a class="wd-copy-page-item" href={mdPath} target="_blank" rel="noopener">
-          <Icon name="lucide:external-link" class="wd-copy-page-icon" />
-          <span class="wd-copy-page-item-text">
-            <span class="wd-copy-page-item-title">View as Markdown</span>
-            <span class="wd-copy-page-item-desc">View this page as plain text</span>
-          </span>
-        </a>
-        )}
-        {enabledAssistants.map((a) => (
-          <a class="wd-copy-page-item" href={assistantHref(a)} data-ask-base={mdAbsoluteUrl ? undefined : a.base} data-md-path={mdAbsoluteUrl ? undefined : mdPath} target="_blank" rel="noopener">
-            <Icon name={a.icon} class="wd-copy-page-icon" />
-            <span class="wd-copy-page-item-text">
-              <span class="wd-copy-page-item-title">Open in {a.label}</span>
-              <span class="wd-copy-page-item-desc">Ask questions about this page</span>
-            </span>
-          </a>
+        {items.map((item, i) => (
+          <>
+            {i > 0 && item.group !== items[i - 1].group && <hr class="wd-copy-page-divider" />}
+            {item.href ? (
+              <a class="wd-copy-page-item" href={item.href} target={item.newTab ? '_blank' : undefined} rel={item.newTab ? 'noopener' : undefined} {...item.attrs}>
+                <Icon name={item.icon} class="wd-copy-page-icon" />
+                <span class="wd-copy-page-item-text">
+                  <span class="wd-copy-page-item-title">{item.title}</span>
+                  <span class="wd-copy-page-item-desc">{item.desc}</span>
+                </span>
+              </a>
+            ) : (
+              <button type="button" class="wd-copy-page-item" {...item.attrs}>
+                <Icon name={item.icon} class="wd-copy-page-icon" />
+                <span class="wd-copy-page-item-text">
+                  <span class="wd-copy-page-item-title">{item.title}</span>
+                  <span class="wd-copy-page-item-desc">{item.desc}</span>
+                </span>
+              </button>
+            )}
+          </>
         ))}
       </div>
     </div>
@@ -141,6 +210,9 @@ const hasDropdown = showView || enabledAssistants.length > 0;
     border: 1px solid var(--wd-border);
     border-radius: 0.4rem;
     flex-shrink: 0;
+    /* Right-aligned on its own line too (a long title on a phone sends it
+       below the title) - its menu opens leftwards, and stays on screen. */
+    margin-left: auto;
   }
   /* .wd-copy-page is this instance's own class on the .wd-dropdown div
      wrapping the caret button + menu (see BaseLayout.astro's shared
@@ -201,6 +273,16 @@ const hasDropdown = showView || enabledAssistants.length > 0;
   .wd-copy-page-primary.wd-copy-page-alone {
     border-radius: 0.35rem;
   }
+  /* The single-option button can be a link ("Open in Claude"). */
+  a.wd-copy-page-primary {
+    text-decoration: none;
+  }
+  /* Between the page's options and the MCP server's. */
+  .wd-copy-page-divider {
+    margin: 0.3rem 0.4rem;
+    border: none;
+    border-top: 1px solid var(--wd-border);
+  }
   .wd-copy-page-caret-trigger.wd-copy-page-labeled-trigger {
     gap: 0.35rem;
     padding: 0.35rem 0.65rem;
@@ -259,6 +341,12 @@ const hasDropdown = showView || enabledAssistants.length > 0;
     text-align: left;
     cursor: pointer;
   }
+  /* A button option ("Copy MCP server URL") fills the row like the links
+     do - a button sizes to its content otherwise. */
+  button.wd-copy-page-item {
+    width: 100%;
+    box-sizing: border-box;
+  }
   .wd-copy-page-item:hover {
     background: var(--wd-surface);
   }

package/src/layout/BaseLayout.astro

@@ -415,6 +415,8 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    {/* Marks the pages writedocs renders - the build checks each has the site's styles (cli/check-built-styles.js). */}
+    <meta name="generator" content="writedocs" />
     <title>{title} · {config.name}</title>
     <ClientRouter />
     {effectiveDescription && <meta name="description" content={effectiveDescription} />}

package/src/layout/components/MobileMenu.astro

@@ -31,6 +31,7 @@
 // comment for the fuller rationale.
 import { isExternalHref, type DocsConfig, type Selector, type GlobalDropdownView } from '../../lib/config';
 import AppIcon from '../../components/AppIcon.astro';
+import { hasMobileMenu } from '../../lib/selector-placement.js';
 import '../styles/dropdown.css';
 import '../styles/topbar.css';
 import '../styles/mobile-menu.css';
@@ -48,8 +49,11 @@ interface Props {
   brandLabel?: string;
 }
 const { config, selectors, globalDropdowns, showSidebarCol, logoLight, logoDark, brandLabel } = Astro.props as Props;
+// A page without a sidebar (`mode: custom`) still gets the menu when it has
+// tabs, switchers or global dropdowns to reach - just without the sidebar part.
+const showMenu = hasMobileMenu({ sidebar: showSidebarCol, selectors, globalDropdowns });
 ---
-{showSidebarCol && (
+{showMenu && (
   <div class="wd-mobile-menu" id="wd-mobile-menu" inert>
     <div class="wd-mobile-menu-backdrop" data-mobile-menu-backdrop></div>
     <div class="wd-mobile-menu-panel" role="dialog" aria-modal="true" aria-label="Navigation">
@@ -171,9 +175,11 @@ const { config, selectors, globalDropdowns, showSidebarCol, logoLight, logoDark,
             )}
           </div>
         )}
-        <div class="wd-mobile-menu-sidebar">
-          <slot name="sidebar" />
-        </div>
+        {showSidebarCol && (
+          <div class="wd-mobile-menu-sidebar">
+            <slot name="sidebar" />
+          </div>
+        )}
       </div>
     </div>
   </div>