feat: agent-friendly docs (llms.txt + markdown endpoints)

.github/workflows/docs.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
           cache-dependency-path: docs-site/package-lock.json
 
@@ -69,7 +69,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Prepare root files
         run: |
@@ -109,6 +109,41 @@ jobs:
           </html>
           EOF
 
+          echo "LATEST_VERSION=${LATEST_VERSION}" >> $GITHUB_ENV
+
+      - name: Copy llms.txt from latest version on docs-deployment branch
+        run: |
+          # Fetch the llms.txt from the latest version's folder on docs-deployment.
+          # This file was deployed by publish-versioned-docs and is always in sync
+          # with the versioned .md endpoints it links to.
+          git fetch origin docs-deployment --depth=1
+          if git show "origin/docs-deployment:${LATEST_VERSION}/llms.txt" > root/llms.txt 2>/dev/null; then
+            echo "✅ Copied llms.txt from /${LATEST_VERSION}/llms.txt to root"
+          else
+            echo "⚠️  No llms.txt found at /${LATEST_VERSION}/llms.txt on docs-deployment — skipping"
+            rm -f root/llms.txt
+          fi
+
+      - name: Prepend version navigation to root llms.txt
+        if: hashFiles('root/llms.txt') != ''
+        run: |
+          # Build a version navigation header from versions.json.
+          # Only the root llms.txt gets this — versioned copies stay static.
+          SITE="${PUBLIC_SITE}"
+          HEADER="This documentation is for v${LATEST_VERSION}. Other versions are available:"
+
+          VERSION_LINES=""
+          for version in $(jq -r '.versions[].version' docs-site/versions.json); do
+            if [[ "$version" != "$LATEST_VERSION" ]]; then
+              VERSION_LINES="${VERSION_LINES}\n- [v${version}](${SITE}/${version}/llms.txt)"
+            fi
+          done
+          VERSION_LINES="${VERSION_LINES}\n- [Development (main)](${SITE}/main/llms.txt)"
+
+          # Insert after the description blockquote (line starting with ">")
+          sed -i "s|^> .*|&\n\n${HEADER}${VERSION_LINES}|" root/llms.txt
+          echo "✅ Added version navigation to root llms.txt"
+
       - name: Deploy root files to docs-deployment branch
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
@@ -129,7 +164,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
           cache-dependency-path: docs-site/package-lock.json
 
@@ -168,7 +203,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
           cache-dependency-path: docs-site/package-lock.json
 

docs-site/astro.config.mjs

@@ -2,6 +2,8 @@ import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import rehypeExternalLinks from 'rehype-external-links';
 import rehypeRewriteLinks from './plugins/rehype-rewrite-links.mjs';
+import rehypeAgentSignaling from './plugins/rehype-agent-signaling.mjs';
+import agentDocs from './plugins/astro-agent-docs.mjs';
 
 // https://astro.build/config
 export default defineConfig({
@@ -15,9 +17,13 @@ export default defineConfig({
       rehypeRewriteLinks,
       // Open external links in new tab
       [rehypeExternalLinks, { target: '_blank', rel: ['noopener', 'noreferrer'] }],
+      // Inject hidden llms.txt directive for agent discovery
+      rehypeAgentSignaling,
     ],
   },
   integrations: [
+    // Generate .md endpoints and llms.txt for agent-friendly docs
+    agentDocs(),
     starlight({
       title: 'ICP CLI',
       description: 'Command-line tool for developing and deploying applications on the Internet Computer Protocol (ICP)',

docs-site/package.json

@@ -13,6 +13,7 @@
     "@astrojs/check": "^0.9.4",
     "@astrojs/starlight": "^0.37.3",
     "astro": "^5.6.1",
+    "gray-matter": "^4.0.3",
     "sharp": "^0.33.5"
   },
   "devDependencies": {