@writedocs/generator 0.7.2 → 0.7.4

package/src/lib/pages.js

@@ -5,6 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
+import { readConfigText } from './config-file.js';
 
 // Top-level folders of a content directory that are never scanned for
 // pages - build output, dependencies, and static assets. Any folder whose
@@ -60,24 +61,31 @@ function readIgnoreFile(contentDir) {
  *  groups' `page`) - read straight from the file, since this runs before
  *  (and independently of) config validation. Empty when there's no
  *  readable writedocs.json. */
-function navigationPageIds(contentDir) {
-  let config;
-  try {
-    config = JSON.parse(fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8'));
-  } catch {
-    return new Set();
-  }
+/** Every page id a `navigation` lists, in the order a reader meets them -
+ *  top to bottom, each group's own `page` before its `pages` - without
+ *  repeats. */
+export function navigationPageOrder(navigation) {
   const ids = new Set();
   (function walk(node) {
     if (Array.isArray(node)) node.forEach((item) => (typeof item === 'string' ? ids.add(item) : walk(item)));
     else if (node && typeof node === 'object') {
+      if (typeof node.page === 'string') ids.add(node.page);
       for (const [key, value] of Object.entries(node)) {
-        if (key === 'page' && typeof value === 'string') ids.add(value);
-        else if (key !== 'openapi' && key !== 'href') walk(value);
+        if (key !== 'page' && key !== 'openapi' && key !== 'href') walk(value);
       }
     }
-  })(config.navigation);
-  return ids;
+  })(navigation);
+  return [...ids];
+}
+
+function navigationPageIds(contentDir) {
+  let config;
+  try {
+    config = JSON.parse(readConfigText(contentDir));
+  } catch {
+    return new Set();
+  }
+  return new Set(navigationPageOrder(config.navigation));
 }
 
 /** Recursively finds every .md/.mdx file under `contentDir` that is a page:
@@ -148,3 +156,121 @@ export function findAllPages(contentDir) {
 export function fileIdForPath(relativePath) {
   return relativePath.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
 }
+
+/** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
+ *  `public/` included - auto-loaded site-wide with zero `writedocs.json`
+ *  config, on top of (not instead of) the explicit `scripts` field
+ *  (bannerSchema and friends, above). Drop a file in, it loads;
+ *  there's no field naming which ones to use, matching the same "just
+ *  works" convention `docs/`'s own file discovery already follows (see
+ *  findAllPages() above / `content-pipeline.mdx`) - a site author already
+ *  drops content files in and expects them found, rather than also
+ *  listing every one in writedocs.json.
+ *
+ *  Two separate walks, because `public/` needs different treatment than
+ *  everywhere else:
+ *
+ *  - `css`/`js`: every `.css`/`.js` file outside `public/` (root, `docs/`,
+ *    `snippets/`, any custom folder) - reused as the walk-with-exclusions
+ *    shape from findAllPages() above, and its exact `EXCLUDED_TOP_LEVEL_DIRS`
+ *    set (skipped only at the project root, same as there), so `dist/`,
+ *    `node_modules/`, `.astro/`, `.writedocs/`, `.git/`, and (for this
+ *    half only - see below) `public/` are never walked into. BaseLayout.astro
+ *    reads each one's raw content and inlines it as a `<style>`/
+ *    `<script is:inline>` tag.
+ *  - `publicCss`/`publicJs`: every `.css`/`.js` file *inside* `public/`,
+ *    walked separately (starting from `<contentDir>/public` rather than
+ *    `contentDir` itself, so the same `EXCLUDED_TOP_LEVEL_DIRS` check
+ *    doesn't apply here - there's no `public/public/` or `public/dist/`
+ *    convention to guard against). Returned as public-URL-rooted hrefs
+ *    (a leading `/`, no `public` segment - `public/custom.css` becomes
+ *    `/custom.css`) rather than content-dir-relative paths, since these
+ *    files are already served as static assets at exactly that URL once
+ *    Astro copies `public/` into the build output. BaseLayout.astro
+ *    renders these as ordinary `<link rel="stylesheet">`/`<script src>`
+ *    tags pointing at that URL instead of inlining their content -
+ *    inlining would duplicate every byte (once in the page's own HTML,
+ *    once more as the independently-fetchable static file at that same
+ *    URL) for no benefit, where a `<link>`/`<script src>` gets normal
+ *    browser caching across pages instead of repeating the content on
+ *    every single page's markup.
+ *
+ *  Both halves are broader than they might sound - a stray `.js` file
+ *  kept in `docs/`, `snippets/`, or `public/` for an unrelated reason
+ *  (a snippet's own local helper, an image gallery's lightbox script
+ *  someone dropped in `public/` to reference from a raw `<script src>`
+ *  in an .mdx file, say) gets auto-injected sitewide the same as a
+ *  deliberate one; there's no separate "this one's just tooling" signal
+ *  to opt out of the convention short of renaming its extension.
+ *
+ *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
+ *  by their respective path for deterministic load order across rebuilds
+ *  - filesystem readdir order isn't guaranteed portable across OSes or
+ *  directory-walk order otherwise.
+ *
+ *  `css`/`js` return POSIX-separated paths relative to `contentDir`, not
+ *  absolute paths or file contents - BaseLayout.astro (the sole caller)
+ *  resolves and reads each one's content itself, right before inlining
+ *  it, so a file's content is always current as of that specific
+ *  request/build rather than cached here across a `writedocs dev`
+ *  session. `publicCss`/`publicJs` return the public-URL hrefs described
+ *  above - nothing to read, Astro's own static-file serving/copy already
+ *  handles those. */
+export function findRootAssets(contentDir) {
+  const css = [];
+  const js = [];
+  function walk(dir, relBase) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
+        // Dot-folders (.github, .claude, .husky, .vscode, ...) hold tooling,
+        // never site assets - the same rule findAllPages() applies to pages.
+        // Without it, a CI script under .github/ ran on every page.
+        if (entry.name.startsWith('.')) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile() || entry.name.startsWith('.')) continue; // .eslintrc.js and friends
+      if (/\.css$/i.test(entry.name)) css.push(rel);
+      else if (/\.js$/i.test(entry.name)) js.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  css.sort();
+  js.sort();
+
+  const publicCss = [];
+  const publicJs = [];
+  function walkPublic(dir, relBase) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkPublic(abs, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (/\.css$/i.test(entry.name)) publicCss.push(`/${rel}`);
+      else if (/\.js$/i.test(entry.name)) publicJs.push(`/${rel}`);
+    }
+  }
+  walkPublic(path.join(contentDir, 'public'), '');
+  publicCss.sort();
+  publicJs.sort();
+
+  return { css, js, publicCss, publicJs };
+}

