From c08ba960846f449808727a6023ff86f677e367f2 Mon Sep 17 00:00:00 2001
From: developerjamiu <developerjamiu@gmail.com>
Date: Wed, 12 Aug 2026 16:26:19 +0100
Subject: [PATCH 1/2] feat: Publish a markdown export of every docs page with
 llms.txt

---
 .github/workflows/deploy.yml       |  12 +-
 .github/workflows/test-build.yml   |   4 +-
 README.md                          |  11 +
 docusaurus.config.js               |  91 +------
 package-lock.json                  |  29 ++-
 package.json                       |   7 +-
 plugins/markdown-export/flatten.js | 397 +++++++++++++++++++++++++++++
 plugins/markdown-export/index.js   | 317 +++++++++++++++++++++++
 plugins/markdown-export/llms.js    |  63 +++++
 plugins/markdown-export/urls.js    |  51 ++++
 redirects.js                       |  89 +++++++
 static/robots.txt                  |  11 +
 util/verify_markdown_export.js     | 286 +++++++++++++++++++++
 13 files changed, 1268 insertions(+), 100 deletions(-)
 create mode 100644 plugins/markdown-export/flatten.js
 create mode 100644 plugins/markdown-export/index.js
 create mode 100644 plugins/markdown-export/llms.js
 create mode 100644 plugins/markdown-export/urls.js
 create mode 100644 redirects.js
 create mode 100644 static/robots.txt
 create mode 100644 util/verify_markdown_export.js

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index afb18f43..87bd7c0e 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -26,6 +26,10 @@ jobs:
               cd src
               npm ci
               npm run build
+        - name: Verify markdown export
+          run: |
+              cd src
+              node util/verify_markdown_export.js
         - uses: actions/checkout@v4
           with:
               path: target
@@ -36,9 +40,13 @@ jobs:
           run: |
               git config --global user.email "serverpod_docs@serverpod.dev"
               git config --global user.name "serverpod_docs"
