bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/website/README.md

@@ -0,0 +1,76 @@
+# BMAD Method Documentation Site
+
+This directory contains the Astro + Starlight configuration for the BMAD Method documentation site.
+
+## Architecture
+
+The documentation uses a symlink architecture to keep content in `docs/` at the repo root while serving it through Astro:
+
+```
+bmad2/
+├── docs/                          # Content lives here (repo root)
+│   ├── index.md
+│   ├── tutorials/
+│   ├── how-to/
+│   ├── explanation/
+│   └── reference/
+└── website/
+    ├── astro.config.mjs           # Astro + Starlight config
+    ├── src/
+    │   ├── content/
+    │   │   └── docs -> ../../docs # Symlink to content
+    │   └── styles/
+    │       └── custom.css         # Custom styling
+    └── public/                    # Static assets
+```
+
+## Development
+
+```bash
+# From repo root
+npm run docs:dev      # Start dev server
+npm run docs:build    # Build for production
+npm run docs:preview  # Preview production build
+```
+
+## Platform Notes
+
+### Windows Symlink Support
+
+The `website/src/content/docs` symlink may not work correctly on Windows without Developer Mode enabled or administrator privileges.
+
+**To enable symlinks on Windows:**
+
+1. **Enable Developer Mode** (recommended):
+   - Settings → Update & Security → For developers → Developer Mode: On
+   - This allows creating symlinks without admin rights
+
+2. **Or use Git's symlink support**:
+   ```bash
+   git config core.symlinks true
+   ```
+   Then re-clone the repository.
+
+3. **Or create a junction** (alternative):
+   ```cmd
+   # Run as Administrator
+   mklink /J website\src\content\docs ..\..\docs
+   ```
+
+**If symlinks don't work**, you can copy the docs folder instead:
+```bash
+# Remove the symlink
+rm website/src/content/docs
+
+# Copy the docs folder
+cp -r docs website/src/content/docs
+```
+
+Note: If copying, remember to keep the copy in sync with changes to `docs/`.
+
+## Build Output
+
+The build pipeline (`npm run docs:build`) produces:
+- Static HTML site in `build/site/`
+- LLM-friendly files: `llms.txt`, `llms-full.txt`
+- Downloadable ZIP bundles in `downloads/`

package/website/astro.config.mjs