package/src/lib/styles-asset-integration.js

@@ -56,6 +56,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadDocsConfig, collectConfiguredAssetPaths } from './config.ts';
+import { resolveOutsidePublic } from './asset-path.js';
 
 const MIME_BY_EXTENSION = {
   '.svg': 'image/svg+xml',
@@ -76,24 +77,6 @@ function mimeFor(filePath) {
   return MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
 }
 
-/** Resolves a root-relative `urlPath` (e.g. "/images/hero.svg") against
- *  `contentDir` directly - not `<contentDir>/public` - the fallback
- *  location for one of the styles/footer/seo asset fields
- *  (collectConfiguredAssetPaths()) when it isn't sitting under public/.
- *  Segment-by-segment path-traversal guard (no
- *  `..`/`.` segments) since `urlPath` ultimately comes from an incoming
- *  request URL in the dev-server case, not just trusted writedocs.json
- *  content. Returns an absolute path, or null if nothing real is there. */
-function resolveOutsidePublic(urlPath, contentDir) {
-  const segments = urlPath.replace(/^\/+/, '').split('/');
-  if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) return null;
-  const absolute = path.join(contentDir, ...segments);
-  try {
-    return fs.statSync(absolute).isFile() ? absolute : null;
-  } catch {
-    return null;
-  }
-}
 
 function publicPathFor(urlPath, contentDir) {
   const segments = urlPath.replace(/^\/+/, '').split('/');

package/src/lib/writedocs-legacy-convert.js

@@ -18,12 +18,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
 import { iconExists } from './icons.js';
+import { readJsonText } from './config-file.js';
 import { fileIdForPath } from './pages.js';
 import { Notes, LANGUAGE_NAMES } from './mintlify-convert.js';
 import { pageUrlResolver } from './link-check.js';
 
 export function loadLegacyConfig(file) {
-  return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  return JSON.parse(readJsonText(file));
 }
 
 const PAGE_ENDINGS = ['.api.mdx', '.info.mdx', '.mdx', '.md'];

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

@@ -271,7 +271,11 @@ interface Props {
 
 const rawProps = Astro.props as Props;
 if (rawProps.redirectTo) {
-  return Astro.redirect(rawProps.redirectTo);
+  // 301, not Astro's default 302: in a static build the status only picks
+  // the meta refresh delay (astro/dist/core/routing/3xx.js) - 2 seconds of
+  // "Redirecting from..." text for a 302, none for a 301. Hosts that read
+  // _redirects get a real 301 for "/" too (write-redirects-file.js).
+  return Astro.redirect(rawProps.redirectTo, 301);
 }
 const {
   entry,
@@ -365,6 +369,11 @@ const activePagePosition = flattenNav(activeSection.pages).findIndex((e) => e.sl
 // plus the always-visible global dropdown list - see BaseLayout.astro
 // for how each renders.
 const selectors = buildSelectors(activeSection.path, hrefForSlug, activePagePosition);
+// <html lang>: the `language` of the navigation level this page sits under,
+// if any. A hidden page has no level of its own (activeSection is only a
+// fallback for its chrome), so it keeps the default.
+const languageSegment = isHidden ? undefined : activeSection.path.find((segment) => segment.kind === "language");
+const pageLang = languageSegment ? (languageSegment.items[languageSegment.index] as { language: string }).language : undefined;
 const globalDropdowns = buildGlobalDropdowns(
   resolveGlobalDropdowns(config.navigation),
   currentFileId,
@@ -473,6 +482,7 @@ const components = {
   selectors={selectors}
   globalDropdowns={globalDropdowns}
   mode={pageMode}
+  lang={pageLang}
 >
   {showSidebar && <Sidebar slot="sidebar" navTree={navTree} hrefForSlug={hrefForSlug} currentSlug={currentFileId} />}
   {

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

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { APIRoute } from 'astro';
 import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
-import { applyVisibilityForAgents } from '../lib/visibility.js';
+import { markdownForAgents } from '../lib/agent-markdown.js';
 
 // The raw-Markdown twin of [...slug].astro: every content page is also
 // reachable at the exact same slug with a literal ".md" suffix (e.g.
@@ -58,25 +58,34 @@ export async function getStaticPaths() {
     .filter((entry) => !entry.data.url)
     .map((entry) => ({
       params: { slug: normalizeEntryId(entry.id) },
-      props: { entry },
+      // Passed along rather than re-read per page - GET only renders one entry.
+      props: { entry, variables: config.variables },
     }));
 }
 
 interface Props {
   entry: DocsEntry;
+  variables: Record<string, string>;
 }
 
 export const GET: APIRoute = ({ props }) => {
-  const { entry } = props as Props;
+  const { entry, variables } = props as Props;
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+  const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || process.cwd();
   // entry.body is the raw, frontmatter-stripped MDX/Markdown source text
   // Astro's glob() loader already read off disk and stashed on every
   // entry by default (see astro/dist/content/loaders/glob.js) - reusing
   // it here means this route needs no separate file read/parse of its
   // own, and always matches exactly what [...slug].astro rendered from
   // (same entry, same collection query).
-  // Mintlify's <Visibility>: this is the agents' view of the page - see
-  // lib/visibility.js.
-  const body = applyVisibilityForAgents(entry.body ?? '');
+  // What the page shows rather than its raw source: Mintlify's <Visibility>
+  // for agents, imported snippets inlined, `variables` filled in - see
+  // lib/agent-markdown.js (llms-full.txt uses the same).
+  const body = markdownForAgents(entry.body ?? '', {
+    file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
+    contentDir,
+    variables,
+  });
   const markdown = `# ${entry.data.title}\n\n${body}`;
   return new Response(markdown, {
     headers: { 'Content-Type': 'text/markdown; charset=utf-8' },

package/src/pages/llms/[...path].md.ts

@@ -0,0 +1,23 @@
+import type { APIRoute } from 'astro';
+import { llmsIndexFiles } from '../../lib/llms-index';
+
+// The child files a big site's llms.txt links to - /llms/<section>.md, one
+// per navigation section that didn't fit in llms.txt itself (see
+// lib/llms.js). Most sites have none: llms.txt holds every page, and this
+// route produces nothing. Nor with a hand-written llms.txt, which replaces
+// the generated index as a whole.
+export async function getStaticPaths() {
+  const files = await llmsIndexFiles();
+  if (!files) return [];
+  return [...files.entries()]
+    .filter(([file]) => file.startsWith('llms/'))
+    .map(([file, text]) => ({
+      params: { path: file.replace(/^llms\//, '').replace(/\.md$/, '') },
+      props: { text },
+    }));
+}
+
+export const GET: APIRoute = ({ props }) =>
+  new Response((props as { text: string }).text, {
+    headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
+  });

package/src/pages/llms-full.txt.ts

@@ -2,9 +2,10 @@ 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, resolveSiteUrl, fileIdForEntry } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
-import { applyVisibilityForAgents } from '../lib/visibility.js';
+import { markdownForAgents } from '../lib/agent-markdown.js';
+import { orderByNavigation } from '../lib/llms.js';
 
 // The "everything, concatenated" half of the llms.txt pair - see
 // llms.txt.ts (right next to this file) for the lightweight index half,
@@ -29,7 +30,9 @@ export const GET: APIRoute = async () => {
     });
   }
 
+  const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || process.cwd();
   const config = loadDocsConfig(contentDir);
+  const siteUrl = resolveSiteUrl(config);
 
   const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
   const hasPages = findAllPages(contentDir).length > 0;
@@ -39,7 +42,7 @@ export const GET: APIRoute = async () => {
   ]);
   const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
 
-  const sections = entries
+  const unordered = entries
     // Same exclusion [...slug].md.ts applies to its own per-page raw
     // Markdown route, for the same reason: an OpenAPI operation page
     // (generated stub, or a hand-written page that opts into rendering
@@ -54,17 +57,35 @@ export const GET: APIRoute = async () => {
     .filter((entry) => !entry.data.url)
     .map((entry: DocsEntry) => {
       const slug = normalizeEntryId(entry.id);
-      // Agents' view of <Visibility> blocks, same as the .md route.
-      const body = applyVisibilityForAgents(entry.body ?? '');
-      return { slug, title: entry.data.title, body };
-    })
-    .sort((a, b) => a.slug.localeCompare(b.slug));
+      // What the page shows, not its raw source: <Visibility> for agents,
+      // imported snippets inlined, `variables` filled in - same as the .md
+      // route (lib/agent-markdown.js).
+      const body = markdownForAgents(entry.body ?? '', {
+        file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
+        contentDir,
+        variables: config.variables,
+      });
+      // The page's own URL, so an agent can cite it.
+      const url = `${siteUrl ?? ''}${slug === 'index' ? '/' : `/${slug}/`}`;
+      return {
+        slug,
+        fileId: fileIdForEntry(contentDir, packageRoot, entry),
+        title: entry.data.title,
+        description: entry.data.description,
+        url,
+        body,
+      };
+    });
+  // Navigation order, same as llms.txt.
+  const sections = orderByNavigation(unordered, config.navigation);
 
   const lines: string[] = [`# ${config.name}`, ''];
   if (config.description) lines.push(`> ${config.description}`, '');
 
   for (const section of sections) {
-    lines.push('---', '', `# ${section.title}`, '', section.body.trim(), '');
+    lines.push('---', '', `# ${section.title}`, '', `URL: ${section.url}`, '');
+    if (section.description) lines.push(`> ${section.description}`, '');
+    lines.push(section.body.trim(), '');
   }
 
   const content = lines.join('\n') + '\n';

package/src/pages/llms.txt.ts

@@ -1,9 +1,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, resolveSiteUrl } from '../lib/config';
-import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+import { llmsIndexFiles } from '../lib/llms-index';
 
 // A lightweight, LLM-facing index of every page on the site - the
 // llms.txt convention (see https://llmstxt.org), also adopted by Mintlify
@@ -13,132 +11,30 @@ import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 // of the pair; llms-full.txt (llms-full.txt.ts, right next to this file)
 // is the "everything, concatenated" half.
 //
-// Fixed, non-dynamic route (no getStaticPaths/params needed) - Astro
-// prerenders this once at the literal path /llms.txt, same as any other
-// static-output route (this project's astro.config.mjs sets
-// `output: 'static'`), and re-evaluates it per request in `writedocs dev`
-// - see [...slug].md.ts for the same fixed-route-vs-catchall distinction
-// applied to per-page raw Markdown.
+// Pages are listed under headings that follow the navigation. A site too
+// big for one file keeps this as a directory whose largest sections link to
+// child files - llms/[...path].md.ts serves those - so no page is left out;
+// see lib/llms.js.
 //
-// Unconditional - unlike the per-page .md routes in [...slug].md.ts,
-// this doesn't depend on writedocs.json's `contextMenu` field. There's no UI
+// Fixed, non-dynamic route - Astro prerenders this once at the literal path
+// /llms.txt (this project's astro.config.mjs sets `output: 'static'`), and
+// re-evaluates it per request in `writedocs dev`.
+//
+// Unconditional - unlike the per-page .md routes in [...slug].md.ts, this
+// doesn't depend on writedocs.json's `contextMenu` field. There's no UI
 // footprint to gate (it's an extra static file, not a visible menu), so
 // it's always generated. `contextMenu` only affects which URL each entry
-// links to below (a real fetchable .md URL if the per-page raw-Markdown
-// routes exist, the ordinary HTML page URL otherwise).
-type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
-
-// Mirrors Mintlify's own llms.txt behavior: truncate a page's frontmatter
-// `description` at the first line break (a multi-paragraph description
-// would blow out a one-line list entry) and at 300 characters (an
-// arbitrary but reasonable cap - keeps every entry scannable regardless
-// of how verbose an individual page's description happens to be).
-const DESCRIPTION_MAX_CHARS = 300;
-function truncateDescription(description: string | undefined): string | undefined {
-  if (!description) return undefined;
-  const firstLine = description.split('\n')[0].trim();
-  if (!firstLine) return undefined;
-  return firstLine.length > DESCRIPTION_MAX_CHARS
-    ? firstLine.slice(0, DESCRIPTION_MAX_CHARS).trimEnd() + '…'
-    : firstLine;
-}
-
-// Same cap Mintlify documents for its own auto-generated llms.txt - this
-// file is meant to stay a lightweight index (one line per page), not
-// balloon into something llms-full.txt-sized. Realistically unlikely to
-// matter for most Writedocs sites (a site would need on the order of a
-// thousand-plus pages with full-length descriptions to hit this), but
-// cheap to guard against regardless.
-const MAX_CHARS = 100_000;
-
+// links to (a real fetchable .md URL if the per-page raw-Markdown routes
+// exist, the ordinary HTML page URL otherwise).
 export const GET: APIRoute = async () => {
-  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
-
-  // A hand-authored llms.txt at the project root (next to writedocs.json)
-  // always wins outright over the generated one below - same override
-  // convention Mintlify documents for its own llms.txt. Lets a site
-  // author hand-curate this file (different ordering, editorial
-  // descriptions, extra sections) without losing the ability to fall
-  // back to the auto-generated version by just deleting the override.
-  const customPath = path.join(contentDir, 'llms.txt');
-  if (fs.existsSync(customPath)) {
-    return new Response(fs.readFileSync(customPath, 'utf-8'), {
-      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-    });
-  }
-
-  const config = loadDocsConfig(contentDir);
-  const siteUrl = resolveSiteUrl(config); // absolute origin if `domain` is set, else null
-
-  const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
-  const hasPages = findAllPages(contentDir).length > 0;
-  const [pagesEntries, generatedDocsEntries] = await Promise.all([
-    hasPages ? getCollection('pages') : Promise.resolve([]),
-    hasGeneratedDocs ? getCollection('generatedDocs') : Promise.resolve([]),
-  ]);
-  const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
-
-  const items = entries
-    // A page that opted out of search-engine indexing (frontmatter
-    // `seo.noindex: true`, already excluded from sitemap.xml - see
-    // astro.config.mjs's collectNoindexIds()) is excluded here for the
-    // same reason: llms.txt exists to help external tools discover
-    // pages, exactly what `noindex` asked not to happen.
-    .filter((entry) => !entry.data.seo?.noindex)
-    // A frontmatter `url` page (Mintlify's external link) has no content -
-    // its own URL only redirects to the link.
-    .filter((entry) => !entry.data.url)
-    .map((entry: DocsEntry) => {
-      const slug = normalizeEntryId(entry.id);
-      // Same URL Astro's own router resolves this entry to - see
-      // hrefForSlug() in [...slug].astro for the HTML form, and
-      // [...slug].md.ts for the .md form (no trailing slash, "index.md"
-      // for the home page rather than the HTML convention's bare "/").
-      const path_ = config.contextMenu ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`;
-      const href = (siteUrl ?? '') + path_;
-      let description = truncateDescription(entry.data.description);
-      // Mirrors Mintlify's own behavior: an OpenAPI operation page's
-      // description gets its "METHOD /path" appended, since the page
-      // itself renders almost entirely from the spec at request time
-      // (see ApiPlayground.astro) rather than from frontmatter prose.
-      if (entry.data.openapi) {
-        description = description ? `${description} (${entry.data.openapi})` : entry.data.openapi;
-      }
-      return { title: entry.data.title, href, description, slug };
-    })
-    .sort((a, b) => a.slug.localeCompare(b.slug));
-
-  const lines: string[] = [`# ${config.name}`, ''];
-  if (config.description) lines.push(`> ${config.description}`, '');
-  lines.push('## Docs', '');
-  for (const item of items) {
-    const entryLine = `- [${item.title}](${item.href})${item.description ? `: ${item.description}` : ''}`;
-    lines.push(entryLine);
-  }
-
-  let content = lines.join('\n') + '\n';
-  if (content.length > MAX_CHARS) {
-    // Truncate at the last full line inside the budget, then note how
-    // many entries got cut - rather than silently producing a
-    // mid-sentence-cutoff file, or (worse) one JSON/Markdown-breaking
-    // half-written link.
-    const truncatedLines = lines.slice(0, 4 + (config.description ? 2 : 0)); // "# name" / "" / ["> desc" / ""] / "## Docs" / ""
-    let runningLength = truncatedLines.join('\n').length + 1;
-    let omitted = 0;
-    for (const item of items) {
-      const entryLine = `- [${item.title}](${item.href})${item.description ? `: ${item.description}` : ''}`;
-      if (runningLength + entryLine.length + 1 > MAX_CHARS - 200) {
-        omitted++;
-        continue;
-      }
-      truncatedLines.push(entryLine);
-      runningLength += entryLine.length + 1;
-    }
-    truncatedLines.push('', `_Truncated — ${omitted} more page(s) omitted. See llms-full.txt or the site's own navigation for the complete list._`);
-    content = truncatedLines.join('\n') + '\n';
-  }
-
-  return new Response(content, {
+  const files = await llmsIndexFiles();
+  // null: the project has its own llms.txt at its root, next to
+  // writedocs.json - it replaces the generated one (and its child files)
+  // outright, and a site can fall back by just deleting it.
+  const text = files
+    ? files.get('llms.txt')
+    : fs.readFileSync(path.join(process.env.WRITEDOCS_CONTENT_DIR || process.cwd(), 'llms.txt'), 'utf-8');
+  return new Response(text, {
     headers: { 'Content-Type': 'text/plain; charset=utf-8' },
   });
 };

package/src/scripts/search.ts

@@ -1,17 +1,33 @@
 // SearchModal.astro's own trigger button (rendered inside TopBar.astro) +
 // overlay/modal. Owns opening/closing the modal, the ⌘K/Ctrl K shortcut,
 // lazy-loading Pagefind on first open, and rendering results.
+
+// The current page's modal, for the ⌘K/Ctrl K shortcut. ClientRouter swaps
+// in a new modal on every navigation and initSearch() runs again for it; the
+// shortcut is one document listener, attached once, that always acts on
+// this. (Attached per page, it piled up one listener per visited page, each
+// still driving that page's detached modal - on a page without a modal of
+// its own, Ctrl K then locked the page's scrolling.)
+let active: { toggle(): void; closeIfOpen(): void } | null = null;
+let shortcutBound = false;
+
 export function initSearch(root: ParentNode) {
+  // No trigger button on a `blank` page (no topbar) - the modal and its
+  // shortcut still work there, as BaseLayout.astro intends.
   const trigger = root.querySelector<HTMLButtonElement>('[data-search-trigger]');
   const overlay = root.querySelector<HTMLElement>('#wd-search-overlay');
   const input = root.querySelector<HTMLInputElement>('#wd-search-input');
   const resultsEl = root.querySelector<HTMLElement>('#wd-search-results');
-  if (!trigger || !overlay || !input || !resultsEl || trigger.dataset.wdInit) return;
-  trigger.dataset.wdInit = 'true';
+  if (!overlay || !input || !resultsEl) {
+    active = null;
+    return;
+  }
+  if (overlay.dataset.wdInit) return;
+  overlay.dataset.wdInit = 'true';
 
   // Most keyboards outside macOS/iOS don't have a command key - "Ctrl K"
   // reads more naturally there than the ⌘ glyph.
-  const kbd = trigger.querySelector('.wd-search-kbd');
+  const kbd = trigger?.querySelector('.wd-search-kbd');
   if (kbd && !/Mac|iPhone|iPad/.test(navigator.userAgent)) {
     kbd.textContent = 'Ctrl K';
   }
@@ -122,10 +138,10 @@ export function initSearch(root: ParentNode) {
   function close() {
     overlay.hidden = true;
     document.body.style.overflow = '';
-    trigger.focus();
+    trigger?.focus();
   }
 
-  trigger.addEventListener('click', open);
+  trigger?.addEventListener('click', open);
   overlay.addEventListener('click', (e) => {
     if (e.target === overlay) close();
   });
@@ -143,13 +159,22 @@ export function initSearch(root: ParentNode) {
       close();
     }
   });
-  document.addEventListener('keydown', (e) => {
-    if ((e.key === 'k' || e.key === 'K') && (e.metaKey || e.ctrlKey)) {
-      e.preventDefault();
-      if (overlay.hidden) open();
-      else close();
-    } else if (e.key === 'Escape' && !overlay.hidden) {
-      close();
-    }
-  });
+  active = {
+    toggle: () => (overlay.hidden ? open() : close()),
+    closeIfOpen: () => {
+      if (!overlay.hidden) close();
+    },
+  };
+  if (!shortcutBound) {
+    shortcutBound = true;
+    document.addEventListener('keydown', (e) => {
+      if (!active) return;
+      if ((e.key === 'k' || e.key === 'K') && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        active.toggle();
+      } else if (e.key === 'Escape') {
+        active.closeIfOpen();
+      }
+    });
+  }
 }