@writedocs/generator 0.8.0 → 0.8.1

package/astro.config.mjs

@@ -107,7 +107,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

@@ -61,12 +61,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),
       packageRoot,
       port: opts.port,
       verbose: Boolean(opts.verbose),
+      open: opts.open,
     });
   });
 

package/package.json

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

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

@@ -6,13 +6,14 @@ 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 }) {
   const started = Date.now();
   preflightCheck(contentDir);
   writableInstallCheck(packageRoot);
@@ -36,6 +37,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 +104,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/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,21 @@
 // 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 dropdown gets a labeled trigger of its own; with only
+// `copy`, the primary button stands alone.
 import { Icon } from 'astro-icon/components';
-import type { ContextMenuConfig } from '../lib/config';
+import type { ContextMenuOption } from '../lib/config';
 
 interface Props {
   currentPath: string; // e.g. "/" or "/guides/foo/" - see hrefForSlug() in [...slug].astro
   siteUrl: string | null;
-  contextMenu: ContextMenuConfig;
+  options: ContextMenuOption[];
 }
 
-const { currentPath, siteUrl, contextMenu } = Astro.props as Props;
+const { currentPath, siteUrl, 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
@@ -50,33 +53,49 @@ 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/' },
 ];
 
-// 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))
-  : [];
+// 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;
 ---
+{(showCopy || hasDropdown) && (
 <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 && (
+    <button type="button" class:list={['wd-copy-page-primary', { 'wd-copy-page-alone': !hasDropdown }]} 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>
+  )}
+  {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-haspopup="true" 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-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">
@@ -84,8 +103,9 @@ const enabledAssistants = mdAbsoluteUrl
             <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">
+          <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>
@@ -96,7 +116,9 @@ const enabledAssistants = mdAbsoluteUrl
       </div>
     </div>
   </div>
+  )}
 </div>
+)}
 
 <style>
   /* The split button: a primary "Copy page" action (always visible,
@@ -174,6 +196,20 @@ 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;
+  }
+  .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;

package/src/lib/config-schema.js

@@ -390,9 +390,26 @@ const apiSchema = z.object({
   // site can set this to `false` to never involve a third party.
   proxy: z.boolean().default(true)
 }).strict().default({ proxy: true });
-const contextMenuSchema = z.object({
-  openIn: z.array(z.enum(["chatgpt", "claude", "perplexity"])).default(["chatgpt", "claude", "perplexity"])
-}).strict();
+const CONTEXT_MENU_OPTIONS = ["copy", "view", "chatgpt", "claude", "perplexity"];
+const ASSISTANT_OPTIONS = ["chatgpt", "claude", "perplexity"];
+const contextMenuSchema = z.union([
+  z.boolean(),
+  z.array(z.enum(CONTEXT_MENU_OPTIONS)),
+  z.object({
+    openIn: z.array(z.enum(ASSISTANT_OPTIONS)).optional()
+  }).strict()
+]);
+function contextMenuOptions(value) {
+  if (value === false) return [];
+  if (value === void 0 || value === null || value === true) return [...CONTEXT_MENU_OPTIONS];
+  if (Array.isArray(value)) return CONTEXT_MENU_OPTIONS.filter((option) => value.includes(option));
+  if (typeof value === "object") {
+    const openIn = value.openIn;
+    const assistants = Array.isArray(openIn) ? openIn : [...ASSISTANT_OPTIONS];
+    return CONTEXT_MENU_OPTIONS.filter((option) => option === "copy" || option === "view" || assistants.includes(option));
+  }
+  return [];
+}
 const redirectSchema = z.object({
   source: z.string(),
   destination: z.string()
@@ -519,8 +536,8 @@ const docsConfigSchema = z.object({
   // field by field via mergeSeo(), rather than needing to repeat every
   // field on every page.
   seo: seoFieldsSchema.default({}),
-  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
-  // default (no menu, no .md routes).
+  // The "Copy page" menu - see contextMenuSchema above. Absent means on,
+  // with every option; read it through contextMenuOptions().
   contextMenu: contextMenuSchema.optional(),
   // The site's MCP server - an AI tool connects to `/mcp` and searches and
   // reads the docs. On by default: `writedocs build` writes the page index
@@ -829,7 +846,9 @@ function validateDocsConfig(rawText) {
   return { ok: true, data: result.data, issues: [] };
 }
 export {
+  CONTEXT_MENU_OPTIONS,
   ROOT_ALLOWED_EXTRA_KEYS,
+  contextMenuOptions,
   createJsonLocator,
   docsConfigSchema,
   formatValidationIssues,

package/src/lib/config-schema.ts

@@ -727,25 +727,50 @@ const apiSchema = z
   .strict()
   .default({ proxy: true });
 
-// The "Copy page" dropdown shown next to a page's title - copy the raw
-// Markdown to the clipboard, open the raw Markdown in a new tab, or
-// deep-link into an AI assistant with a prompt pointing at it. Opt-in:
-// undefined (the field simply absent from writedocs.json) means the feature
-// is off entirely - no menu rendered, no .md routes generated at build
-// time either (see [...slug].md.ts) - rather than defaulting to on,
-// since it changes both the UI and the build output. Once a site does
-// write a `contextMenu` key (even `{}`), copying/viewing-as-Markdown are
-// always included (they need nothing but the page's own content); only
-// `openIn` (the AI-assistant deep-links, which need an absolute URL to
-// point the assistant at) is independently configurable.
-const contextMenuSchema = z
-  .object({
-    openIn: z.array(z.enum(['chatgpt', 'claude', 'perplexity'])).default(['chatgpt', 'claude', 'perplexity']),
-  })
-  .strict();
+// The "Copy page" menu shown next to a page's title - copy the page's
+// Markdown, view it, or open it in an AI assistant - and the .md copy of
+// every page it relies on ([...slug].md.ts). On by default, with every
+// option, like the MCP server. writedocs.json narrows or turns it off:
+//
+//   (absent) or true         every option
+//   ["copy", "claude"]       only these, in the menu's own order
+//   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 type ContextMenuOption = (typeof CONTEXT_MENU_OPTIONS)[number];
+const ASSISTANT_OPTIONS = ['chatgpt', 'claude', 'perplexity'] as const;
+
+const contextMenuSchema = z.union([
+  z.boolean(),
+  z.array(z.enum(CONTEXT_MENU_OPTIONS)),
+  z
+    .object({
+      openIn: z.array(z.enum(ASSISTANT_OPTIONS)).optional(),
+    })
+    .strict(),
+]);
 
 export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
 
+/** The menu options a writedocs.json `contextMenu` value turns on, in menu
+ *  order - [] when the menu is off. Takes the raw value too (link-check.js
+ *  reads writedocs.json without the schema), so absent means every option. */
+export function contextMenuOptions(value: unknown): ContextMenuOption[] {
+  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 (typeof value === 'object') {
+    const openIn = (value as { openIn?: unknown }).openIn;
+    const assistants = Array.isArray(openIn) ? openIn : [...ASSISTANT_OPTIONS];
+    return CONTEXT_MENU_OPTIONS.filter((option) => option === 'copy' || option === 'view' || assistants.includes(option));
+  }
+  return [];
+}
+
 // One entry in writedocs.json's `redirects` array - wired almost directly into
 // Astro's own `redirects` config option (astro.config.mjs), which is what
 // actually generates the redirect pages. `permanent` is deliberately not