@@ -0,0 +1,218 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import sitemap from '@astrojs/sitemap';
+import rehypeMarkdownLinks from './src/rehype-markdown-links.js';
+import { getSiteUrl } from './src/lib/site-url.js';
+
+const siteUrl = getSiteUrl();
+const urlParts = new URL(siteUrl);
+// Normalize basePath: ensure trailing slash so links can use `${BASE_URL}path`
+const basePath = urlParts.pathname === '/' ? '/' : urlParts.pathname.endsWith('/') ? urlParts.pathname : urlParts.pathname + '/';
+
+export default defineConfig({
+  site: `${urlParts.origin}${basePath}`,
+  base: basePath,
+  outDir: '../build/site',
+
+  // Disable aggressive caching in dev mode
+  vite: {
+    optimizeDeps: {
+      force: true, // Always re-bundle dependencies
+    },
+    server: {
+      watch: {
+        usePolling: false, // Set to true if file changes aren't detected
+      },
+    },
+  },
+
+  markdown: {
+    rehypePlugins: [rehypeMarkdownLinks],
+  },
+
+  integrations: [
+    sitemap(),
+    starlight({
+      title: 'BMAD Method',
+      tagline: 'AI-driven agile development with specialized agents and workflows that scale from bug fixes to enterprise platforms.',
+
+      logo: {
+        src: './public/img/logo.svg',
+        alt: 'BMAD Logo',
+      },
+      favicon: '/favicon.ico',
+
+      // Social links
+      social: [
+        { icon: 'discord', label: 'Discord', href: 'https://discord.gg/gk8jAdXWmj' },
+        { icon: 'github', label: 'GitHub', href: 'https://github.com/bmad-code-org/BMAD-METHOD' },
+        { icon: 'youtube', label: 'YouTube', href: 'https://www.youtube.com/@BMadCode' },
+      ],
+
+      // Show last updated timestamps
+      lastUpdated: true,
+
+      // Custom head tags for LLM discovery
+      head: [
+        {
+          tag: 'meta',
+          attrs: {
+            name: 'ai-terms',
+            content: `AI-optimized documentation: ${siteUrl}/llms-full.txt (plain text, ~100k tokens, complete BMAD reference). Index: ${siteUrl}/llms.txt`,
+          },
+        },
+        {
+          tag: 'meta',
+          attrs: {
+            name: 'llms-full',
+            content: `${siteUrl}/llms-full.txt`,
+          },
+        },
+        {
+          tag: 'meta',
+          attrs: {
+            name: 'llms',
+            content: `${siteUrl}/llms.txt`,
+          },
+        },
+      ],
+
+      // Custom CSS
+      customCss: ['./src/styles/custom.css'],
+
+      // Sidebar configuration (Diataxis structure)
+      sidebar: [
+        { label: 'Welcome', slug: 'index' },
+        {
+          label: 'Tutorials',
+          collapsed: false,
+          items: [
+            {
+              label: 'Getting Started',
+              autogenerate: { directory: 'tutorials/getting-started' },
+            },
+            {
+              label: 'Advanced',
+              autogenerate: { directory: 'tutorials/advanced' },
+            },
+          ],
+        },
+        {
+          label: 'How-To Guides',
+          collapsed: true,
+          items: [
+            { slug: 'how-to/get-answers-about-bmad' },
+            {
+              label: 'Installation',
+              autogenerate: { directory: 'how-to/installation' },
+            },
+            {
+              label: 'Workflows',
+              autogenerate: { directory: 'how-to/workflows' },
+            },
+            {
+              label: 'Customization',
+              autogenerate: { directory: 'how-to/customization' },
+            },
+            {
+              label: 'Brownfield Development',
+              autogenerate: { directory: 'how-to/brownfield' },
+            },
+            {
+              label: 'Troubleshooting',
+              autogenerate: { directory: 'how-to/troubleshooting' },
+            },
+          ],
+        },
+        {
+          label: 'Explanation',
+          collapsed: true,
+          items: [
+            {
+              label: 'Core Concepts',
+              autogenerate: { directory: 'explanation/core-concepts' },
+            },
+            {
+              label: 'Architecture',
+              autogenerate: { directory: 'explanation/architecture' },
+            },
+            {
+              label: 'Philosophy',
+              autogenerate: { directory: 'explanation/philosophy' },
+            },
+            {
+              label: 'Features',
+              autogenerate: { directory: 'explanation/features' },
+            },
+            {
+              label: 'Agents',
+              autogenerate: { directory: 'explanation/agents' },
+            },
+            {
+              label: 'BMM',
+              autogenerate: { directory: 'explanation/bmm' },
+            },
+            {
+              label: 'BMad Builder',
+              autogenerate: { directory: 'explanation/bmad-builder' },
+            },
+            {
+              label: 'Game Development',
+              autogenerate: { directory: 'explanation/game-dev' },
+            },
+            {
+              label: 'Creative Intelligence',
+              autogenerate: { directory: 'explanation/creative-intelligence' },
+            },
+            {
+              label: 'Core Module',
+              autogenerate: { directory: 'explanation/core' },
+            },
+            {
+              label: 'FAQ',
+              autogenerate: { directory: 'explanation/faq' },
+            },
+          ],
+        },
+        {
+          label: 'Reference',
+          collapsed: true,
+          items: [
+            {
+              label: 'Agents',
+              autogenerate: { directory: 'reference/agents' },
+            },
+            {
+              label: 'Workflows',
+              autogenerate: { directory: 'reference/workflows' },
+            },
+            {
+              label: 'Configuration',
+              autogenerate: { directory: 'reference/configuration' },
+            },
+            {
+              label: 'Glossary',
+              autogenerate: { directory: 'reference/glossary' },
+            },
+          ],
+        },
+      ],
+
+      // Credits in footer
+      credits: false,
+
+      // Pagination
+      pagination: true,
+
+      // Custom components
+      components: {
+        Header: './src/components/Header.astro',
+        MobileMenuFooter: './src/components/MobileMenuFooter.astro',
+      },
+
+      // Table of contents
+      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },
+    }),
+  ],
+});

