@writedocs/generator 0.8.0 → 0.9.0

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,
@@ -107,7 +108,10 @@ const contentPublicDir = path.join(contentDir, 'public');
 // document-relative URLs isn't meaningful anyway.
 const siteUrl = resolveSiteUrl(docsConfig);
 if (!siteUrl) {
-  report('info', 'No "domain" set in writedocs.json, so no sitemap.xml was generated.');
+  report(
+    'info',
+    'No "domain" set in writedocs.json, so no sitemap.xml was generated, 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".'
+  );
 }
 
 /** Recursively lists every .md/.mdx file under `baseDir` (Node 20's

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
@@ -61,12 +64,14 @@ program
   .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
   .option('-p, --port <port>', 'port to run on')
   .option('--verbose', "also print Astro's and Vite's own output")
+  .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),
+      open: opts.open,
     });
   });
 
@@ -84,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
@@ -104,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.
@@ -190,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);
@@ -225,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);
@@ -274,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.0",
+  "version": "0.9.0",
   "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';
@@ -6,12 +7,16 @@ import { preflightCheck, sameDriveCheck, writableInstallCheck } from './prefligh
 import { generateApiPages } from './generate-api-pages.js';
 import { writeRedirectsFile } from './write-redirects-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,6 +113,16 @@ 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

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/convert.js

@@ -96,6 +96,9 @@ export async function runConvert({ source = 'mintlify', contentDir, force = fals
   // before the first build.
   const checking = step('Checking pages');
   const content = await checkContent(contentDir, text);
+  // The domain reminder comes once, at the end, with where the source tool
+  // kept that setting.
+  content.warnings = content.warnings.filter((w) => w.code !== 'no-domain');
   checking.stop();
   if (content.errors.length) {
     log.line();

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';
@@ -6,13 +7,17 @@ import { describeError, requestLog, authorWarning, verboseLine, stripAnsi } from
 import { reportApiPages } from './api-pages-output.js';
 import { runningPreview, writeLock, removeLock } from './dev-lock.js';
 import { showUpdateNotice } from './update-check.js';
+import { shouldOpenBrowser, openBrowser } from './open-browser.js';
 
 // The same problem tends to arrive more than once in a row - Vite and
 // Astro each log a failed page, and a page compiles for more than one
 // environment. Within this window, a repeat is dropped.
 const REPEAT_WINDOW_MS = 2000;
 
-export async function runDev({ contentDir, packageRoot, port, verbose = false }) {
+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);
@@ -36,6 +41,7 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
 
   const starting = step('Starting local preview');
   let ready = false;
+  let browserOpened = false;
 
   const lastShown = new Map();
   const once = (key, print) => {
@@ -102,6 +108,12 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
           // `dev` runs until Ctrl+C - the notice goes under the ready screen,
           // not after the command like everywhere else.
           showUpdateNotice();
+          // The preview in the browser, at the address it actually got - once,
+          // not again if Astro restarts the server.
+          if (!browserOpened && shouldOpenBrowser({ open })) {
+            browserOpened = true;
+            openBrowser(local ?? `http://localhost:${wanted}/`);
+          }
           return;
         }
         case 'fatal':

package/src/cli/open-browser.js

@@ -0,0 +1,32 @@
+// `writedocs dev` opens the preview in the default browser once it's ready.
+import { spawn } from 'node:child_process';
+
+/** Whether to open the browser: not with `--no-open`, not with BROWSER=none
+ *  (the convention Vite and create-react-app follow), and not where nobody's
+ *  watching - CI, or output that isn't an interactive terminal. */
+export function shouldOpenBrowser({ open = true, env = process.env, isTTY = Boolean(process.stdout.isTTY) } = {}) {
+  if (!open || !isTTY || env.CI) return false;
+  return String(env.BROWSER ?? '').toLowerCase() !== 'none';
+}
+
+/** The command that opens `url` in the default browser on `platform`. On
+ *  Windows, `start`'s first quoted argument is a window title - hence the
+ *  empty one, which Node passes as "". */
+export function openCommand(url, platform = process.platform) {
+  if (platform === 'win32') return ['cmd', ['/c', 'start', '', url]];
+  if (platform === 'darwin') return ['open', [url]];
+  return ['xdg-open', [url]];
+}
+
+/** Opens `url`, best effort: a machine with no browser (or no xdg-open)
+ *  just doesn't get one - the URL is printed anyway. */
+export function openBrowser(url, { platform = process.platform, run = spawn } = {}) {
+  const [command, args] = openCommand(url, platform);
+  try {
+    const child = run(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on?.('error', () => {});
+    child.unref?.();
+  } catch {
+    // no browser to open - fine
+  }
+}

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

@@ -1,6 +1,7 @@
 ---
-// The "Copy page" split button - opt-in via writedocs.json's `contextMenu`
-// field (see contextMenuSchema in lib/config.ts). A primary button
+// The "Copy page" split button - on by default, showing the options
+// writedocs.json's `contextMenu` leaves on (`options`, from
+// contextMenuOptions() in lib/config-schema.ts). With `copy`, a primary button
 // (always-visible "Copy page" action, copies this page's Markdown
 // straight to the clipboard on click - see initCopyPageMenu() in
 // [...slug].astro) plus a small caret-only button next to it that opens
@@ -19,19 +20,29 @@
 // Rendered from [...slug].astro (see its own comment on where/when),
 // which passes in everything needed to build both same-origin links (the
 // .md route from [...slug].md.ts) and the external "Open in X" links
-// (which need an absolute URL - siteUrl is null on sites with no
-// writedocs.json `domain` set, in which case those three are left out
-// entirely rather than linking a service at a URL it could never fetch).
+// (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 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 { ContextMenuConfig } from '../lib/config';
+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;
-  contextMenu: ContextMenuConfig;
+  siteName: string;
+  options: ContextMenuOption[];
 }
 
