@writedocs/generator 0.7.3 → 0.8.0

package/src/lib/mcp-dev-integration.js

@@ -0,0 +1,60 @@
+// `writedocs dev`: the site's MCP server at /mcp, as the build serves it - the
+// same handler (src/mcp/server.js), answering from the dev server's own
+// /mcp-index.json, so an edit shows up on the next request. Lets an author
+// point an MCP client at http://localhost:4321/mcp before deploying.
+import { handleMcpHttp } from '../mcp/server.js';
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+export function mcpDevServer({ version }) {
+  return {
+    name: 'writedocs-mcp-dev',
+    hooks: {
+      'astro:server:setup': ({ server }) => {
+        server.middlewares.use(async (req, res, next) => {
+          const pathname = (req.url ?? '').split('?')[0];
+          if (pathname !== '/mcp' && pathname !== '/mcp/') return next();
+          try {
+            const origin = `http://${req.headers.host}`;
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(req.headers)) {
+              if (typeof value === 'string') headers.set(key, value);
+            }
+            const body = req.method === 'POST' ? await readBody(req) : undefined;
+            const request = new Request(origin + req.url, { method: req.method, headers, body });
+            let missing = false;
+            const response = await handleMcpHttp(request, {
+              version,
+              loadIndex: async () => {
+                const index = await fetch(`${origin}/mcp-index.json`);
+                if (!index.ok) {
+                  missing = true;
+                  return { meta: {}, docs: [] };
+                }
+                return index.json();
+              },
+            });
+            if (missing) {
+              res.statusCode = 404;
+              res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+              res.end('No MCP server: writedocs.json has "mcp": false.');
+              return;
+            }
+            res.statusCode = response.status;
+            response.headers.forEach((value, key) => res.setHeader(key, value));
+            res.end(Buffer.from(await response.arrayBuffer()));
+          } catch (err) {
+            next(err);
+          }
+        });
+      },
+    },
+  };
+}

package/src/lib/mcp-index.ts

@@ -0,0 +1,101 @@
+// mcp-index.json - everything the site's MCP server (src/mcp/server.js)
+// answers from: every page an agent may read, as it should read it. Built
+// from the same pipeline as llms-full.txt (markdownForAgents(): snippets
+// inlined, `variables` filled in, <Visibility> for agents), in navigation
+// order, with each page's real URL and the version/language it sits under in
+// the navigation - what search_docs filters on.
+import { getCollection, type CollectionEntry } from 'astro:content';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  loadDocsConfig,
+  normalizeEntryId,
+  findAllPages,
+  resolveSiteUrl,
+  fileIdForEntry,
+  resolveSections,
+  flattenNav,
+} from './config';
+import { markdownForAgents } from './agent-markdown.js';
+import { orderByNavigation } from './llms.js';
+import { writedocsTempDir } from './writedocs-temp-dir.js';
+
+type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
+
+export interface McpDoc {
+  path: string;
+  url: string;
+  title: string;
+  description: string;
+  content: string;
+  version: string;
+  language: string;
+}
+
+export interface McpIndex {
+  meta: { name: string; description: string; siteUrl: string; generator: 'writedocs' };
+  docs: McpDoc[];
+}
+
+export async function mcpIndex(): Promise<McpIndex> {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+  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;
+  const [pagesEntries, generatedDocsEntries] = await Promise.all([
+    hasPages ? getCollection('pages') : Promise.resolve([]),
+    hasGeneratedDocs ? getCollection('generatedDocs') : Promise.resolve([]),
+  ]);
+  const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
+
+  // The version and language each page sits under, from its section's path
+  // through the navigation (tabs > versions > languages > ...).
+  const sections = resolveSections(config.navigation);
+  const placeOf = (fileId: string) => {
+    const section = sections.find((s) => flattenNav(s.pages).some((e) => e.slug === fileId));
+    const place = { version: '', language: '' };
+    for (const segment of section?.path ?? []) {
+      const item = segment.items[segment.index] as { version?: string; language?: string };
+      if (segment.kind === 'version' && item.version) place.version = item.version;
+      if (segment.kind === 'language' && item.language) place.language = item.language;
+    }
+    return place;
+  };
+
+  const docs = entries
+    // Same pages llms.txt lists: not `noindex`, not a frontmatter `url`
+    // (an external link, with no content of its own).
+    .filter((entry) => !entry.data.seo?.noindex && !entry.data.url)
+    .map((entry) => {
+      const slug = normalizeEntryId(entry.id);
+      const fileId = fileIdForEntry(contentDir, packageRoot, entry);
+      let content = markdownForAgents(entry.body ?? '', {
+        file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
+        contentDir,
+        variables: config.variables,
+      }).trim();
+      // An OpenAPI operation page renders from the spec, so its source body
+      // is near-empty - name the operation, at least.
+      if (entry.data.openapi) content = [`Operation: ${entry.data.openapi}`, content].filter(Boolean).join('\n\n');
+      return {
+        slug,
+        fileId,
+        doc: {
+          path: fileId,
+          url: `${siteUrl}${slug === 'index' ? '/' : `/${slug}/`}`,
+          title: entry.data.title,
+          description: entry.data.description ?? '',
+          content,
+          ...placeOf(fileId),
+        },
+      };
+    });
+
+  return {
+    meta: { name: config.name, description: config.description ?? '', siteUrl, generator: 'writedocs' },
+    docs: orderByNavigation(docs, config.navigation).map((d) => d.doc),
+  };
+}