@@ -996,8 +1021,8 @@ export const docsConfigSchema = z.object({
   // field by field via mergeSeo(), rather than needing to repeat every
   // field on every page.
   seo: seoFieldsSchema.default({}),
-  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
-  // default (no menu, no .md routes).
+  // The "Copy page" menu - see contextMenuSchema above. Absent means on,
+  // with every option; read it through contextMenuOptions().
   contextMenu: contextMenuSchema.optional(),
   // The site's MCP server - an AI tool connects to `/mcp` and searches and
   // reads the docs. On by default: `writedocs build` writes the page index

package/src/lib/content-check.js

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

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

@@ -164,8 +164,8 @@ export const DESCRIPTIONS = {
   'seo.twitterCard': 'X/Twitter card style. Default "summary_large_image" with an `ogImage`, "summary" without.',
   'seo.keywords': 'Keywords for the <meta name="keywords"> tag.',
   'seo.noindex': 'Ask search engines not to index pages, and leave them out of sitemap.xml.',
-  contextMenu: 'Adds a "Copy page" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + ".md".',
-  'contextMenu.openIn': 'Which AI assistants the menu offers. Default: all three.',
+  contextMenu: 'The "Copy page" menu on every page - copy as Markdown, view as Markdown, open in ChatGPT, Claude or Perplexity - 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.openIn': 'The earlier form: which AI assistants the menu offers, besides copy and view. A list of options replaces it.',
   mcp: 'An MCP server at /mcp, so AI tools can search and read the docs. The build adds its index and a Cloudflare-ready _worker.js to dist/. Default true; false leaves them out.',
   redirects: 'Redirects from old addresses. Each matches one exact path.',
   'redirects[].source': 'The old path, like "/old-page".',

package/src/lib/link-check.js

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

package/src/lib/llms-index.ts

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

package/src/lib/mintlify-convert.js

@@ -530,13 +530,16 @@ export function convertMintlifyConfig(docs) {
   if (docs.seo?.indexing === 'all') notes.add('seo.indexing', ['seo', 'indexing'], '`seo.indexing: "all"` has no equivalent - writedocs indexes every page that isn\'t marked noindex.');
 
   // context menu
+  // Mintlify's option names are writedocs' own for the 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.
   const options = docs.contextual?.options;
   if (Array.isArray(options) && options.length) {
-    const openIn = options.filter((o) => ['chatgpt', 'claude', 'perplexity'].includes(o));
-    out.contextMenu = { openIn };
-    const other = options.filter((o) => typeof o !== 'string' || !['copy', 'view', 'chatgpt', 'claude', 'perplexity'].includes(o));
+    const known = ['copy', 'view', 'chatgpt', 'claude', 'perplexity'];
+    out.contextMenu = known.filter((o) => options.includes(o));
+    const other = options.filter((o) => typeof o !== 'string' || !known.includes(o));
     if (other.length) {
-      notes.add('contextual', ['contextual', 'options'], `Context menu options writedocs doesn't have were dropped: ${other.map((o) => (typeof o === 'string' ? o : o.title ?? 'custom')).join(', ')}.`, 'writedocs\' page menu always has copy and view-as-Markdown, plus open in ChatGPT, Claude and Perplexity.');
+      notes.add('contextual', ['contextual', 'options'], `Context menu options writedocs doesn't have were dropped: ${other.map((o) => (typeof o === 'string' ? o : o.title ?? 'custom')).join(', ')}.`, 'writedocs\' page menu offers copy, view as Markdown, and open in ChatGPT, Claude and Perplexity.');
     }
   }
 

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

@@ -16,6 +16,7 @@ import {
   flattenNav,
   firstSlugOfNavigation,
   mergeSeo,
+  contextMenuOptions,
   resolveSiteUrl,
   findAllPages,
 } from "../lib/config";
@@ -414,8 +415,9 @@ const showToc = pageMode === "default";
 // branch on separately.
 const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 
-// The "Copy page" dropdown (CopyPageMenu.astro) - opt-in via writedocs.json's
-// `contextMenu` field (see contextMenuSchema in lib/config.ts), and only
+// The "Copy page" menu (CopyPageMenu.astro) - on by default, with the
+// options writedocs.json's `contextMenu` leaves on (contextMenuOptions() in
+// lib/config-schema.ts; `false` turns it off), and only
 // shown where there's a real auto-rendered <h1> to sit next to: canvas
 // mode pages (custom/blank) have no such header (a hand-built landing
 // page controls its own layout, there's nothing standard to anchor the
@@ -423,7 +425,8 @@ const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 // spec rather than prose - see [...slug].md.ts's own comment on why
 // those are excluded from the .md route this menu links to in the first
 // place, which this mirrors on the UI side.
-const showCopyPageMenu = Boolean(config.contextMenu) && !isCanvasMode && !entry.data.openapi;
+const contextMenuItems = contextMenuOptions(config.contextMenu);
+const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode && !entry.data.openapi;
 const siteUrl = resolveSiteUrl(config);
 
 const components = {
@@ -513,7 +516,7 @@ const components = {
             )
           }
           {showCopyPageMenu && (
-            <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} contextMenu={config.contextMenu!} />
+            <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} options={contextMenuItems} />
           )}
         </div>
         <Content components={components} />
@@ -672,6 +675,19 @@ const components = {
   initCopyPageMenu(document);
   document.addEventListener("astro:page-load", () => initCopyPageMenu(document));
 
+  // "Open in ChatGPT/Claude/Perplexity" on a site with no writedocs.json
+  // `domain`: the page's absolute .md URL isn't known at build time, so the
+  // link is completed here from the address the page is served from (see
+  // CopyPageMenu.astro) - same prompt the build writes when it does know.
+  function initAskLinks(root: ParentNode) {
+    root.querySelectorAll<HTMLAnchorElement>("a[data-ask-base][data-md-path]").forEach((link) => {
+      const url = new URL(link.dataset.mdPath ?? "/", window.location.origin).href;
+      link.href = link.dataset.askBase + encodeURIComponent(`Read ${url} so you can answer questions about it.`);
+    });
+  }
+  initAskLinks(document);
+  document.addEventListener("astro:page-load", () => initAskLinks(document));
+
   // Show more/less toggle for ```js expandable code blocks - same
   // build-time-emitted-button + client-wired-click pattern as the copy
   // button above; codeBlockTransformer only adds this button when the
@@ -845,7 +861,7 @@ const components = {
     width: 100%;
   }
   /* Wraps the auto-rendered <h1> together with CopyPageMenu (only
-     rendered when writedocs.json's `contextMenu` is set - see
+     rendered when writedocs.json's `contextMenu` isn't off - see
      showCopyPageMenu above) so the two sit on one row, menu pinned to
      the right. Always present (even with no menu) rather than only
      wrapping the <h1> conditionally, so the <h1>'s own top/bottom

package/src/pages/[...slug].md.ts

@@ -2,7 +2,7 @@ import { getCollection, type CollectionEntry } from 'astro:content';
 import fs from 'node:fs';
 import path from 'node:path';
 import type { APIRoute } from 'astro';
-import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
+import { loadDocsConfig, normalizeEntryId, findAllPages, contextMenuOptions } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 import { markdownForAgents } from '../lib/agent-markdown.js';
 
@@ -11,10 +11,10 @@ import { markdownForAgents } from '../lib/agent-markdown.js';
 // /guides/foo/ -> /guides/foo.md), serving its untouched MDX/Markdown
 // source instead of rendered HTML - what the "Copy page"/"View as
 // Markdown" menu (CopyPageMenu.astro, wired in from [...slug].astro)
-// links to, and what an LLM fetching that URL directly gets. Gated
-// entirely behind writedocs.json's `contextMenu` field being present (see
-// contextMenuSchema in lib/config.ts) - a site that hasn't opted in gets
-// no .md routes at all, not just a hidden menu.
+// links to, and what an LLM fetching that URL directly gets. On by
+// default, like the menu; writedocs.json `"contextMenu": false` (see
+// contextMenuOptions() in lib/config-schema.ts) leaves out the .md routes
+// too, not just the menu.
 //
 // A literal ".md" filename suffix rather than a `[...slug]` capture
 // covering it: naming the file `[...slug].md.ts` makes Astro treat ".md"
@@ -33,9 +33,9 @@ type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
 export async function getStaticPaths() {
   const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
   const config = loadDocsConfig(contentDir);
-  // No writedocs.json `contextMenu` - feature is off entirely, including these
-  // routes (not just the menu UI - see the file-level comment above).
-  if (!config.contextMenu) return [];
+  // `"contextMenu": false` - the feature is off entirely, these routes
+  // included (not just the menu UI - see the file-level comment above).
+  if (contextMenuOptions(config.contextMenu).length === 0) return [];
 
   const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
   const hasPages = findAllPages(contentDir).length > 0;

package/writedocs.schema.json

@@ -747,30 +747,45 @@
       "markdownDescription": "Default metadata for every page. A page's own `seo` frontmatter overrides it field by field."
     },
     "contextMenu": {
-      "type": "object",
-      "properties": {
-        "openIn": {
-          "default": [
-            "chatgpt",
-            "claude",
-            "perplexity"
-          ],
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
           "type": "array",
           "items": {
             "type": "string",
             "enum": [
+              "copy",
+              "view",
               "chatgpt",
               "claude",
               "perplexity"
             ]
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "openIn": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "chatgpt",
+                  "claude",
+                  "perplexity"
+                ]
+              },
+              "description": "The earlier form: which AI assistants the menu offers, besides copy and view. A list of options replaces it.",
+              "markdownDescription": "The earlier form: which AI assistants the menu offers, besides copy and view. A list of options replaces it."
+            }
           },
-          "description": "Which AI assistants the menu offers. Default: all three.",
-          "markdownDescription": "Which AI assistants the menu offers. Default: all three."
+          "additionalProperties": false
         }
-      },
-      "additionalProperties": false,
-      "description": "Adds a \"Copy page\" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + \".md\".",
-      "markdownDescription": "Adds a \"Copy page\" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + \".md\"."
+      ],
+      "description": "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.",
+      "markdownDescription": "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."
     },
     "mcp": {
       "default": true,