package/website/src/components/Banner.astro

@@ -0,0 +1,59 @@
+---
+import { getSiteUrl } from '../lib/site-url.js';
+
+const SITE_URL = getSiteUrl();
+const fullDocsUrl = `${SITE_URL}/llms-full.txt`;
+---
+
+<div class="ai-banner">
+  <span>🤖 Consolidated, AI-optimized BMAD docs: <a href={fullDocsUrl}>llms-full.txt</a>. Fetch this plain text file for complete context.</span>
+</div>
+
+<style>
+  .ai-banner {
+    width: 100vw; /* Full viewport width */
+    margin-left: calc(-50vw + 50%); /* Center and break out of container */
+    height: var(--ai-banner-height, 2.75rem);
+    background: #334155;
+    color: rgb(148, 163, 184);
+    padding: 0.5rem 1rem;
+    font-size: 0.875rem;
+    border-bottom: 1px solid rgba(140, 140, 255, 0.15);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    font-family: system-ui, sans-serif;
+  }
+
+  /* Truncate text on narrow screens */
+  .ai-banner span {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 100%;
+  }
+  .ai-banner a {
+    color: #8C8CFF;
+    text-decoration: none;
+    font-weight: 600;
+  }
+  .ai-banner a:hover {
+    text-decoration: underline;
+  }
+
+  /* Match navbar padding at breakpoints */
+  @media (min-width: 50rem) {
+    .ai-banner {
+      padding-left: 2.5rem;
+      padding-right: 2.5rem;
+    }
+  }
+
+  @media (min-width: 72rem) {
+    .ai-banner {
+      padding-left: 3rem;
+      padding-right: 3rem;
+    }
+  }
+</style>

package/website/src/components/Header.astro