-const { currentPath, siteUrl, contextMenu } = 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
@@ -39,6 +50,7 @@ const { currentPath, siteUrl, contextMenu } = 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 -
@@ -50,53 +62,132 @@ const mdAbsoluteUrl = siteUrl ? `${siteUrl}${mdPath}` : null;
 // a bookmarked/shared link.
 const promptFor = (url: string) => `Read ${url} so you can answer questions about it.`;
 
+// `base` + the URL-encoded prompt is the link; `home` is where it goes
+// before the page script has filled the prompt in (see below).
 const assistants = [
-  { id: 'chatgpt' as const, label: 'ChatGPT', icon: 'simple-icons:openai', buildHref: (q: string) => `https://chatgpt.com/?q=${q}` },
-  { id: 'claude' as const, label: 'Claude', icon: 'simple-icons:claude', buildHref: (q: string) => `https://claude.ai/new?q=${q}` },
-  { id: 'perplexity' as const, label: 'Perplexity', icon: 'simple-icons:perplexity', buildHref: (q: string) => `https://www.perplexity.ai/search?q=${q}` },
+  { id: 'chatgpt' as const, label: 'ChatGPT', icon: 'simple-icons:openai', base: 'https://chatgpt.com/?q=', home: 'https://chatgpt.com/' },
+  { 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' },
 ];
 
-// No siteUrl at all -> mdAbsoluteUrl is null -> none of these render,
-// regardless of what contextMenu.openIn lists: a link these services
-// could never actually fetch (a bare relative path, meaningless once
-// it's opened on a different origin) is worse than not offering it.
-const enabledAssistants = mdAbsoluteUrl
-  ? assistants.filter((a) => contextMenu.openIn.includes(a.id))
-  : [];
+// 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 },
+  });
+}
+
+const showCopy = options.includes('copy');
+// 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;
 ---
-<div class="wd-copy-page-split">
-  <button type="button" class="wd-copy-page-primary" 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>
+{(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-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="wd-dropdown-trigger wd-copy-page-caret-trigger" aria-haspopup="true" aria-expanded="false" aria-label="More copy 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" />
+          <span class="wd-copy-page-primary-label">Page options</span>
+        </>
+      )}
       <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
         <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">
-        <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={a.buildHref(encodeURIComponent(promptFor(mdAbsoluteUrl!)))} 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>
   </div>
+  )}
 </div>
+)}
 
 <style>
   /* The split button: a primary "Copy page" action (always visible,
@@ -174,6 +265,30 @@ const enabledAssistants = mdAbsoluteUrl
     border-left: 1px solid var(--wd-border);
     border-radius: 0 0.35rem 0.35rem 0;
   }
+  /* Only one of the two halves: it gets all four corners (and, for the
+     trigger, no divider line and a label like the primary button's). */
+  .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;
+    border-left: none;
+    border-radius: 0.35rem;
+    color: var(--wd-text-muted);
+    font-size: 0.85rem;
+    font-weight: 500;
+  }
   .wd-copy-page-menu {
     left: auto;
     right: 0;
@@ -223,6 +338,12 @@ const enabledAssistants = mdAbsoluteUrl
     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} />}