-              rm -rf target/docs/*
+              # Dotfiles must deploy too (.nojekyll keeps GitHub Pages from
+              # running Jekyll over the generated .md files), so copy the
+              # directory contents rather than a dotfile-skipping glob.
+              rm -rf target/docs
+              mkdir -p target/docs
               cp target/CNAME target/docs
-              cp -r src/build/* target/docs
+              cp -a src/build/. target/docs
               cd target
               git add .
               if git diff --cached --quiet; then
diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
index 690bfef2..5caa36ac 100644
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -32,4 +32,6 @@ jobs:
             - name: Install dependencies
               run: npm ci 
             - name: Build
-              run: npm run build
\ No newline at end of file
+              run: npm run build
+            - name: Verify markdown export
+              run: node util/verify_markdown_export.js
\ No newline at end of file
diff --git a/README.md b/README.md
index 7484bb70..d44bbfee 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,17 @@ To maintain link integrity when relocating or renaming documentation pages, it's
 
 Once a PR is merged into the `main` branch of this repository, a GitHub action is triggered that builds the documentation and pushes the build to the `docs` directory within the `serverpod.github.io` repository. The built documentation is committed as a new commit to the `main` branch and is then deployed to Github pages by the `serverpod.github.io` repository.
 
+### Markdown export (llms.txt and per-page .md)
+
+The local plugin in `plugins/markdown-export` publishes a clean markdown version of every doc page at its page URL with `.md` appended, plus `llms.txt`, `llms-full.txt`, and `cloud/llms-full.txt` at the site root. The "Copy as Markdown" button on every page fetches these files. Things to know:
+
+- The llms files always describe the current stable version, derived from `versions.json`; nothing needs updating when a new version is cut. The plugin logs the export size and duration on every build.
+- Links between doc pages inside the exports point at the target's `.md` version, so an agent reading one page can follow links to more markdown.
+- Renamed pages keep their HTML redirect only. The old `.md` URL becomes a one-line "moved to" stub, generated from `redirects.js`.
+- `static/robots.txt` disallows crawling of `*.md` to keep the duplicates out of search engines; `llms.txt` stays crawlable on purpose.
+- `node util/verify_markdown_export.js` checks the export after a build. CI runs it on every PR.
+- GitHub Pages only serves the `.md` files raw because Jekyll is disabled via `.nojekyll`; the deploy workflow copies that file explicitly.
+
 ### Formatting
 
 To ensure consistent formatting, we use markdownlint [(VS Code Extension)](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 70112c00..3e16f281 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -4,6 +4,7 @@
 import {
   themes
 } from 'prism-react-renderer';
+import {SITE_URL, BASE_URL} from './plugins/markdown-export/urls.js';
 const lightCodeTheme = themes.github;
 const darkCodeTheme = themes.dracula;
 
@@ -11,8 +12,8 @@ const darkCodeTheme = themes.dracula;
 const config = {
   title: 'Serverpod',
   tagline: 'The missing server for Flutter',
-  url: 'https://docs.serverpod.dev',
-  baseUrl: '/',
+  url: SITE_URL,
+  baseUrl: BASE_URL,
   onBrokenLinks: 'throw',
   onBrokenAnchors: 'throw',
   favicon: 'img/favicon.png',
@@ -147,6 +148,7 @@ const config = {
         breadcrumbs: false,
       },
     ],
+    './plugins/markdown-export',
     [
       'docusaurus-plugin-snipsync',
       {
@@ -182,90 +184,7 @@ const config = {
     [
       '@docusaurus/plugin-client-redirects',
       {
-        redirects: [{
-            // Moved in version 1.1.1
-            from: ['/concepts/authentication'],
-            to: '/concepts/authentication/setup',
-          },
-          {
-            // Moved in version 1.1.1, 2.1.0 and 2.9.0
-            from: ['/tutorials', '/tutorials/videos', '/tutorials/first-app'],
-            to: '/tutorials/tutorials/fundamentals',
-          },
-          {
-            // Moved in version 1.2.0
-            from: ['/concepts/database-communication'],
-            to: '/concepts/database/connection',
-          },
-          {
-            // Moved in version 2.1.0
-            from: ['/insights'],
-            to: '/tools/insights',
-          },
-          {
-            // Moved in version 2.1.0
-            from: ['/roadmap'],
-            to: '/contribute',
-          },
-          {
-            // Moved in version 2.7.0
-            from: ['/get-started'],
-            to: '/get-started/creating-endpoints',
-          },
-          {
-            // Moved when scheduling was reorganized from a single page to a directory
-            from: ['/concepts/scheduling'],
-            to: '/concepts/scheduling/setup',
-          },
-          {
-            from: ['/cloud/reference/deployment/deploying-your-application'],
-            to: '/cloud/concepts/deployments',
-          },
-          {
-            from: ['/cloud/guides/logs', '/cloud/reference/logging'],
-            to: '/cloud/concepts/logs',
-          },
-          {
-            from: ['/cloud/guides/passwords'],
-            to: '/cloud/concepts/passwords-secrets-env-vars',
-          },
-          {
-            from: ['/cloud/guides/custom-domains'],
-            to: '/cloud/concepts/custom-domains',
-          },
-          {
-            from: ['/cloud/guides/database'],
-            to: '/cloud/concepts/database',
-          },
-          {
-            from: ['/cloud/reference/personal-access-tokens'],
-            to: '/cloud/concepts/personal-access-tokens',
-          },
-          {
-            from: ['/cloud/reference/deployment/assets'],
-            to: '/cloud/guides/ship-non-dart-files',
-          },
-          {
-            from: ['/cloud/reference/deployment/deployment-hooks'],
-            to: '/cloud/concepts/deployment-hooks',
-          },
-          {
-            from: ['/cloud/reference/deployment/github-automation'],
-            to: '/cloud/guides/deploy-from-ci-with-github-actions',
-          },
-          {
-            from: ['/cloud/reference/deployment/handling-private-dependencies'],
-            to: '/cloud/reference/private-dependencies',
-          },
-          {
-            from: ['/cloud/reference/deployment/dart-sdk-versions'],
-            to: '/cloud/reference/dart-sdk-versions',
-          },
-          {
-            from: ['/cloud/reference/project-id'],
-            to: '/cloud/reference/project-id-rules',
-          },
-        ],
+        redirects: require('./redirects'),
       },
     ],
   ],
diff --git a/package-lock.json b/package-lock.json
index 0fd9fa23..59f7ac2f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -21,7 +21,12 @@
         "prism-react-renderer": "^2.4.1",
         "react": "^19.2.8",
         "react-dom": "^19.2.8",
-        "react-player": "^3.4.0"
+        "react-player": "^3.4.0",
+        "remark-gfm": "^4.0.1",
+        "remark-mdx": "^3.1.1",
+        "remark-parse": "^11.0.0",
+        "remark-stringify": "^11.0.0",
+        "unified": "^11.0.5"
       },
       "devDependencies": {
         "docusaurus-plugin-snipsync": "^1.0.0",
@@ -16910,9 +16915,10 @@
       }
     },
     "node_modules/remark-mdx": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/remark-mdx/-/remark-mdx-3.0.0.tgz",
-      "integrity": "sha512-O7yfjuC6ra3NHPbRVxfflafAj3LTwx3b73aBvkEFU5z4PsD6FD4vrqJAkE5iNGLz71GdjXfgRqm3SQ0h0VuE7g==",
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/remark-mdx/-/remark-mdx-3.1.1.tgz",
+      "integrity": "sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==",
+      "license": "MIT",
       "dependencies": {
         "mdast-util-mdx": "^3.0.0",
         "micromark-extension-mdxjs": "^3.0.0"
@@ -16926,6 +16932,7 @@
       "version": "11.0.0",
       "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz",
       "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==",
+      "license": "MIT",
       "dependencies": {
         "@types/mdast": "^4.0.0",
         "mdast-util-from-markdown": "^2.0.0",
@@ -18561,9 +18568,10 @@
       }
     },
     "node_modules/unified": {
-      "version": "11.0.4",
-      "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.4.tgz",
-      "integrity": "sha512-apMPnyLjAX+ty4OrNap7yumyVAMlKx5IWU2wlzzUdYJO9A8f1p9m/gywF/GM2ZDFcjQPrx59Mc90KwmxsoklxQ==",
+      "version": "11.0.5",
+      "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz",
+      "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^3.0.0",
         "bail": "^2.0.0",
@@ -18655,9 +18663,10 @@
       }
     },
     "node_modules/unist-util-visit": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.0.0.tgz",
-      "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==",
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.1.0.tgz",
+      "integrity": "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==",
+      "license": "MIT",
       "dependencies": {
         "@types/unist": "^3.0.0",
         "unist-util-is": "^6.0.0",
diff --git a/package.json b/package.json
index ebbc72f7..899abb6c 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,12 @@
     "prism-react-renderer": "^2.4.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "react-player": "^3.4.0"
+    "react-player": "^3.4.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx": "^3.1.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "unified": "^11.0.5"
   },
   "engines": {
     "node": ">=18.0"
diff --git a/plugins/markdown-export/flatten.js b/plugins/markdown-export/flatten.js
new file mode 100644
index 00000000..b4fdcc4b
--- /dev/null
+++ b/plugins/markdown-export/flatten.js
@@ -0,0 +1,397 @@
+// Flattens a doc's MDX/markdown source into clean, self-contained markdown:
+// partial imports inlined, Tabs unwrapped, video embeds turned into links,
+// snipsync markers and HTML comments stripped, and links rewritten to
+// absolute URLs.
+//
+// Front matter and titles go through @docusaurus/utils so this pipeline
+// parses sources exactly the way the site build does. The remark toolchain
+// is ESM-only, so it is loaded through dynamic import from this CommonJS
+// module.
+
+const fs = require('fs');
+const path = require('path');
+const {
+  DEFAULT_PARSE_FRONT_MATTER,
+  escapeMarkdownHeadingIds,
+  parseMarkdownContentTitle,
+} = require('@docusaurus/utils');
+
+const urls = require('./urls');
+
+let toolchainPromise;
+function toolchain() {
+  if (!toolchainPromise) {
+    toolchainPromise = (async () => {
+      const [
+        {unified},
+        {default: remarkParse},
+        {default: remarkStringify},
+        {default: remarkMdx},
+        {default: remarkGfm},
+      ] = await Promise.all([
+        import('unified'),
+        import('remark-parse'),
+        import('remark-stringify'),
+        import('remark-mdx'),
+        import('remark-gfm'),
+      ]);
+      return {
+        mdxParser: unified().use(remarkParse).use(remarkMdx).use(remarkGfm),
+        mdParser: unified().use(remarkParse).use(remarkGfm),
+        stringifier: unified().use(remarkGfm).use(remarkStringify, {
+          bullet: '-',
+          fences: true,
+          resourceLink: true,
+        }),
+      };
+    })();
+  }
+  return toolchainPromise;
+}
+
+const IMPORT_RE = /import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g;
+
+/**
+ * Trim whitespace at the edges of a node list, so unwrapped JSX like
+ * `<summary> Click…</summary>` does not serialize an escaped leading space.
+ */
+function trimTextEdges(nodes) {
+  const first = nodes[0];
+  if (first && first.type === 'text') {
+    first.value = first.value.replace(/^\s+/, '');
+  }
+  const last = nodes[nodes.length - 1];
+  if (last && last.type === 'text') {
+    last.value = last.value.replace(/\s+$/, '');
+  }
+}
+
+function jsxAttr(node, name) {
+  for (const attr of node.attributes || []) {
+    if (attr.type === 'mdxJsxAttribute' && attr.name === name && typeof attr.value === 'string') {
+      return attr.value;
+    }
+  }
+  return undefined;
+}
+
+function textOf(node) {
+  if (node.type === 'text' || node.type === 'inlineCode') {
+    return node.value;
+  }
+  return (node.children || []).map(textOf).join('');
+}
+
+function splitAnchor(url) {
+  const hash = url.indexOf('#');
+  if (hash === -1) {
+    return { target: url, anchor: '' };
+  }
+  return { target: url.slice(0, hash), anchor: url.slice(hash) };
+}
+
+function isExternal(url) {
+  return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(url);
+}
+
+/** Resolve an import/link source spec to an absolute file path. */
+function resolveSourcePath(spec, fileDir, siteDir) {
+  if (spec.startsWith('@site/')) {
+    return path.join(siteDir, spec.slice('@site/'.length));
+  }
+  return path.resolve(fileDir, spec);
+}
+
+/**
+ * Rewrite a file-style link (ending .md/.mdx) found in `filePath` to an
+ * absolute .md URL, using the source-to-permalink map. Unknown targets pass
+ * through and surface later as broken absolute links in the CI link check.
+ */
+function rewriteFileLink(url, filePath, shared) {
+  const { target, anchor } = splitAnchor(url);
+  if (!/\.(md|mdx)$/.test(target) || isExternal(target)) {
+    return url;
+  }
+  if (target.startsWith('/') || (target.startsWith('@') && !target.startsWith('@site/'))) {
+    return url;
+  }
+  const resolved = resolveSourcePath(target, path.dirname(filePath), shared.siteDir);
+  const permalink = shared.sourceToPermalink.get(resolved);
+  if (!permalink) {
+    return url;
+  }
+  return `${urls.mdUrl(permalink)}${anchor}`;
+}
+
+/**
+ * Remove HTML comments outside fenced code blocks (the MDX loader does the
+ * same before compiling; this also strips the snipsync markers). Comments
+ * inside code fences are sample code and stay untouched.
+ */
+function stripHtmlComments(content) {
+  const out = [];
+  let inFence = false;
+  let inComment = false;
+  for (let line of content.split('\n')) {
+    if (inFence) {
+      out.push(line);
+      if (/^\s*(```|~~~)/.test(line)) {
+        inFence = false;
+      }
+      continue;
+    }
+    if (inComment) {
+      const close = line.indexOf('-->');
+      if (close === -1) {
+        continue;
+      }
+      line = line.slice(close + 3);
+      inComment = false;
+    }
+    line = line.replace(/<!--[\s\S]*?-->/g, '');
+    const open = line.indexOf('<!--');
+    if (open !== -1) {
+      line = line.slice(0, open);
+      inComment = true;
+    }
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = true;
+    }
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+/**
+ * Parse markdown/MDX body text into an mdast tree, mirroring how the site
+ * compiles: comments stripped and heading IDs escaped first (so `{#id}`
+ * anchors survive into the output text), CommonMark as the .md fallback.
+ */
+async function parseBody(filePath, body) {
+  const { mdxParser, mdParser } = await toolchain();
+  const prepared = stripHtmlComments(escapeMarkdownHeadingIds(body));
+  try {
+    return mdxParser.parse(prepared);
+  } catch (mdxError) {
+    if (filePath.endsWith('.mdx')) {
+      throw new Error(`Failed to parse ${filePath}: ${mdxError.message}`);
+    }
+    return mdParser.parse(prepared);
+  }
+}
+
+/**
+ * Recursively transform a node list: drop imports/expressions, inline
+ * partials, unwrap JSX, rewrite file-style links. Unknown childless JSX is
+ * recorded on shared.droppedJsx: deleting a node that carries its meaning in
+ * attributes must be a visible decision, never a silent default.
+ */
+async function transformNodes(nodes, ctx) {
+  const out = [];
+  for (const node of nodes || []) {
+    switch (node.type) {
+      case 'mdxjsEsm': {
+        for (const match of node.value.matchAll(IMPORT_RE)) {
+          const [, name, source] = match;
+          if (/\.(md|mdx)$/.test(source) && (!source.startsWith('@') || source.startsWith('@site/'))) {
+            ctx.imports.set(name, resolveSourcePath(source, ctx.dir, ctx.shared.siteDir));
+          }
+        }
+        break;
+      }
+      case 'mdxFlowExpression':
+      case 'mdxTextExpression':
+        break;
+      case 'mdxJsxFlowElement':
+      case 'mdxJsxTextElement': {
+        const partialPath = node.name ? ctx.imports.get(node.name) : undefined;
+        if (partialPath) {
+          out.push(...(await flattenPartial(partialPath, ctx.shared, ctx.stack)));
+        } else if (node.name === 'TabItem') {
+          const label = jsxAttr(node, 'label') || jsxAttr(node, 'value');
+          if (label) {
+            out.push({
+              type: 'paragraph',
+              children: [{ type: 'strong', children: [{ type: 'text', value: label }] }],
+            });
+          }
+          out.push(...(await transformNodes(node.children, ctx)));
+        } else if (node.name === 'ReactPlayer' || node.name === 'iframe' || node.name === 'video') {
+          const url = jsxAttr(node, 'url') || jsxAttr(node, 'src');
+          if (url) {
+            out.push({
+              type: 'paragraph',
+              children: [
+                { type: 'link', url, children: [{ type: 'text', value: 'Watch the video' }] },
+              ],
+            });
+          }
+        } else if (node.name === 'img') {
+          const src = jsxAttr(node, 'src');
+          if (src) {
+            out.push({ type: 'image', url: src, alt: jsxAttr(node, 'alt') || '' });
+          }
+        } else if (node.name === 'br') {
+          // Dropping a void <br/> outright fuses the words around it.
+          out.push({ type: 'text', value: ' ' });
+        } else {
+          // Tabs and any other JSX wrapper: keep the content, drop the tag.
+          const kids = await transformNodes(node.children, ctx);
+          if (kids.length === 0 && (node.children || []).length === 0 && node.name) {
+            const count = ctx.shared.droppedJsx.get(node.name) || 0;
+            ctx.shared.droppedJsx.set(node.name, count + 1);
+          }
+          if (node.type === 'mdxJsxFlowElement') {
+            trimTextEdges(kids);
+          }
+          out.push(...kids);
+        }
+        break;
+      }
+      default: {
+        if (node.type === 'link' || node.type === 'definition') {
+          node.url = rewriteFileLink(node.url, ctx.filePath, ctx.shared);
+        }
+        if (Array.isArray(node.children)) {
+          node.children = await transformNodes(node.children, ctx);
+        }
+        out.push(node);
+      }
+    }
+  }
+  return out;
+}
+
+/** Parse a source file into {frontMatter, body} the way Docusaurus does. */
+async function parseSource(filePath) {
+  const fileContent = fs.readFileSync(filePath, 'utf8');
+  const { frontMatter, content } = await DEFAULT_PARSE_FRONT_MATTER({
+    filePath,
+    fileContent,
+  });
+  return { frontMatter, body: content };
+}
+
+/** Parse and transform one file's body into mdast children. */
+async function flattenBody(filePath, body, shared, stack) {
+  if (stack.has(filePath)) {
+    throw new Error(`Circular partial import involving ${filePath}`);
+  }
+  stack.add(filePath);
+  const tree = await parseBody(filePath, body);
+  const ctx = {
+    filePath,
+    dir: path.dirname(filePath),
+    imports: new Map(),
+    shared,
+    stack,
+  };
+  const children = await transformNodes(tree.children, ctx);
+  stack.delete(filePath);
+  return { children, usedPartials: ctx.imports.size > 0 };
+}
+
+// Partials are cached by path + mtime and deep-cloned per use: the
+// page-level link pass mutates nodes, and a shared subtree must not leak one
+// host page's rewrites into another.
+const partialCache = new Map();
+
+async function flattenPartial(filePath, shared, stack) {
+  const mtimeMs = fs.statSync(filePath).mtimeMs;
+  const cached = partialCache.get(filePath);
+  if (cached && cached.mtimeMs === mtimeMs) {
+    return structuredClone(cached.children);
+  }
+  const { body } = await parseSource(filePath);
+  const { children } = await flattenBody(filePath, body, shared, stack);
+  partialCache.set(filePath, { mtimeMs, children });
+  return structuredClone(children);
+}
+
+/**
+ * Page-level link pass: make every remaining relative URL absolute. URL-style
+ * relative links resolve against the page's permalink (matching how the
+ * browser resolves them on the rendered page); links to doc pages point at
+ * the page's .md version.
+ */
+function absolutizeLinks(nodes, permalink, shared) {
+  const baseDir = path.posix.dirname(permalink === '/' ? '/index' : permalink);
+  const rewrite = (url, isImage) => {
+    if (isExternal(url) || url.startsWith('#')) {
+      return url;
+    }
+    const { target, anchor } = splitAnchor(url);
+    if (target === '') {
+      return url;
+    }
+    let routePath = target.startsWith('/')
+      ? path.posix.normalize(target)
+      : path.posix.resolve(baseDir, target);
+    routePath = urls.normalizePermalink(routePath);
+    if (!isImage && shared.permalinks.has(routePath)) {
+      return `${urls.mdUrl(routePath)}${anchor}`;
+    }
+    return `${urls.SITE_URL}${routePath}${anchor}`;
+  };
+  const walk = (list) => {
+    for (const node of list || []) {
+      if (node.type === 'link' || node.type === 'definition') {
+        node.url = rewrite(node.url, false);
+      } else if (node.type === 'image') {
+        node.url = rewrite(node.url, true);
+      } else if (node.type === 'paragraph') {
+        // Unwrapped inline JSX can leave paragraph-edge whitespace, which
+        // stringify would escape as `&#x20;`.
+        trimTextEdges(node.children);
+      }
+      if (Array.isArray(node.children)) {
+        walk(node.children);
+      }
+    }
+  };
+  walk(nodes);
+}
+
+/**
+ * Flatten a doc to its final markdown. Title chain: frontmatter title, else
+ * the content H1 (promoted, not duplicated; a leading H1 that differs from
+ * an explicit frontmatter title stays in the body), else the H1 a flattened
+ * partial contributed, else the Docusaurus-computed title.
+ */
+async function flattenDoc(doc, sourcePath, shared) {
+  const { stringifier } = await toolchain();
+  const { frontMatter, body } = await parseSource(sourcePath);
+  const fmTitle =
+    typeof frontMatter.title === 'string' && frontMatter.title.trim()
+      ? frontMatter.title.trim()
+      : undefined;
+  const { content: bodyContent, contentTitle } = parseMarkdownContentTitle(body, {
+    removeContentTitle: true,
+  });
+
+  const { children, usedPartials } = await flattenBody(
+    sourcePath,
+    bodyContent,
+    shared,
+    new Set()
+  );
+
+  let partialTitle;
+  if (children.length > 0 && children[0].type === 'heading' && children[0].depth === 1) {
+    const text = textOf(children[0]).trim();
+    if (!fmTitle || text === fmTitle) {
+      partialTitle = text;
+      children.shift();
+    }
+  }
+  const title =
+    fmTitle || contentTitle || partialTitle || (doc.title && doc.title.trim()) || doc.id;
+
+  absolutizeLinks(children, doc.permalink, shared);
+
+  const markdownBody = stringifier.stringify({ type: 'root', children }).trim();
+  const markdown = `# ${title}\n\n${urls.pageUrl(doc.permalink)}\n\n${markdownBody}\n`;
+  return { title, markdown, usedPartials };
+}
+
+module.exports = { flattenDoc };
diff --git a/plugins/markdown-export/index.js b/plugins/markdown-export/index.js
new file mode 100644
index 00000000..65bc1a90
--- /dev/null
+++ b/plugins/markdown-export/index.js
@@ -0,0 +1,317 @@
+// Docusaurus plugin that publishes a clean markdown version of every doc page
+// at its page URL with `.md` appended, plus llms.txt and per-instance
+// llms-full.txt discovery files at the site root.
+//
+// Files are generated during `allContentLoaded` (which runs after every
+// plugin's `loadContent`, so snipsync has finished mutating sources by then)
+// and copied into the build output during `postBuild`. In dev, the generated
+// directory is served through the dev server's static file handling, so
+// `.md` URLs resolve the same way they do in production.
+
+const fs = require('fs');
+const path = require('path');
+const { aliasedSitePathToRelativePath } = require('@docusaurus/utils');
+
+const { flattenDoc } = require('./flatten');
+const { buildLlmsTxt, buildLlmsFullTxt } = require('./llms');
+const { normalizePermalink, mdFilePath, mdUrl } = require('./urls');
+
+const PLUGIN_NAME = 'serverpod-markdown-export';
+const DOCS_PLUGIN = 'docusaurus-plugin-content-docs';
+const REDIRECTS_PLUGIN = '@docusaurus/plugin-client-redirects';
+
+/** Collect doc ids in sidebar order; docs order for anything unlisted. */
+function sidebarOrderedDocs(version) {
+  const orderedIds = [];
+  const walk = (items) => {
+    for (const item of items || []) {
+      if (item.type === 'doc' || item.type === 'ref') {
+        orderedIds.push(item.id);
+      } else if (item.type === 'category') {
+        if (item.link && item.link.type === 'doc') {
+          orderedIds.push(item.link.id);
+        }
+        walk(item.items);
+      }
+    }
+  };
+  for (const sidebar of Object.values(version.sidebars || {})) {
+    walk(sidebar);
+  }
+  const byId = new Map(version.docs.map((d) => [d.id, d]));
+  const ordered = [];
+  const seen = new Set();
+  for (const id of orderedIds) {
+    const doc = byId.get(id);
+    if (doc && !seen.has(doc.permalink)) {
+      seen.add(doc.permalink);
+      ordered.push(doc);
+    }
+  }
+  for (const doc of version.docs) {
+    if (!seen.has(doc.permalink)) {
+      seen.add(doc.permalink);
+      ordered.push(doc);
+    }
+  }
+  return ordered;
+}
+
+/** Extract the client-redirects source→target pairs from the site config. */
+function redirectPairs(siteConfig) {
+  const entry = (siteConfig.plugins || []).find(
+    (p) => Array.isArray(p) && p[0] === REDIRECTS_PLUGIN
+  );
+  if (!entry || !entry[1] || !Array.isArray(entry[1].redirects)) {
+    // Fail hard: silently emitting zero stubs would pass CI vacuously.
+    throw new Error(
+      `${PLUGIN_NAME}: could not find the ${REDIRECTS_PLUGIN} config; ` +
+        'the "moved to" stubs derive from it.'
+    );
+  }
+  const pairs = [];
+  for (const rule of entry[1].redirects) {
+    const froms = Array.isArray(rule.from) ? rule.from : [rule.from];
+    for (const from of froms) {
+      pairs.push({ from, to: rule.to });
+    }
+  }
+  return pairs;
+}
+
+// Per-source flatten cache, keyed by mtime, so a dev reload (which re-runs
+// allContentLoaded for every content edit) only re-flattens changed files.
+// Pages that inline partials are always re-flattened: their output depends
+// on the partials' files too, and there are only a few dozen of them.
+const flattenCache = new Map();
+
+async function flattenWithCache(descriptor, sourcePath, shared) {
+  const mtimeMs = fs.statSync(sourcePath).mtimeMs;
+  const cached = flattenCache.get(sourcePath);
+  if (cached && cached.mtimeMs === mtimeMs && !cached.result.usedPartials) {
+    return cached.result;
+  }
+  const result = await flattenDoc(descriptor, sourcePath, shared);
+  flattenCache.set(sourcePath, { mtimeMs, result });
+  return result;
+}
+
+module.exports = function markdownExportPlugin(context) {
+  const genDir = path.join(context.generatedFilesDir, PLUGIN_NAME);
+  const manifestPath = path.join(
+    context.generatedFilesDir,
+    'markdown-export-manifest.json'
+  );
+  let firstRun = true;
+
+  return {
+    name: PLUGIN_NAME,
+
+    async allContentLoaded({ allContent }) {
+      const startedAt = Date.now();
+      const isDev = process.env.NODE_ENV !== 'production';
+      const instances = allContent[DOCS_PLUGIN] || {};
+
+      const frameworkStable = (instances.default?.loadedVersions || []).find(
+        (v) => v.isLast
+      );
+      const cloudVersions = instances.cloud?.loadedVersions || [];
+      const cloudCurrent = cloudVersions.find((v) => v.isLast) || cloudVersions[0];
+      if (!frameworkStable || !cloudCurrent) {
+        // Fail hard: an empty llms selection would otherwise ship silently.
+        throw new Error(
+          `${PLUGIN_NAME}: could not resolve the stable framework version ` +
+            'or the cloud docs instance for the llms files.'
+        );
+      }
+
+      // Pass 1: index every doc of every instance and version, so link
+      // rewriting can map any source file or route to its permalink. Docs
+      // are carried as lightweight descriptors with normalized permalinks;
+      // the loaded content objects are never mutated. In dev, archived
+      // framework versions are indexed but not rendered: a content edit
+      // re-runs this whole hook, and re-flattening 18 immutable trees per
+      // keystroke would stall the reload.
+      const docs = [];
+      const sourceToPermalink = new Map();
+      const permalinks = new Set();
+      for (const [instanceId, content] of Object.entries(instances)) {
+        for (const version of content.loadedVersions) {
+          const render =
+            !isDev ||
+            instanceId !== 'default' ||
+            version.isLast ||
+            version.versionName === 'current';
+          for (const doc of version.docs) {
+            const sourcePath = path.join(
+              context.siteDir,
+              aliasedSitePathToRelativePath(doc.source)
+            );
+            const permalink = normalizePermalink(doc.permalink);
+            docs.push({
+              descriptor: { id: doc.id, title: doc.title, permalink },
+              sourcePath,
+              render,
+            });
+            sourceToPermalink.set(sourcePath, permalink);
+            permalinks.add(permalink);
+          }
+        }
+      }
+
+      // The llms files only need the rendered markdown of current stable and
+      // Cloud pages; everything else streams straight to disk.
+      const llmsPermalinks = new Set(
+        [...frameworkStable.docs, ...cloudCurrent.docs].map((d) =>
+          normalizePermalink(d.permalink)
+        )
+      );
+
+      // Pass 2: flatten and write, mirrored by permalink. The gen dir is
+      // only wiped on the first run; dev reloads overwrite in place so the
+      // dev server never serves from a half-empty directory.
+      if (firstRun) {
+        fs.rmSync(genDir, { recursive: true, force: true });
+        firstRun = false;
+      }
+      fs.mkdirSync(genDir, { recursive: true });
+      const rendered = new Map(); // llms permalink -> markdown
+      const titles = new Map(); // llms permalink -> title
+      const createdDirs = new Set();
+      const shared = {
+        siteDir: context.siteDir,
+        sourceToPermalink,
+        permalinks,
+        droppedJsx: new Map(),
+      };
+      let written = 0;
+      for (const entry of docs) {
+        if (!entry.render) {
+          continue;
+        }
+        const { title, markdown } = await flattenWithCache(
+          entry.descriptor,
+          entry.sourcePath,
+          shared
+        );
+        const permalink = entry.descriptor.permalink;
+        if (llmsPermalinks.has(permalink)) {
+          rendered.set(permalink, markdown);
+          titles.set(permalink, title);
+        }
+        const outFile = path.join(genDir, mdFilePath(permalink));
+        const outDirName = path.dirname(outFile);
+        if (!createdDirs.has(outDirName)) {
+          fs.mkdirSync(outDirName, { recursive: true });
+          createdDirs.add(outDirName);
+        }
+        fs.writeFileSync(outFile, markdown);
+        written += 1;
+      }
+
+      if (shared.droppedJsx.size > 0) {
+        const summary = [...shared.droppedJsx.entries()]
+          .map(([name, count]) => `<${name}> x${count}`)
+          .join(', ');
+        console.warn(
+          `[${PLUGIN_NAME}] Dropped childless JSX with no markdown mapping: ` +
+            `${summary}. Add a rule in flatten.js if the content matters.`
+        );
+      }
+
+      const toDescriptor = (doc) => {
+        const permalink = normalizePermalink(doc.permalink);
+        return {
+          id: doc.id,
+          title: titles.get(permalink) || doc.title || doc.id,
+          description: doc.description,
+          permalink,
+        };
+      };
+      const frameworkDocs = sidebarOrderedDocs(frameworkStable).map(toDescriptor);
+      const cloudDocs = sidebarOrderedDocs(cloudCurrent).map(toDescriptor);
+
+      fs.writeFileSync(
+        path.join(genDir, 'llms.txt'),
+        buildLlmsTxt({ frameworkDocs, cloudDocs })
+      );
+      fs.writeFileSync(
+        path.join(genDir, 'llms-full.txt'),
+        buildLlmsFullTxt({
+          title: 'Serverpod framework documentation',
+          summary:
+            'The current stable Serverpod framework documentation as a single ' +
+            'markdown file. Every page starts with its title and canonical URL.',
+          docs: frameworkDocs,
+          rendered,
+        })
+      );
+      fs.mkdirSync(path.join(genDir, 'cloud'), { recursive: true });
+      fs.writeFileSync(
+        path.join(genDir, 'cloud', 'llms-full.txt'),
+        buildLlmsFullTxt({
+          title: 'Serverpod Cloud documentation',
+          summary:
+            'The Serverpod Cloud documentation as a single markdown file. ' +
+            'Every page starts with its title and canonical URL.',
+          docs: cloudDocs,
+          rendered,
+        })
+      );
+
+      // "Moved to" stubs so previously copied .md URLs survive renames.
+      // Skip any source a real page owns.
+      const stubs = [];
+      for (const pair of redirectPairs(context.siteConfig)) {
+        const from = normalizePermalink(pair.from);
+        const to = normalizePermalink(pair.to);
+        if (permalinks.has(from)) {
+          continue;
+        }
+        const stubFile = path.join(genDir, mdFilePath(from));
+        fs.mkdirSync(path.dirname(stubFile), { recursive: true });
+        fs.writeFileSync(stubFile, `Moved to ${mdUrl(to)}\n`);
+        stubs.push(from);
+      }
+
+      // Manifest for the CI verification script. Written outside genDir so
+      // the postBuild copy never publishes it.
+      fs.writeFileSync(
+        manifestPath,
+        JSON.stringify({ pages: docs.map((d) => d.descriptor.permalink).sort(), stubs: stubs.sort() }, null, 2)
+      );
+
+      const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+      console.log(
+        `[${PLUGIN_NAME}] Generated ${written} markdown pages, ` +
+          `${stubs.length} redirect stubs, and the llms files in ${seconds}s.`
+      );
+    },
+
+    configureWebpack() {
+      // Serves the generated .md files in dev. Must stay a one-element
+      // array: webpack-merge concatenates arrays but would let an object
+      // replace Docusaurus's own static-directory array.
+      return {
+        devServer: {
+          static: [
+            {
+              directory: genDir,
+              publicPath: context.baseUrl,
+            },
+          ],
+        },
+      };
+    },
+
+    async postBuild({ outDir }) {
+      // errorOnExist makes a collision with static/ assets or another
+      // plugin's output a loud failure instead of a silent overwrite.
+      fs.cpSync(genDir, outDir, {
+        recursive: true,
+        force: false,
+        errorOnExist: true,
+      });
+    },
+  };
+};
diff --git a/plugins/markdown-export/llms.js b/plugins/markdown-export/llms.js
new file mode 100644
index 00000000..9671d18b
--- /dev/null
+++ b/plugins/markdown-export/llms.js
@@ -0,0 +1,63 @@
+// Builders for the llms.txt index and the per-instance llms-full.txt files,
+// following the llmstxt.org shape: H1 title, blockquote summary, then
+// H2-delimited link-list sections, with an Optional section for the
+// full-content files.
+
+const { SITE_URL, mdUrl } = require('./urls');
+
+const SITE_SUMMARY =
+  'Serverpod is an open-source app server for the Flutter community, written in Dart. ' +
+  'Every documentation page is also available as markdown at its page URL with `.md` appended. ' +
+  'This index covers the current stable framework docs and the Serverpod Cloud docs.';
+
+function escapeTitle(title) {
+  return title.replace(/[\[\]]/g, '');
+}
+
+function linkLine(doc) {
+  const title = escapeTitle(doc.title || doc.id);
+  const description =
+    typeof doc.description === 'string' && doc.description.trim()
+      ? `: ${doc.description.trim().replace(/\s+/g, ' ')}`
+      : '';
+  return `- [${title}](${mdUrl(doc.permalink)})${description}`;
+}
+
+function buildLlmsTxt({ frameworkDocs, cloudDocs }) {
+  const lines = [
+    '# Serverpod documentation',
+    '',
+    `> ${SITE_SUMMARY}`,
+    '',
+    '## Framework documentation',
+    '',
+    ...frameworkDocs.map(linkLine),
+    '',
+    '## Serverpod Cloud documentation',
+    '',
+    ...cloudDocs.map(linkLine),
+    '',
+    '## Optional',
+    '',
+    `- [Framework documentation as a single file](${SITE_URL}/llms-full.txt)`,
+    `- [Serverpod Cloud documentation as a single file](${SITE_URL}/cloud/llms-full.txt)`,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function buildLlmsFullTxt({ title, summary, docs, rendered }) {
+  const parts = [`# ${title}\n\n> ${summary}`];
+  for (const doc of docs) {
+    const markdown = rendered.get(doc.permalink);
+    if (!markdown) {
+      // A silent skip would ship a partial single-file export that still
+      // passes every link check.
+      throw new Error(`llms-full: no rendered markdown for ${doc.permalink}`);
+    }
+    parts.push(markdown.trim());
+  }
+  return `${parts.join('\n\n---\n\n')}\n`;
+}
+
+module.exports = { buildLlmsTxt, buildLlmsFullTxt };
diff --git a/plugins/markdown-export/urls.js b/plugins/markdown-export/urls.js
new file mode 100644
index 00000000..8ba6f6df
--- /dev/null
+++ b/plugins/markdown-export/urls.js
@@ -0,0 +1,51 @@
+// Single source of truth for the site's public URL and the permalink-to-
+// markdown mapping, shared by the generator plugin, the theme components,
+// the site config, and the CI verifier. Environment-neutral on purpose: it
+// must load in Node scripts and in the browser bundle alike.
+
+const SITE_URL = 'https://docs.serverpod.dev';
+const BASE_URL = '/';
+
+// Docusaurus keeps a trailing slash on some doc permalinks (version roots,
+// directory-index pages) even with `trailingSlash: false`, while routes and
+// the sitemap serve them without it.
+function normalizePermalink(permalink) {
+  if (permalink !== '/' && permalink.endsWith('/')) {
+    return permalink.slice(0, -1);
+  }
+  return permalink;
+}
+
+// Site-relative path of a page's markdown endpoint. Permalinks already
+// include the base URL; the root doc maps to index.md.
+function mdPath(permalink) {
+  if (permalink === '/' || permalink === BASE_URL) {
+    return `${BASE_URL}index.md`;
+  }
+  return `${permalink}.md`;
+}
+
+// Absolute URL of a page's markdown endpoint.
+function mdUrl(permalink) {
+  return `${SITE_URL}${mdPath(permalink)}`;
+}
+
+// A page's canonical absolute URL.
+function pageUrl(permalink) {
+  return permalink === '/' ? SITE_URL : `${SITE_URL}${permalink}`;
+}
+
+// Output file path relative to the build root for a permalink.
+function mdFilePath(permalink) {
+  return mdPath(permalink).slice(BASE_URL.length);
+}
+
+module.exports = {
+  SITE_URL,
+  BASE_URL,
+  normalizePermalink,
+  mdPath,
+  mdUrl,
+  pageUrl,
+  mdFilePath,
+};
diff --git a/redirects.js b/redirects.js
new file mode 100644
index 00000000..68aecbb8
--- /dev/null
+++ b/redirects.js
@@ -0,0 +1,89 @@
+// Client-side redirects for pages that moved. Consumed by the
+// client-redirects plugin in docusaurus.config.js, by the markdown-export
+// plugin (which turns each source into a "moved to" .md stub), and by
+// util/verify_markdown_export.js.
+
+module.exports = [{
+    // Moved in version 1.1.1
+    from: ['/concepts/authentication'],
+    to: '/concepts/authentication/setup',
+  },
+  {
+    // Moved in version 1.1.1, 2.1.0 and 2.9.0
+    from: ['/tutorials', '/tutorials/videos', '/tutorials/first-app'],
+    to: '/tutorials/tutorials/fundamentals',
+  },
+  {
+    // Moved in version 1.2.0
+    from: ['/concepts/database-communication'],
+    to: '/concepts/database/connection',
+  },
+  {
+    // Moved in version 2.1.0
+    from: ['/insights'],
+    to: '/tools/insights',
+  },
+  {
+    // Moved in version 2.1.0
+    from: ['/roadmap'],
+    to: '/contribute',
+  },
+  {
+    // Moved in version 2.7.0
+    from: ['/get-started'],
+    to: '/get-started/creating-endpoints',
+  },
+  {
+    // Moved when scheduling was reorganized from a single page to a directory
+    from: ['/concepts/scheduling'],
+    to: '/concepts/scheduling/setup',
+  },
+  {
+    from: ['/cloud/reference/deployment/deploying-your-application'],
+    to: '/cloud/concepts/deployments',
+  },
+  {
+    from: ['/cloud/guides/logs', '/cloud/reference/logging'],
+    to: '/cloud/concepts/logs',
+  },
+  {
+    from: ['/cloud/guides/passwords'],
+    to: '/cloud/concepts/passwords-secrets-env-vars',
+  },
+  {
+    from: ['/cloud/guides/custom-domains'],
+    to: '/cloud/concepts/custom-domains',
+  },
+  {
+    from: ['/cloud/guides/database'],
+    to: '/cloud/concepts/database',
+  },
+  {
+    from: ['/cloud/reference/personal-access-tokens'],
+    to: '/cloud/concepts/personal-access-tokens',
+  },
+  {
+    from: ['/cloud/reference/deployment/assets'],
+    to: '/cloud/guides/ship-non-dart-files',
+  },
+  {
+    from: ['/cloud/reference/deployment/deployment-hooks'],
+    to: '/cloud/concepts/deployment-hooks',
+  },
+  {
+    from: ['/cloud/reference/deployment/github-automation'],
+    to: '/cloud/guides/deploy-from-ci-with-github-actions',
+  },
+  {
+    from: ['/cloud/reference/deployment/handling-private-dependencies'],
+    to: '/cloud/reference/private-dependencies',
+  },
+  {
+    from: ['/cloud/reference/deployment/dart-sdk-versions'],
+    to: '/cloud/reference/dart-sdk-versions',
+  },
+  {
+    from: ['/cloud/reference/project-id'],
+    to: '/cloud/reference/project-id-rules',
+  },
+];
diff --git a/static/robots.txt b/static/robots.txt
new file mode 100644
index 00000000..d1493c0d
--- /dev/null
+++ b/static/robots.txt
@@ -0,0 +1,11 @@
+# Keep the .md duplicates of every docs page out of search results. Scoped
+# to search engine crawlers only: AI agent fetchers must stay able to follow
+# llms.txt links to the markdown endpoints.
+User-agent: Googlebot
+Disallow: /*.md$
+
+User-agent: Bingbot
+Disallow: /*.md$
+
+User-agent: *
+Disallow:
diff --git a/util/verify_markdown_export.js b/util/verify_markdown_export.js
new file mode 100644
index 00000000..704b5020
--- /dev/null
+++ b/util/verify_markdown_export.js
@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+// Verifies the markdown export in the build output. Run after `npm run build`:
+//
+//   node util/verify_markdown_export.js
+//
+// Checks:
+//   1. Every page in the plugin's manifest has a non-empty .md, and every
+//      sitemap route is a doc page, a stub, or a known non-doc route.
+//   2. No generated .md contains import lines, JSX residue, or snipsync
+//      markers (outside code fences), and every page file starts with an H1
+//      followed by its exact canonical URL.
+//   3. Every internal .md link in every generated file resolves to an
+//      emitted file (in-page links, llms.txt, and both llms-full.txt files).
+//   4. The llms selection is current-stable-only, and the framework and
+//      Cloud sections are each non-empty.
+//   5. Every source path in redirects.js has either a real page .md or a
+//      "moved to" stub.
+//   6. Sampled pages from each instance render the button and the
+//      text/markdown alternate link tag.
+//
+// Exits non-zero with a list of failures.
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  SITE_URL,
+  mdFilePath,
+  normalizePermalink,
+} = require('../plugins/markdown-export/urls');
+const redirects = require('../redirects');
+
+const ROOT = path.join(__dirname, '..');
+const BUILD = path.join(ROOT, 'build');
+const MANIFEST = path.join(ROOT, '.docusaurus', 'markdown-export-manifest.json');
+
+// Sitemap routes that are not doc pages and have no markdown by design.
+const NON_DOC_ROUTES = new Set(['/search']);
+
+// Version-prefixed route (first path segment is `next` or a version number).
+const VERSIONED_ROUTE_RE = /^\/(next|\d+\.\d+\.\d+)([/.]|$)/;
+
+const failures = [];
+function fail(message) {
+  failures.push(message);
+}
+
+/** Does an emitted .md file exist for this site-absolute .md URL? */
+function mdUrlResolves(url) {
+  const rel = url.replace(SITE_URL, '').replace(/^\//, '');
+  return rel !== '.md' && rel !== '' && fs.existsSync(path.join(BUILD, rel));
+}
+
+function stripCode(markdown) {
+  return markdown
+    .replace(/^ {0,3}(```|~~~)[\s\S]*?^ {0,3}\1[^\n]*$/gm, '')
+    .replace(/`[^`\n]*`/g, '');
+}
+
+// 1. Every manifest page has a non-empty .md, and every sitemap route is
+// accounted for (a doc page, a stub, or a known non-doc route), so a
+// silently skipped doc tree cannot pass.
+const manifest = fs.existsSync(MANIFEST)
+  ? JSON.parse(fs.readFileSync(MANIFEST, 'utf8'))
+  : null;
+if (!manifest) {
+  fail(`missing ${MANIFEST}; run npm run build first`);
+} else {
+  for (const page of manifest.pages) {
+    const mdFile = path.join(BUILD, mdFilePath(page));
+    if (!fs.existsSync(mdFile)) {
+      fail(`missing .md for page ${page}`);
+    } else if (fs.statSync(mdFile).size === 0) {
+      fail(`empty .md for page ${page}`);
+    }
+  }
+  const covered = new Set([...manifest.pages, ...manifest.stubs]);
+  const sitemapPath = path.join(BUILD, 'sitemap.xml');
+  if (!fs.existsSync(sitemapPath)) {
+    fail('build/sitemap.xml is missing; run npm run build first');
+  } else {
+    const sitemap = fs.readFileSync(sitemapPath, 'utf8');
+    const routes = [...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)]
+      .map((m) => m[1].replace(SITE_URL, ''))
+      .map((r) => normalizePermalink(r === '' ? '/' : r) || '/');
+    for (const route of routes) {
+      if (!covered.has(route) && !NON_DOC_ROUTES.has(route)) {
+        fail(`sitemap route ${route} has no markdown export and is not a known non-doc route`);
+      }
+    }
+    console.log(`manifest pages with .md: ${manifest.pages.length}, sitemap routes covered: ${routes.length}`);
+  }
+}
+
+// 2 + 3 (in-page part). Content and link checks on every generated .md.
+function* mdFiles(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* mdFiles(full);
+    } else if (entry.name.endsWith('.md')) {
+      yield full;
+    }
+  }
+}
+
+const SITE_URL_RE = SITE_URL.replace(/[.\\/]/g, '\\$&');
+const MD_LINK_RE = new RegExp(`\\((${SITE_URL_RE}[^)#\\s]*\\.md)(?:#[^)]*)?\\)`, 'g');
+const CANONICAL_LINE_RE = new RegExp(`^${SITE_URL_RE}(\\/[\\w\\-./]*)?$`, 'gm');
+
+let checked = 0;
+let totalBytes = 0;
+let inPageLinks = 0;
+let brokenInPageLinks = 0;
+for (const file of mdFiles(BUILD)) {
+  const rel = path.relative(BUILD, file);
+  const content = fs.readFileSync(file, 'utf8');
+  totalBytes += content.length;
+  checked += 1;
+
+  if (/^Moved to https:\/\/[^\s]+\.md$/m.test(content.trim())) {
+    continue; // redirect stub; single line by design
+  }
+
+  const prose = stripCode(content);
+  if (/^import\s.+\sfrom\s/m.test(prose)) {
+    fail(`${rel}: import residue`);
+  }
+  if (/<[A-Z][A-Za-z]*[\s/>]/.test(prose)) {
+    fail(`${rel}: JSX residue`);
+  }
+  if (/SNIPSTART|SNIPEND/.test(content)) {
+    fail(`${rel}: snipsync marker residue`);
+  }
+
+  const lines = content.split('\n');
+  if (!lines[0].startsWith('# ')) {
+    fail(`${rel}: does not start with an H1`);
+  }
+  const route = `/${rel.replace(/\.md$/, '')}`;
+  const expectedCanonical = rel === 'index.md' ? SITE_URL : `${SITE_URL}${route}`;
+  if ((lines[2] || '') !== expectedCanonical) {
+    fail(`${rel}: canonical URL line is "${lines[2]}", expected "${expectedCanonical}"`);
+  }
+
+  for (const match of prose.matchAll(MD_LINK_RE)) {
+    inPageLinks += 1;
+    if (!mdUrlResolves(match[1])) {
+      brokenInPageLinks += 1;
+      if (brokenInPageLinks <= 10) {
+        fail(`${rel}: broken internal link ${match[1]}`);
+      }
+    }
+  }
+}
+if (brokenInPageLinks > 10) {
+  fail(`...and ${brokenInPageLinks - 10} more broken internal links`);
+}
+console.log(
+  `.md files checked: ${checked} (${(totalBytes / 1024 / 1024).toFixed(1)} MB), ` +
+    `internal links resolved: ${inPageLinks - brokenInPageLinks}/${inPageLinks}`
+);
+
+// 3 (llms part) + 4. llms files: links resolve, the selection is stable-only
+// (checked on llms.txt links and on llms-full canonical lines, which state
+// each embedded page's identity; embedded page BODIES may legitimately link
+// to versioned pages, e.g. from upgrade guides), and the framework and Cloud
+// selections are each non-empty.
+for (const llmsFile of ['llms.txt', 'llms-full.txt', path.join('cloud', 'llms-full.txt')]) {
+  const fullPath = path.join(BUILD, llmsFile);
+  if (!fs.existsSync(fullPath)) {
+    fail(`missing ${llmsFile}`);
+    continue;
+  }
+  const content = fs.readFileSync(fullPath, 'utf8');
+  const links = [...content.matchAll(MD_LINK_RE)].map((m) => m[1]);
+  // Only lines that are exactly a page URL count as canonical lines; prose
+  // can contain a bare URL followed by punctuation.
+  const canonicals = [...content.matchAll(CANONICAL_LINE_RE)].map((m) => m[1] || '/');
+  if (links.length + canonicals.length === 0) {
+    fail(`${llmsFile}: contains no links (empty generation would pass silently)`);
+  }
+  for (const link of links) {
+    if (!mdUrlResolves(link)) {
+      fail(`${llmsFile} links to missing file: ${link}`);
+    }
+  }
+  for (const route of canonicals) {
+    if (!fs.existsSync(path.join(BUILD, mdFilePath(route)))) {
+      fail(`${llmsFile} canonical line has no emitted file: ${route}`);
+    }
+  }
+  const identity =
+    llmsFile === 'llms.txt'
+      ? links.map((l) => l.replace(SITE_URL, '').replace(/\.md$/, ''))
+      : canonicals;
+  for (const route of identity.filter((r) => VERSIONED_ROUTE_RE.test(r)).slice(0, 5)) {
+    fail(`${llmsFile} selects a page outside current stable: ${route}`);
+  }
+  console.log(`${llmsFile}: ${links.length} links + ${canonicals.length} canonical lines resolved`);
+}
+const llmsIndexPath = path.join(BUILD, 'llms.txt');
+if (fs.existsSync(llmsIndexPath)) {
+  const llmsLinks = [...fs.readFileSync(llmsIndexPath, 'utf8').matchAll(MD_LINK_RE)].map(
+    (m) => m[1]
+  );
+  const isCloudLink = (l) =>
+    l.startsWith(`${SITE_URL}/cloud/`) || l === `${SITE_URL}/cloud.md`;
+  const cloudCount = llmsLinks.filter(isCloudLink).length;
+  const frameworkCount = llmsLinks.length - cloudCount;
+  if (frameworkCount === 0) {
+    fail('llms.txt: framework section is empty');
+  }
+  if (cloudCount === 0) {
+    fail('llms.txt: Cloud section is empty');
+  }
+  console.log(`llms.txt sections: framework ${frameworkCount}, cloud ${cloudCount}`);
+}
+
+// 5. Redirect coverage against redirects.js (the same module the site config
+// consumes), independent of the plugin's own stub generation.
+const fromPaths = redirects.flatMap((rule) =>
+  Array.isArray(rule.from) ? rule.from : [rule.from]
+);
+if (fromPaths.length === 0) {
+  fail('redirects.js contains no redirect sources');
+}
+for (const from of fromPaths) {
+  const target = path.join(BUILD, mdFilePath(from.replace(/\/$/, '') || '/'));
+  if (!fs.existsSync(target)) {
+    fail(`redirect source ${from} has neither a page .md nor a moved-to stub`);
+  }
+}
+if (manifest) {
+  for (const stub of manifest.stubs) {
+    const stubFile = path.join(BUILD, mdFilePath(stub));
+    const stubContent = fs.readFileSync(stubFile, 'utf8').trim();
+    if (!/^Moved to https:\/\/[^\s]+\.md$/.test(stubContent)) {
+      fail(`redirect stub ${stub}.md has unexpected content`);
+    } else if (!mdUrlResolves(stubContent.replace('Moved to ', ''))) {
+      fail(`redirect stub ${stub}.md points at a missing file`);
+    }
+  }
+  console.log(`redirect sources checked: ${fromPaths.length} (${manifest.stubs.length} stubs)`);
+}
+
+// 6. Sampled rendered pages (one per instance class, picked from the
+// manifest) carry the alternate link tag and the copy button.
+if (manifest) {
+  const samples = [
+    manifest.pages.find(
+      (p) => p !== '/' && !p.startsWith('/cloud') && !VERSIONED_ROUTE_RE.test(p)
+    ),
+    manifest.pages.find((p) => p.startsWith('/cloud/')),
+    manifest.pages.find((p) => VERSIONED_ROUTE_RE.test(p)),
+  ].filter(Boolean);
+  if (samples.length < 3) {
+    fail('manifest is missing pages for one of: stable, cloud, versioned');
+  }
+  for (const permalink of samples) {
+    const htmlFile = path.join(BUILD, `${permalink.replace(/^\//, '')}.html`);
+    if (!fs.existsSync(htmlFile)) {
+      fail(`sample page ${permalink} has no rendered HTML at ${htmlFile}`);
+      continue;
+    }
+    const html = fs.readFileSync(htmlFile, 'utf8');
+    if (!html.includes('rel="alternate" type="text/markdown"')) {
+      fail(`${permalink}: rendered page is missing the text/markdown alternate link tag`);
+    }
+    if (!html.includes('Copy as Markdown')) {
+      fail(`${permalink}: rendered page is missing the copy button`);
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error(`\nFAILED: ${failures.length} problem(s)`);
+  for (const failure of failures.slice(0, 50)) {
+    console.error(`  - ${failure}`);
+  }
+  if (failures.length > 50) {
+    console.error(`  ... and ${failures.length - 50} more`);
+  }
+  process.exit(1);
+}
+console.log('\nmarkdown export verification passed');

From 309efe3581bfc6d926e8491a20e69c33a5c4c522 Mon Sep 17 00:00:00 2001
From: developerjamiu <developerjamiu@gmail.com>
Date: Wed, 12 Aug 2026 16:26:19 +0100
Subject: [PATCH 2/2] feat: Add a Copy as Markdown button to every docs page

---
 src/components/CopyPageButton/index.js        | 178 ++++++++++++++++++
 .../CopyPageButton/styles.module.css          |  67 +++++++
 src/components/MarkdownDocActions/index.js    |  35 ++++
 .../MarkdownDocActions/styles.module.css      |  12 ++
 src/theme/DocVersionBadge/index.js            |  12 ++
 5 files changed, 304 insertions(+)
 create mode 100644 src/components/CopyPageButton/index.js
 create mode 100644 src/components/CopyPageButton/styles.module.css
 create mode 100644 src/components/MarkdownDocActions/index.js
 create mode 100644 src/components/MarkdownDocActions/styles.module.css
 create mode 100644 src/theme/DocVersionBadge/index.js

diff --git a/src/components/CopyPageButton/index.js b/src/components/CopyPageButton/index.js
new file mode 100644
index 00000000..82862068
--- /dev/null
+++ b/src/components/CopyPageButton/index.js
@@ -0,0 +1,178 @@
+/**
+ * "Copy page as Markdown" button: fetches the page's generated .md endpoint
+ * and writes it to the clipboard. The ClipboardItem is constructed
+ * synchronously in the click handler with a promise for the text; Safari
+ * invalidates the clipboard permission across an awaited fetch, so a
+ * fetch-then-writeText order fails there. Fallbacks are capability-based.
+ */
+import React, {useCallback, useEffect, useRef, useState} from 'react';
+import clsx from 'clsx';
+import {translate} from '@docusaurus/Translate';
+import IconCopy from '@theme/Icon/Copy';
+import IconSuccess from '@theme/Icon/Success';
+import {mdPath} from '@site/plugins/markdown-export/urls';
+import styles from './styles.module.css';
+
+const RESET_DELAY_MS = 2500;
+
+function label(state) {
+  switch (state) {
+    case 'loading':
+      return translate({
+        id: 'serverpod.copyPageButton.copying',
+        message: 'Copying…',
+        description: 'Copy page button label while the markdown is fetched',
+      });
+    case 'copied':
+      return translate({
+        id: 'serverpod.copyPageButton.copied',
+        message: 'Copied',
+        description: 'Copy page button label after a successful copy',
+      });
+    case 'error':
+      return translate({
+        id: 'serverpod.copyPageButton.failed',
+        message: 'Copy failed',
+        description: 'Copy page button label after a failed copy',
+      });
+    default:
+      return translate({
+        id: 'serverpod.copyPageButton.label',
+        message: 'Copy as Markdown',
+        description: 'Copy page button label',
+      });
+  }
+}
+
+function title() {
+  return translate({
+    id: 'serverpod.copyPageButton.title',
+    message:
+      'Copy the markdown version of this page, ready to paste into an AI assistant',
+    description: 'Tooltip for the copy page button',
+  });
+}
+
+async function fetchMarkdown(markdownPath) {
+  const response = await fetch(markdownPath);
+  const contentType = response.headers.get('content-type') || '';
+  // The dev server's SPA fallback answers unknown paths with 200 + HTML.
+  if (!response.ok || contentType.includes('text/html')) {
+    throw new Error(`Markdown not available at ${markdownPath} (HTTP ${response.status})`);
+  }
+  return response.text();
+}
+
+function writeToClipboard(textPromise) {
+  const writeText = () =>
+    textPromise.then((text) => navigator.clipboard.writeText(text));
+  if (typeof ClipboardItem !== 'undefined' && navigator.clipboard?.write) {
+    const item = new ClipboardItem({
+      'text/plain': textPromise.then(
+        (text) => new Blob([text], {type: 'text/plain'}),
+      ),
+    });
+    // A clipboard-side rejection (permission, unsupported promise values)
+    // retries the simpler API; a fetch failure re-rejects inside writeText.
+    return navigator.clipboard.write([item]).catch(writeText);
+  }
+  if (navigator.clipboard?.writeText) {
+    return writeText();
+  }
+  return Promise.reject(new Error('Clipboard API unavailable'));
+}
+
+function reportCopyEvent(params) {
+  // gtag is absent on the dev server and behind ad blockers.
+  if (typeof window === 'undefined' || typeof window.gtag !== 'function') {
+    return;
+  }
+  try {
+    window.gtag('event', 'copy_page_markdown', params);
+  } catch {}
+}
+
+export default function CopyPageButton({permalink, docsVersion}) {
+  const [state, setState] = useState('idle');
+  const resetTimer = useRef(undefined);
+  const mounted = useRef(true);
+  useEffect(
+    () => () => {
+      mounted.current = false;
+      window.clearTimeout(resetTimer.current);
+    },
+    [],
+  );
+
+  const handleClick = useCallback(() => {
+    if (state === 'loading') {
+      return;
+    }
+    window.clearTimeout(resetTimer.current);
+    setState('loading');
+    const markdownPath = mdPath(permalink);
+    const isCloud = permalink === '/cloud' || permalink.startsWith('/cloud/');
+    const finish = (ok, error) => {
+      if (error) {
+        // Surface the cause (missing .md, clipboard denial) so a "Copy
+        // failed" report is diagnosable from the console.
+        console.error('[copy-page-markdown]', error);
+      }
+      reportCopyEvent({
+        page_path: permalink,
+        docs_instance: isCloud ? 'cloud' : 'framework',
+        docs_version: docsVersion,
+        status: ok ? 'success' : 'error',
+      });
+      if (!mounted.current) {
+        return;
+      }
+      setState(ok ? 'copied' : 'error');
+      resetTimer.current = window.setTimeout(() => setState('idle'), RESET_DELAY_MS);
+    };
+    writeToClipboard(fetchMarkdown(markdownPath)).then(
+      () => finish(true),
+      (error) => finish(false, error),
+    );
+  }, [state, permalink, docsVersion]);
+
+  // aria-busy + click guard instead of `disabled`, which would drop keyboard
+  // focus; the live region sits outside the button so screen readers still
+  // announce it while the button's own subtree changes.
+  return (
+    <>
+      <button
+        type="button"
+        className={clsx(
+          'badge',
+          'badge--secondary',
+          styles.copyPageButton,
+          {[styles.copyPageButtonError]: state === 'error'},
+        )}
+        onClick={handleClick}
+        aria-busy={state === 'loading'}
+        title={title()}>
+        <span className={styles.copyPageButtonIcon} aria-hidden="true">
+          {state === 'copied' ? <IconSuccess /> : <IconCopy />}
+        </span>
+        {label(state)}
+      </button>
+      <span role="status" aria-live="polite" className={styles.visuallyHidden}>
+        {state === 'copied'
+          ? translate({
+              id: 'serverpod.copyPageButton.announceCopied',
+              message: 'Page copied as Markdown',
+              description: 'Screen reader announcement after a successful copy',
+            })
+          : ''}
+        {state === 'error'
+          ? translate({
+              id: 'serverpod.copyPageButton.announceFailed',
+              message: 'Copying the page failed',
+              description: 'Screen reader announcement after a failed copy',
+            })
+          : ''}
+      </span>
+    </>
+  );
+}
diff --git a/src/components/CopyPageButton/styles.module.css b/src/components/CopyPageButton/styles.module.css
new file mode 100644
index 00000000..7baac4e1
--- /dev/null
+++ b/src/components/CopyPageButton/styles.module.css
@@ -0,0 +1,67 @@
+/* The pill look comes from the infima badge classes the button shares with
+   the version badge; this module only resets button chrome. */
+
+.copyPageButton {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  border: 0;
+  cursor: pointer;
+  font-family: var(--ifm-font-family-base);
+}
+
+.copyPageButton:hover {
+  filter: brightness(0.96);
+}
+
+[data-theme='dark'] .copyPageButton:hover {
+  filter: brightness(1.15);
+}
+
+.copyPageButton:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 2px;
+}
+
+.copyPageButton[aria-busy='true'] {
+  cursor: default;
+  opacity: 0.7;
+}
+
+.copyPageButtonError {
+  color: var(--ifm-color-danger-dark);
+}
+
+[data-theme='dark'] .copyPageButtonError {
+  color: var(--ifm-color-danger-light);
+}
+
+.copyPageButtonIcon {
+  display: inline-flex;
+  width: 0.9rem;
+  height: 0.9rem;
+}
+
+.copyPageButtonIcon svg {
+  width: 100%;
+  height: 100%;
+  fill: currentColor;
+}
+
+@media (pointer: coarse) {
+  .copyPageButton {
+    min-height: 2.75rem;
+  }
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}
diff --git a/src/components/MarkdownDocActions/index.js b/src/components/MarkdownDocActions/index.js
new file mode 100644
index 00000000..53f89452
--- /dev/null
+++ b/src/components/MarkdownDocActions/index.js
@@ -0,0 +1,35 @@
+/**
+ * Page-level markdown actions for a doc page: the row above the title
+ * holding the version badge (when the page has one) and the "Copy as
+ * Markdown" button, plus the page's text/markdown alternate link tag.
+ */
+import React from 'react';
+import Head from '@docusaurus/Head';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import CopyPageButton from '@site/src/components/CopyPageButton';
+import {normalizePermalink, mdUrl} from '@site/plugins/markdown-export/urls';
+import styles from './styles.module.css';
+
+export default function MarkdownDocActions({badge}) {
+  // DocVersionBadge has a second theme render site (generated-index category
+  // pages) that sits outside DocProvider, where useDoc throws. Those pages
+  // have no markdown export, so render the badge slot unchanged there.
+  let metadata;
+  try {
+    metadata = useDoc().metadata;
+  } catch {
+    return badge;
+  }
+  const permalink = normalizePermalink(metadata.permalink);
+  return (
+    <>
+      <Head>
+        <link rel="alternate" type="text/markdown" href={mdUrl(permalink)} />
+      </Head>
+      <div className={styles.actionsRow}>
+        {badge}
+        <CopyPageButton permalink={permalink} docsVersion={metadata.version} />
+      </div>
+    </>
+  );
+}
diff --git a/src/components/MarkdownDocActions/styles.module.css b/src/components/MarkdownDocActions/styles.module.css
new file mode 100644
index 00000000..98c6cc05
--- /dev/null
+++ b/src/components/MarkdownDocActions/styles.module.css
@@ -0,0 +1,12 @@
+.actionsRow {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin-bottom: 1rem;
+}
+
+/* The original badge carries its own bottom margin; the row owns it now. */
+.actionsRow > :global(.badge) {
+  margin-bottom: 0;
+}
diff --git a/src/theme/DocVersionBadge/index.js b/src/theme/DocVersionBadge/index.js
new file mode 100644
index 00000000..14a2441c
--- /dev/null
+++ b/src/theme/DocVersionBadge/index.js
@@ -0,0 +1,12 @@
+/**
+ * Docusaurus wrappers must live at the wrapped component's theme path, and
+ * DocVersionBadge is the slot every doc page renders above its title. The
+ * feature itself lives in MarkdownDocActions.
+ */
+import React from 'react';
+import DocVersionBadge from '@theme-original/DocVersionBadge';
+import MarkdownDocActions from '@site/src/components/MarkdownDocActions';
+
+export default function DocVersionBadgeWrapper(props) {
+  return <MarkdownDocActions badge={<DocVersionBadge {...props} />} />;
+}