fix(docs): add lychee link verification to build pipeline

- Default SITE_URL to localhost:4321 for local builds
- Add verifyBuiltLinks() that starts local server and runs lychee
- Pass BASE_PATH to remark plugin for proper link transformation
- Production builds set SITE_URL via env var in CI

Author: alexeyv

tools/build-docs.js

@@ -21,7 +21,8 @@ const archiver = require('archiver');
 const PROJECT_ROOT = path.dirname(__dirname);
 const BUILD_DIR = path.join(PROJECT_ROOT, 'build');
 
-const SITE_URL = process.env.SITE_URL || 'https://bmad-code-org.github.io/BMAD-METHOD';
+// For local builds, use localhost. Production URL set via SITE_URL env var in CI.
+const SITE_URL = process.env.SITE_URL || 'http://localhost:4321';
 const REPO_URL = 'https://github.com/bmad-code-org/BMAD-METHOD';
 
 const LLM_MAX_CHARS = 600_000;
@@ -108,15 +109,55 @@ function buildAstroSite() {
   runAstroBuild();
   copyArtifactsToSite(artifactsDir, siteDir);
 
-  // No longer needed: Inject AI agents banner into every HTML page
-  // injectAgentBanner(siteDir);
+  // Verify all links in built site
+  verifyBuiltLinks(siteDir);
 
   console.log();
   console.log(`  \u001B[32m✓\u001B[0m Astro build complete`);
 
   return siteDir;
 }
 
+/**
+ * Verify all internal links in the built site using lychee.
+ * Starts a local server and crawls the site.
+ */
+function verifyBuiltLinks(siteDir) {
+  console.log('  → Verifying links in built site...');
+
+  const { spawn } = require('node:child_process');
+  const url = new URL(SITE_URL);
+  const port = url.port || '4321';
+
+  // Start local server
+  const serverProcess = spawn('npx', ['serve', siteDir, '-l', port, '--single'], {
+    cwd: PROJECT_ROOT,
+    stdio: 'pipe',
+    detached: true,
+  });
+
+  // Wait for server to start
+  execSync('sleep 2');
+
+  try {
+    execSync(`lychee 'http://localhost:${port}/' --no-progress`, {
+      cwd: PROJECT_ROOT,
+      stdio: 'inherit',
+    });
+    console.log(`  \u001B[32m✓\u001B[0m Link verification passed`);
+  } catch {
+    console.error(`\n  \u001B[31m✗\u001B[0m Link verification failed - fix broken links before deploying\n`);
+    process.kill(-serverProcess.pid);
+    process.exit(1);
+  } finally {
+    try {
+      process.kill(-serverProcess.pid);
+    } catch {
+      // Server already stopped
+    }
+  }
+}
+
 // =============================================================================
 // LLM File Generation
 /**
@@ -330,12 +371,17 @@ async function generatePromptsBundle(downloadsDir) {
  */
 function runAstroBuild() {
   console.log('  → Running astro build...');
+  // Extract base path from SITE_URL for remark plugin
+  const url = new URL(SITE_URL);
+  const basePath = url.pathname.replace(/\/$/, ''); // Strip trailing slash
+
   execSync('npx astro build --root website', {
     cwd: PROJECT_ROOT,
     stdio: 'inherit',
     env: {
       ...process.env,
       SITE_URL,
+      BASE_PATH: basePath,
       NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --disable-warning=MODULE_TYPELESS_PACKAGE_JSON`.trim(),
     },
   });

website/src/remark-markdown-links.js

@@ -2,19 +2,23 @@
  * Remark plugin to transform relative markdown links to absolute paths
  *
  * Uses the source file's path to resolve relative links correctly.
+ * Prepends base path from import.meta.env.BASE_URL for proper deployment.
  * Works with Astro's build.format: 'directory' setting.
  */
 
 import { visit } from 'unist-util-visit';
 import path from 'path';
 
+// Get base path from environment, strip trailing slash for concatenation
+const basePath = (process.env.BASE_PATH || '').replace(/\/$/, '');
+
 export default function remarkMarkdownLinks() {
   return (tree, file) => {
     const filePath = file.history?.[0] || file.path;
 
     // Debug log
     if (!remarkMarkdownLinks._logged) {
-      console.log('[remark-markdown-links] Plugin running, file:', filePath || 'NO PATH');
+      console.log('[remark-markdown-links] Plugin running, basePath:', basePath || '(none)');
       remarkMarkdownLinks._logged = true;
     }
 
@@ -55,7 +59,8 @@ export default function remarkMarkdownLinks() {
         resolved = '/' + resolved;
       }
 
-      node.url = resolved + suffix;
+      // Prepend base path for deployment
+      node.url = basePath + resolved + suffix;
     });
   };
 }