@@ -0,0 +1,121 @@
+---
+import config from 'virtual:starlight/user-config';
+import type { Props } from '@astrojs/starlight/props';
+
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import Search from 'virtual:starlight/components/Search';
+import SiteTitle from 'virtual:starlight/components/SiteTitle';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
+
+import Banner from './Banner.astro';
+
+/**
+ * Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
+ */
+const shouldRenderSearch =
+	config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
+---
+
+<Banner />
+<div class="header sl-flex">
+	<div class="title-wrapper sl-flex">
+		<SiteTitle {...Astro.props} />
+	</div>
+	<div class="sl-flex print:hidden">
+		{shouldRenderSearch && <Search {...Astro.props} />}
+	</div>
+	<div class="sl-hidden md:sl-flex print:hidden right-group">
+		<nav class="sl-flex nav-links">
+			<a href={`${import.meta.env.BASE_URL}downloads/`}>Downloads</a>
+		</nav>
+		<div class="sl-flex social-icons">
+			<SocialIcons {...Astro.props} />
+		</div>
+		<ThemeSelect {...Astro.props} />
+		<LanguageSelect {...Astro.props} />
+	</div>
+</div>
+
+<style>
+	.header {
+		gap: var(--sl-nav-gap);
+		justify-content: space-between;
+		align-items: center;
+		height: 100%;
+	}
+
+	.title-wrapper {
+		/* Prevent long titles overflowing and covering the search and menu buttons on narrow viewports. */
+		overflow: clip;
+		/* Avoid clipping focus ring around link inside title wrapper. */
+		padding: 0.25rem;
+		margin: -0.25rem;
+		min-width: 0;
+	}
+
+	.right-group,
+	.social-icons,
+	.nav-links {
+		gap: 1rem;
+		align-items: center;
+	}
+
+	.nav-links a {
+		color: var(--sl-color-white);
+		text-decoration: none;
+		font-size: 0.875rem;
+		font-weight: 500;
+		padding: 0.25rem 0.5rem;
+		border-radius: 4px;
+		transition: color 0.15s ease, background-color 0.15s ease;
+	}
+
+	.nav-links a:hover {
+		color: var(--sl-color-accent);
+		background-color: rgba(140, 140, 255, 0.1);
+	}
+
+	.nav-links::after {
+		content: '';
+		height: 2rem;
+		border-inline-end: 1px solid var(--sl-color-gray-5);
+	}
+
+	.social-icons::after {
+		content: '';
+		height: 2rem;
+		border-inline-end: 1px solid var(--sl-color-gray-5);
+	}
+
+	@media (min-width: 50rem) {
+		:global(:root[data-has-sidebar]) {
+			--__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+		}
+		:global(:root:not([data-has-toc])) {
+			--__toc-width: 0rem;
+		}
+		.header {
+			--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
+			--__main-column-fr: calc(
+				(
+						100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
+							(2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
+							var(--sl-content-width)
+					) / 2
+			);
+			display: grid;
+			grid-template-columns:
+        /* 1 (site title): runs up until the main content column’s left edge or the width of the title, whichever is the largest  */
+				minmax(
+					calc(var(--__sidebar-width) + max(0rem, var(--__main-column-fr) - var(--sl-nav-gap))),
+					auto
+				)
+				/* 2 (search box): all free space that is available. */
+				1fr
+				/* 3 (right items): use the space that these need. */
+				auto;
+			align-content: center;
+		}
+	}
+</style>

package/website/src/components/MobileMenuFooter.astro

@@ -0,0 +1,53 @@
+---
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
+import type { Props } from '@astrojs/starlight/props';
+---
+
+<div class="mobile-preferences sl-flex">
+	<div class="sl-flex social-icons">
+		<SocialIcons {...Astro.props} />
+	</div>
+	<nav class="sl-flex nav-links">
+		<a href={`${import.meta.env.BASE_URL}downloads/`}>Downloads</a>
+	</nav>
+	<ThemeSelect {...Astro.props} />
+	<LanguageSelect {...Astro.props} />
+</div>
+
+<style>
+	.social-icons {
+		gap: 1rem;
+		align-items: center;
+		padding-block: 1rem;
+	}
+	.social-icons:empty {
+		display: none;
+	}
+	.mobile-preferences {
+		justify-content: space-between;
+		flex-wrap: wrap;
+		border-top: 1px solid var(--sl-color-gray-6);
+		column-gap: 1rem;
+		padding: 0.5rem 0;
+		align-items: center;
+	}
+	.nav-links {
+		gap: 1rem;
+		align-items: center;
+	}
+	.nav-links a {
+		color: var(--sl-color-white);
+		text-decoration: none;
+		font-size: 0.875rem;
+		font-weight: 500;
+		padding: 0.5rem 0.75rem;
+		border-radius: 4px;
+		transition: color 0.15s ease, background-color 0.15s ease;
+	}
+	.nav-links a:hover {
+		color: var(--sl-color-accent);
+		background-color: rgba(140, 140, 255, 0.1);
+	}
+</style>

package/website/src/content/config.ts

@@ -0,0 +1,6 @@
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema() }),
+};

package/website/src/lib/site-url.js

@@ -0,0 +1,25 @@
+/**
+ * Resolve the site's base URL using cascading environment defaults.
+ *
+ * Preference order: use SITE_URL if set; otherwise derive a GitHub Pages URL from GITHUB_REPOSITORY; otherwise use the local development URL.
+ * @returns {string} The resolved site URL (SITE_URL override, or `https://{owner}.github.io/{repo}`, or `http://localhost:3000`).
+ */
+export function getSiteUrl() {
+  // Explicit override (works in both local and GitHub Actions)
+  if (process.env.SITE_URL) {
+    return process.env.SITE_URL;
+  }
+
+  // GitHub Actions: compute from repository context
+  if (process.env.GITHUB_REPOSITORY) {
+    const parts = process.env.GITHUB_REPOSITORY.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      throw new Error(`Invalid GITHUB_REPOSITORY format: "${process.env.GITHUB_REPOSITORY}". Expected "owner/repo".`);
+    }
+    const [owner, repo] = parts;
+    return `https://${owner}.github.io/${repo}`;
+  }
+
+  // Local development: use dev server
+  return 'http://localhost:3000';
+}

