feat: Add markdown exports and a Copy as Markdown button

.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

.github/workflows/test-build.yml

@@ -32,4 +32,6 @@ jobs:
             - name: Install dependencies
               run: npm ci 
             - name: Build
-              run: npm run build
+              run: npm run build
+            - name: Verify markdown export
+              run: node util/verify_markdown_export.js

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)

docusaurus.config.js

@@ -4,15 +4,16 @@
 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;
 
 /** @type {import('@docusaurus/types').Config} */
 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'),
       },
     ],
   ],

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"