package/src/lib/pages.js

@@ -61,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(readConfigText(contentDir));
-  } 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:
@@ -198,9 +205,8 @@ export function fileIdForPath(relativePath) {
  *
  *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
  *  by their respective path for deterministic load order across rebuilds
- *  - same reasoning as llms.txt's own alphabetical-by-slug sort (see
- *  llms.txt.ts) - filesystem readdir order isn't guaranteed portable
- *  across OSes or directory-walk order otherwise.
+ *  - 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)

package/src/mcp/server.js

@@ -0,0 +1,262 @@
+// The site's MCP server - lets an AI tool (Claude, Cursor, ...) list, search
+// and read the docs over the Model Context Protocol, at /mcp.
+//
+// Dependency-free and Web-standard (Request in, Response out), so the same
+// code runs wherever the site does: the Cloudflare `_worker.js` that
+// `writedocs build` writes into dist/ (src/cli/write-mcp-files.js - this file
+// is inlined into it), and any other host or serving Worker that imports
+// `@writedocs/generator/mcp` and calls handleMcpHttp() for /mcp. The docs
+// themselves come from the site's mcp-index.json (src/lib/mcp-index.ts),
+// which the build writes next to the pages.
+//
+// Streamable HTTP transport, JSON responses only (no server-sent events),
+// which every protocol version below allows. Keep this file free of imports:
+// the Cloudflare worker inlines its source as-is.
+
+// MCP protocol versions this server speaks, newest first.
+export const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+export const TOOLS = [
+  {
+    name: 'list_docs',
+    description: 'List every documentation page with its title, path, URL and description.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'get_doc',
+    description:
+      'Get the full content of one or more documentation pages, as Markdown. Pass a path or URL from list_docs or search_docs (the page URL works with or without its site address), or an array of them for a batch read.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          oneOf: [
+            { type: 'string', description: 'A page path or URL, e.g. "docs/quickstart" or "/docs/quickstart/"' },
+            { type: 'array', items: { type: 'string' }, description: 'Several page paths or URLs' },
+          ],
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'search_docs',
+    description:
+      'Search the documentation by keywords, returning the best-matching pages with a snippet each. Follow up with get_doc to read a page in full.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search terms' },
+        limit: { type: 'number', description: 'Max results (default 5, max 20)' },
+        version: { type: 'string', description: 'Only pages of this docs version' },
+        language: { type: 'string', description: 'Only pages in this language' },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+const CORS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization, Mcp-Protocol-Version, Mcp-Session-Id',
+};
+
+const json = (body, status = 200, headers = {}) =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json', ...CORS, ...headers } });
+
+/**
+ * Handles one HTTP request to /mcp. `loadIndex()` returns (or resolves to) the
+ * site's mcp-index.json, parsed; `version` is reported as the server's.
+ *
+ *   POST     JSON-RPC - one message or a batch
+ *   GET      an MCP client asking for an event stream (Accept:
+ *            text/event-stream) gets 405, as the spec says; anyone else (a
+ *            browser) gets a description of the server
+ *   OPTIONS  CORS preflight
+ */
+export async function handleMcpHttp(request, { loadIndex, version = '' } = {}) {
+  if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: CORS });
+  if (request.method === 'GET') {
+    if ((request.headers.get('accept') ?? '').includes('text/event-stream')) {
+      return new Response(null, { status: 405, headers: { Allow: 'POST, OPTIONS', ...CORS } });
+    }
+    const index = await loadIndex();
+    return json({
+      name: index.meta?.name ?? 'docs',
+      description: 'An MCP server for these docs. Connect an MCP client to this URL (Streamable HTTP).',
+      server: { name: 'writedocs', version },
+      protocolVersions: PROTOCOL_VERSIONS,
+      pages: index.docs?.length ?? 0,
+      tools: TOOLS.map((t) => ({ name: t.name, description: t.description })),
+    });
+  }
+  if (request.method !== 'POST') return new Response(null, { status: 405, headers: { Allow: 'GET, POST, OPTIONS', ...CORS } });
+
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }, 400);
+  }
+  const index = await loadIndex();
+  if (Array.isArray(body)) {
+    const responses = body.map((message) => handleMcpMessage(message, index, { version })).filter(Boolean);
+    return responses.length ? json(responses) : new Response(null, { status: 202, headers: CORS });
+  }
+  const response = handleMcpMessage(body, index, { version });
+  return response ? json(response) : new Response(null, { status: 202, headers: CORS });
+}
+
+/** One JSON-RPC message -> its response, or null for a notification. */
+export function handleMcpMessage(message, index, { version = '' } = {}) {
+  if (!message || typeof message !== 'object') {
+    return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid request' } };
+  }
+  const id = message.id ?? null;
+  if (message.id === undefined && String(message.method ?? '').startsWith('notifications/')) return null;
+
+  switch (message.method) {
+    case 'initialize': {
+      // The client's version when this server speaks it, else the newest one
+      // it does - the client then decides whether it can go on.
+      const requested = message.params?.protocolVersion;
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: {} },
+          serverInfo: { name: 'writedocs', title: index.meta?.name, version },
+          instructions: index.meta?.name
+            ? `Documentation for ${index.meta.name}. Use search_docs to find pages, get_doc to read them.`
+            : undefined,
+        },
+      };
+    }
+    case 'ping':
+      return { jsonrpc: '2.0', id, result: {} };
+    case 'tools/list':
+      return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+    case 'tools/call': {
+      const { name, arguments: args = {} } = message.params ?? {};
+      return { jsonrpc: '2.0', id, result: callTool(name, args ?? {}, index) };
+    }
+    default:
+      return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${message.method}` } };
+  }
+}
+
+const text = (value, isError = false) => ({ content: [{ type: 'text', text: value }], ...(isError ? { isError: true } : {}) });
+
+function callTool(name, args, index) {
+  const docs = index.docs ?? [];
+  switch (name) {
+    case 'list_docs': {
+      if (!docs.length) return text('This site has no pages.');
+      return text(
+        docs
+          .map((d) => {
+            let line = `${d.path}  -  ${d.title}  (${d.url})`;
+            if (d.description) line += `\n  ${d.description}`;
+            const meta = [d.version, d.language].filter(Boolean).join(', ');
+            if (meta) line += `\n  [${meta}]`;
+            return line;
+          })
+          .join('\n')
+      );
+    }
+
+    case 'get_doc': {
+      const paths = Array.isArray(args.path) ? args.path : [args.path];
+      const found = [];
+      const missing = [];
+      for (const p of paths) {
+        const doc = findDoc(docs, p);
+        if (!doc) {
+          missing.push(String(p ?? ''));
+          continue;
+        }
+        const parts = [`# ${doc.title}`, '', `URL: ${doc.url}`];
+        if (doc.description) parts.push('', `> ${doc.description}`);
+        parts.push('', doc.content);
+        found.push(parts.join('\n'));
+      }
+      const quoted = missing.map((p) => `"${p}"`).join(', ');
+      if (!found.length) return text(`No page found for ${quoted}. Use list_docs or search_docs to find page paths.`, true);
+      if (missing.length) found.push(`> No page found for ${quoted}.`);
+      return text(found.join('\n\n---\n\n'));
+    }
+
+    case 'search_docs': {
+      const query = String(args.query ?? '').trim();
+      if (!query) return text('The query is empty.', true);
+      // A limit that isn't a positive number (a model sent "abc", 0) falls
+      // back to the default instead of returning nothing.
+      const requested = Number(args.limit);
+      const limit = Number.isFinite(requested) && requested >= 1 ? Math.min(Math.floor(requested), 20) : 5;
+      let pool = docs;
+      if (args.version) pool = pool.filter((d) => d.version === String(args.version));
+      if (args.language) pool = pool.filter((d) => d.language === String(args.language));
+      const results = search(pool, query).slice(0, limit);
+      if (!results.length) return text(`No pages match "${query}".`);
+      return text(
+        results
+          .map((d) => {
+            const meta = [d.version, d.language].filter(Boolean).join(', ');
+            return `**${d.title}** (\`${d.path}\`) ${d.url}${meta ? ` [${meta}]` : ''}\n${d.description || snippet(d.content, query)}`;
+          })
+          .join('\n\n')
+      );
+    }
+
+    default:
+      return text(`Unknown tool: ${name}`, true);
+  }
+}
+
+/** The page a path points at, however it's written: its path ("docs/setup"),
+ *  its URL with or without slashes, the full site URL, a ".md" address, or
+ *  "/" for the home page. */
+export function findDoc(docs, value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return undefined;
+  const exact = docs.find((d) => d.path === raw || d.url === raw);
+  if (exact) return exact;
+  const key = (s) => {
+    const p = String(s)
+      .replace(/^https?:\/\/[^/]+/i, '')
+      .replace(/[?#].*$/, '')
+      .replace(/\.mdx?$/i, '')
+      .replace(/^\/+|\/+$/g, '')
+      .replace(/(^|\/)index$/, '');
+    return p || 'index';
+  };
+  const wanted = key(raw);
+  return docs.find((d) => key(d.url) === wanted || key(d.path) === wanted);
+}
+
+/** Pages scored by how often the query's words occur - title matches count
+ *  most - best first. */
+function search(docs, query) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const count = (haystack, word) => haystack.split(word).length - 1;
+  return docs
+    .map((doc) => {
+      const title = doc.title.toLowerCase();
+      const body = `${doc.description ?? ''} ${doc.content}`.toLowerCase();
+      const score = words.reduce((s, w) => s + count(title, w) * 5 + count(body, w), 0);
+      return { doc, score };
+    })
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map((r) => r.doc);
+}
+
+function snippet(content, query) {
+  const word = query.toLowerCase().split(/\s+/)[0];
+  const at = content.toLowerCase().indexOf(word);
+  const start = Math.max(0, at - 60);
+  const end = Math.min(content.length, (at < 0 ? 0 : at) + 180);
+  return (start > 0 ? '...' : '') + content.slice(start, end).replace(/\s+/g, ' ').trim() + (end < content.length ? '...' : '');
+}

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/[mcpIndex].json.ts

@@ -0,0 +1,16 @@
+import type { APIRoute } from 'astro';
+import { loadDocsConfig } from '../lib/config';
+import { mcpIndex } from '../lib/mcp-index';
+
+// /mcp-index.json - the pages the site's MCP server answers from (see
+// lib/mcp-index.ts and src/mcp/server.js). A dynamic route only so it can be
+// left out: writedocs.json `"mcp": false` gives no paths, so no file.
+export async function getStaticPaths() {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+  return loadDocsConfig(contentDir).mcp ? [{ params: { mcpIndex: 'mcp-index' } }] : [];
+}
+
+export const GET: APIRoute = async () =>
+  new Response(JSON.stringify(await mcpIndex()), {
+    headers: { 'Content-Type': 'application/json; 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';