package/website/src/rehype-markdown-links.js

@@ -0,0 +1,102 @@
+/**
+ * Rehype plugin to transform markdown file links (.md) to page routes
+ *
+ * Transforms:
+ *   ./path/to/file.md → ./path/to/file/
+ *   ./path/index.md → ./path/ (index.md becomes directory root)
+ *   ../path/file.md#anchor → ../path/file/#anchor
+ *   ./file.md?query=param → ./file/?query=param
+ *   /docs/absolute/path/file.md → /absolute/path/file/
+ *
+ * For absolute paths starting with /docs/, the /docs prefix is stripped
+ * since the Astro site serves content from the docs directory as the root.
+ *
+ * Affects relative links (./, ../) and absolute paths (/) - external links are unchanged
+ */
+
+import { visit } from 'unist-util-visit';
+
+/**
+ * Convert Markdown file links (.md) into equivalent page route-style links.
+ *
+ * The returned transformer walks the HTML tree and rewrites anchor `href` values that are relative paths (./, ../) or absolute paths (/) pointing to `.md` files. It preserves query strings and hash anchors, rewrites `.../index.md` to the directory root path (`.../`), and rewrites other `.md` file paths by removing the `.md` extension and ensuring a trailing slash. External links (http://, https://) and non-.md links are left unchanged.
+ *
+ * @returns {function} A HAST tree transformer that mutates `a` element `href` properties as described.
+ */
+export default function rehypeMarkdownLinks() {
+  return (tree) => {
+    visit(tree, 'element', (node) => {
+      // Only process anchor tags with href
+      if (node.tagName !== 'a' || !node.properties?.href) {
+        return;
+      }
+
+      const href = node.properties.href;
+
+      // Skip if not a string (shouldn't happen, but be safe)
+      if (typeof href !== 'string') {
+        return;
+      }
+
+      // Skip external links (http://, https://, mailto:, etc.)
+      if (href.includes('://') || href.startsWith('mailto:') || href.startsWith('tel:')) {
+        return;
+      }
+
+      // Only transform paths starting with ./, ../, or / (absolute)
+      if (!href.startsWith('./') && !href.startsWith('../') && !href.startsWith('/')) {
+        return;
+      }
+
+      // Extract path portion (before ? and #) to check if it's a .md file
+      const firstDelimiter = Math.min(
+        href.indexOf('?') === -1 ? Infinity : href.indexOf('?'),
+        href.indexOf('#') === -1 ? Infinity : href.indexOf('#'),
+      );
+      const pathPortion = firstDelimiter === Infinity ? href : href.substring(0, firstDelimiter);
+
+      // Don't transform if path doesn't end with .md
+      if (!pathPortion.endsWith('.md')) {
+        return;
+      }
+
+      // Split the URL into parts: path, anchor, and query
+      let urlPath = pathPortion;
+      let anchor = '';
+      let query = '';
+
+      // Extract query string and anchor from original href
+      if (firstDelimiter !== Infinity) {
+        const suffix = href.substring(firstDelimiter);
+        const anchorInSuffix = suffix.indexOf('#');
+        if (suffix.startsWith('?')) {
+          if (anchorInSuffix !== -1) {
+            query = suffix.substring(0, anchorInSuffix);
+            anchor = suffix.substring(anchorInSuffix);
+          } else {
+            query = suffix;
+          }
+        } else {
+          // starts with #
+          anchor = suffix;
+        }
+      }
+
+      // Strip /docs/ prefix from absolute paths (repo-relative → site-relative)
+      if (urlPath.startsWith('/docs/')) {
+        urlPath = urlPath.slice(5); // Remove '/docs' prefix, keeping the leading /
+      }
+
+      // Transform .md to /
+      // Special case: index.md → directory root (e.g., ./tutorials/index.md → ./tutorials/)
+      if (urlPath.endsWith('/index.md')) {
+        urlPath = urlPath.replace(/\/index\.md$/, '/');
+      } else {
+        urlPath = urlPath.replace(/\.md$/, '/');
+      }
+
+      // Reconstruct the href
+      node.properties.href = urlPath + query + anchor;
+    });
+  };
+}