fix(docs): resolve remaining htmltest validation issues

Author: alexeyv

docs/explanation/bmm/index.md

@@ -29,7 +29,7 @@ The BMad Method is meant to be adapted and customized to your specific needs. In
 
 First know there is the full BMad Method Process and then there is a Quick Flow for those quicker smaller efforts.
 
-- **[Full Adaptive BMad Method](#workflow-guides)** - Full planning and scope support through extensive development and testing.
+- **[Full Adaptive BMad Method](#-workflow-guides)** - Full planning and scope support through extensive development and testing.
   - Broken down into 4 phases, all of which are comprised of both required and optional phases
     - Phases 1-3 are all about progressive idea development through planning and preparations to build your project.
     - Phase 4 is the implementation cycle where you will Just In Time (JIT) produce the contextual stories needed for the dev agent based on the extensive planning completed

docs/how-to/get-answers-about-bmad.md

@@ -45,7 +45,7 @@ Fetch `llms-full.txt` into your session:
 https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
 ```
 
-You can also find this and other downloadable resources on the [Downloads page](/downloads).
+You can also find this and other downloadable resources on the [Downloads page](/downloads/).
 
 :::tip[Verify Surprising Answers]
 LLMs occasionally get things wrong. If an answer seems off, check the source file it referenced or ask on Discord.

docs/tutorials/advanced/create-custom-agent.md

@@ -148,9 +148,9 @@ Edit the agent YAML directly or use the customization file in `_bmad/_config/age
 Yes. Package your agent as a standalone module and share it with your team or the community.
 
 **Where can I see example agents?**
-Study the reference agents in `src/modules/bmb/reference/agents/`:
-- [commit-poet](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) (Simple)
-- [journal-keeper](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) (Expert)
+Study the reference agents in `src/modules/bmb/workflows/agent/data/reference/`:
+- [commit-poet](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/workflows/agent/data/reference/simple-examples/commit-poet.agent.yaml) (Simple)
+- [journal-keeper](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper) (Expert)
 
 ## Getting Help
 

tools/build-docs.js

@@ -335,6 +335,7 @@ function runAstroBuild() {
     stdio: 'inherit',
     env: {
       ...process.env,
+      SITE_URL,
       NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --disable-warning=MODULE_TYPELESS_PACKAGE_JSON`.trim(),
     },
   });
@@ -359,6 +360,18 @@ function copyArtifactsToSite(artifactsDir, siteDir) {
   if (fs.existsSync(downloadsDir)) {
     copyDirectory(downloadsDir, path.join(siteDir, 'downloads'));
   }
+
+  // Create base path symlink for local testing with htmltest
+  // This allows htmltest to resolve absolute paths like /BMAD-METHOD/...
+  const url = new URL(SITE_URL);
+  const basePath = url.pathname.replaceAll(/^\/|\/$/g, ''); // Strip leading/trailing slashes
+  if (basePath) {
+    const symlinkPath = path.join(siteDir, basePath);
+    if (!fs.existsSync(symlinkPath)) {
+      fs.symlinkSync(siteDir, symlinkPath);
+      console.log(`  → Created base path symlink: ${basePath}/`);
+    }
+  }
 }
 
 // =============================================================================

tools/check-doc-links.js

@@ -53,7 +53,7 @@ function headingToAnchor(heading) {
     .replaceAll(/[^\w\s-]/g, '') // Remove special chars except hyphens
     .replaceAll(/\s+/g, '-') // Spaces to hyphens
     .replaceAll(/-+/g, '-') // Collapse multiple hyphens
-    .replaceAll(/^-+|-+$/g, ''); // Trim leading/trailing hyphens
+    .replaceAll(/-+$/g, ''); // Trim trailing hyphens only (Starlight keeps leading hyphens from emoji removal)
 }
 
 /**

tools/verify-build-links.js

@@ -24,12 +24,15 @@
  *   1 - Broken links found or build directory missing
  */
 
-const { readFileSync, existsSync, statSync, readdirSync } = require('node:fs');
+const { readFileSync, existsSync, statSync, lstatSync, readdirSync } = require('node:fs');
 const { resolve, join, dirname, relative, normalize } = require('node:path');
 
 const BUILD_DIR = resolve(process.cwd(), 'build/site');
 const DOCS_DIR = resolve(process.cwd(), 'docs');
 
+// Base path to strip from absolute links (auto-detected from HTML)
+let BASE_PATH = '';
+
 // ANSI color codes
 const colors = {
   reset: '\u001B[0m',
@@ -51,9 +54,14 @@ function findHtmlFiles(dir, fileList = []) {
 
   for (const file of files) {
     const filePath = join(dir, file);
-    const stat = statSync(filePath);
+    const lstat = lstatSync(filePath);
+
+    // Skip symlinks to avoid infinite loops
+    if (lstat.isSymbolicLink()) {
+      continue;
+    }
 
-    if (stat.isDirectory()) {
+    if (lstat.isDirectory()) {
       findHtmlFiles(filePath, fileList);
     } else if (file.endsWith('.html')) {
       fileList.push(filePath);
@@ -112,6 +120,26 @@ function isInternalLink(link) {
   return true;
 }
 
+/**
+ * Detect base path from the first HTML file's canonical or sitemap link
+ */
+function detectBasePath(htmlFiles) {
+  for (const htmlFile of htmlFiles) {
+    const content = readFileSync(htmlFile, 'utf-8');
+    // Look for sitemap link which shows the base path
+    const sitemapMatch = content.match(/href="(\/[^"]*?)sitemap-index\.xml"/);
+    if (sitemapMatch) {
+      return sitemapMatch[1].slice(0, -1); // Remove trailing /
+    }
+    // Fallback: look for favicon link
+    const faviconMatch = content.match(/href="(\/[^"]*?)favicon\.ico"/);
+    if (faviconMatch) {
+      return faviconMatch[1].slice(0, -1);
+    }
+  }
+  return '';
+}
+
 /**
  * Resolve a link to an absolute file path in the build directory
  */
@@ -126,7 +154,14 @@ function resolveLinkToPath(fromHtmlPath, link) {
 
   // Handle absolute paths (starting with /)
   if (linkWithoutHash.startsWith('/')) {
-    const cleanPath = linkWithoutHash.slice(1); // Remove leading /
+    let cleanPath = linkWithoutHash;
+    // Strip base path if present
+    if (BASE_PATH && cleanPath.startsWith(BASE_PATH + '/')) {
+      cleanPath = cleanPath.slice(BASE_PATH.length);
+    } else if (BASE_PATH && cleanPath === BASE_PATH) {
+      cleanPath = '/';
+    }
+    cleanPath = cleanPath.slice(1); // Remove leading /
     return join(BUILD_DIR, cleanPath);
   }
 
@@ -221,7 +256,14 @@ async function verifyBuildLinks() {
 
   // Find all HTML files
   const htmlFiles = findHtmlFiles(BUILD_DIR);
-  console.log(`Found ${htmlFiles.length} HTML files\n`);
+  console.log(`Found ${htmlFiles.length} HTML files`);
+
+  // Detect base path from HTML
+  BASE_PATH = detectBasePath(htmlFiles);
+  if (BASE_PATH) {
+    console.log(`Detected base path: ${BASE_PATH}`);
+  }
+  console.log();
 
   // Category tracking
   const categories = {