feat(docs): Diataxis restructure + Astro/Starlight migration #1263
Conversation
- Create tutorials, how-to, explanation, reference directories with subdirectories - Add index.md files for each main Diataxis section - Update homepage with Diataxis card navigation layout - Implement clean React Native-inspired sidebar styling - Convert sidebar to autogenerated for both Diataxis and legacy sections - Update docusaurus config with dark mode default and navbar changes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Move 21 files to new locations: - Tutorials: quick-start guides, agent creation guide - How-To: installation, customization, workflows - Explanation: core concepts, features, game-dev, builder - Reference: merged glossary from BMM and BMGD Also: - Copy images to new locations - Update internal links via migration script (73 links updated) - Build verified successfully 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add _category_.json files to control display labels and position for autogenerated sidebar categories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Rewrite index.md with React Native-inspired welcoming layout - Add Diataxis section cards with descriptions - Remove sidebar separator, add spacing instead - Increase navbar padding with responsive breakpoints - Add rounded admonitions without left border bar - Use system font stack for better readability - Add lighter chevron styling in sidebar - Constrain max-width to 1600px for wide viewports 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Phase 2 of Diataxis migration: - Split 16 large legacy files into 42+ focused documents - Created FAQ section with 7 topic-specific files - Created brownfield how-to guides (3 files) - Created workflow how-to guides (15+ files) - Created architecture explanation files (3 files) - Created TEA/testing explanation files - Moved remaining legacy module files to proper Diataxis locations Link fixes: - Fixed ~50 broken internal links across documentation - Updated relative paths for new file locations - Created missing index files for installation, advanced tutorials - Simplified TOC anchors to fix Docusaurus warnings Cleanup: - Removed legacy sidebar entries for deleted folders - Deleted duplicate and empty placeholder files - Moved workflow diagram assets to tutorials/images 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Replace brittle sidebar.js regex parsing with recursive file glob. The old approach captured non-file strings like 'autogenerated' and category labels, resulting in only 5 files being processed. Now correctly processes all 86+ markdown files (~95k tokens). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
AI web-browsing agents couldn't follow relative paths in meta tags due to URL security restrictions. Changed llms-full.txt and llms.txt meta tag URLs from relative (baseUrl) to absolute (urlParts.origin + baseUrl). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Phase 2.5 categorization fixes based on post-migration analysis: Moved to correct Diataxis categories: - tutorials/installation.md → deleted (duplicate of how-to/install-bmad.md) - tutorials/brownfield-onboarding.md → how-to/brownfield/index.md - reference/faq/* (8 files) → explanation/faq/ - reference/agents/barry-quick-flow.md → explanation/agents/ - reference/agents/bmgd-agents.md → explanation/game-dev/agents.md Created: - explanation/agents/index.md Fixed all broken internal links (14 total) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Add comprehensive Getting Started tutorial with installation as Step 1 - Simplify build-docs.js to read directly from docs/ (no consolidation) - Remove backup/restore dance that could corrupt docs folder on build failure - Remove ~150 lines of unused consolidation code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Apply React Native docs approach: set both width and max-width at largest breakpoint (1400px) so content area maintains consistent size regardless of content length. Switches to fluid 100% below 1416px breakpoint. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Rename index.md to bmad-tutorial.md for clearer navigation - Remove redundant tutorials/index.md - Update sidebar and config references 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Add docs/_contributing/ with tutorial style guide - Reformat quick-start-bmm.md and bmad-tutorial.md per style guide - Remove horizontal separators, add strategic admonitions - Add persistent announcement bar for AI agents directing to llms-full.txt - Fix footer broken link to tutorials 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Add comprehensive markdown-demo.md for style testing - Remove doc category links from navbar (use sidebar instead) - Remove card buttons from welcome page - Add dark mode styling for announcement bar - Clean up index.md card layout 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Reformat create-custom-agent.md to follow tutorial style guide - Update tutorial-style.md with complete unified structure - Update all internal references to renamed tutorial files - Remove obsolete advanced/index.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
alexeyv
force-pushed
the
feat/diataxis-starlight
branch
from
e4cb71a to
fa01a22
Compare
|
@CodeRabbit review |
✅ Actions performedReview triggered.
|
📝 WalkthroughWalkthroughThis PR migrates the documentation site from Docusaurus to Astro with Starlight, reorganizing content into a Diataxis-style structure (Tutorials, How-To Guides, Explanation, Reference), rewriting the build pipeline, updating dependencies, and introducing new Astro components and configuration while removing legacy Docusaurus artifacts. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom Pre-merge Checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/explanation/creative-intelligence/index.md (1)
88-115: Restore or document Configuration and Module Structure sections.The removed "Configuration" and "Module Structure" sections with YAML examples and directory layout diagrams are not documented elsewhere in the repository. No CIS-specific configuration guide or module structure documentation exists. Either restore these sections to the CIS documentation or create a dedicated configuration reference document to maintain completeness.
docs/explanation/features/web-bundles.md (1)
37-37: Update backlink text to match destination.The backlink text says "Back to Core Concepts," but the relative path
../index.mdresolves todocs/explanation/index.md(the Explanation section hub), not the Core Concepts section. Since web-bundles is categorized under Features, update the text to "Back to Explanation" to match the actual destination.
🤖 Fix all issues with AI agents
In @docs/_contributing/index.md:
- Line 18: Update the outdated framework name in the contributor docs: replace
the phrase "Docusaurus sidebar" in the `_contributing/` index line with
"Starlight sidebar" so the sentence reads that the directory is prefixed to
exclude it from the Starlight sidebar; keep the rest of the sentence unchanged.
In @docs/explanation/architecture/_category_.json:
- Line 1: Remove the orphaned Docusaurus `_category_.json` files that are unused
by Starlight/Astro; specifically delete files like the shown `_category_.json`
(e.g., the one with { "label": "Architecture", "position": 2 }) throughout the
docs/ tree, and rely on Starlight’s autogenerate feature (the autogenerate: {
directory: ... } configuration in astro.config.mjs) to generate navigation from
folder and file names instead of keeping these legacy files.
In @docs/explanation/bmad-builder/custom-content-types.md:
- Around line 20-26: Replace the unhyphenated compound modifiers in both anchor
list items and section headers: change "Custom Stand Alone Modules" to "Custom
Stand-Alone Modules" and "Custom Add On Modules" to "Custom Add-On Modules"
wherever they appear (including the anchor link texts and the corresponding
section headings such as the header currently titled "Custom Stand Alone
Modules" and the later header for add-on modules), and ensure the anchor targets
match the updated hyphenated header text so links continue to work.
In @docs/explanation/bmm/index.md:
- Line 35: In the line containing the Phase 4 description ("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 planing completed"), fix
the spelling of "planing" to "planning" so the sentence reads with "extensive
planning completed".
In @docs/explanation/game-dev/_category_.json:
- Line 1: The Docusaurus-style _category_.json containing "label" and "position"
is incompatible with Starlight; replace it by removing this JSON file and
instead add the category metadata to the category's index document using
Starlight-compatible frontmatter (e.g., set title: "Game Development" and
order/position: 6 in the index.md or equivalent), or convert the JSON keys
("label" and "position") into the proper Starlight frontmatter fields in the
category's index file so the category title and ordering are preserved.
In @docs/how-to/customization/_category_.json:
- Line 1: Legacy Docusaurus `_category_.json` files (e.g., the file with content
`{ "label": "Customization", "position": 3 }`) are not used by Astro/Starlight
and should be deleted; remove this `_category_.json` and the other ~20 instances
found across the docs directory, and ensure navigation is driven by markdown
frontmatter/autogenerate settings in your markdown files and `astro.config.mjs`
instead of relying on these JSON files.
In @docs/how-to/customization/vendor-workflows.md:
- Line 2: The YAML frontmatter title string contains an extra closing
parenthesis: update the title value for the key title from "Workflow Vendoring,
Customization, and Inheritance (Official Support Coming Soon))" to "Workflow
Vendoring, Customization, and Inheritance (Official Support Coming Soon)" by
removing the stray closing parenthesis in the title line.
In @docs/how-to/ide-setup/_category_.json:
- Line 1: Remove the unused Docusaurus artifact _category_.json (e.g.,
docs/how-to/ide-setup/_category_.json) that Starlight/astro autogenerate
sidebars ignore; delete all occurrences of "_category_.json" across the docs
directory, and if any categories or ordering are required, configure them in
astro.config.mjs using Starlight's sidebar/autogenerate options or convert
needed metadata into supported formats (frontmatter or index files).
In @docs/tutorials/advanced/_category_.json:
- Line 1: Remove the orphaned Docusaurus `_category_.json` files (e.g.,
docs/tutorials/advanced/_category_.json and the other ~19 duplicates) since
Starlight/Astro does not use them; delete these files from the repo, ensure no
build/sidebar config references `_category_.json`, and confirm the docs use
autogenerate directory-based sidebars with markdown frontmatter instead.
In @docs/tutorials/getting-started/getting-started-bmadv6.md:
- Around line 28-32: Add the missing asterisk command prefix to make triggers
consistent with the Quick Reference: replace create-architecture,
create-epics-and-stories, implementation-readiness, sprint-planning, and
retrospective with *create-architecture, *create-epics-and-stories,
*implementation-readiness, *sprint-planning, and *retrospective respectively,
and also change workflow-init to *workflow-init in the quick-path section so all
documented command triggers uniformly use the leading `*` prefix (verify
occurrences around the noted lines and update any other instances in this
document).
In @docs/tutorials/getting-started/markdown-demo.md:
- Around line 258-285: The snippet uses JSX/MDX syntax (className attributes and
style={{...}} objects) and Docusaurus CSS vars (--ifm-color-primary-*) which
Starlight's Markdown does not support; update the card layout divs (the <div
className="row"> block and inner <div className="col col--6">/card elements) to
use standard HTML attributes (class instead of className) and convert any style
object notation to inline style strings (e.g., style="margin-bottom: 1rem;
border: 1px solid var(--sl-color-hairline);"), change the anchor buttons to use
class="button ..." and inline style strings for spacing, and replace Docusaurus
variables in the color palette block with Starlight CSS variables from
custom.css (e.g., --sl-color-accent, --sl-color-accent-high,
--sl-color-accent-low) or hex values so the content renders correctly without
MDX enabled.
In @package.json:
- Around line 88-92: Update the Astro version constraint in package.json so it
allows v5.1.5 or newer to satisfy Starlight v0.31; change the "astro" dependency
value (the "astro" key in package.json) from "^5.1.3" to a constraint that
includes 5.1.5 or higher (e.g., "^5.1.5") and then run a lockfile update/install
to ensure the new compatible Astro version is picked up.
In @tools/check-doc-links.js:
- Around line 157-160: The loop that reads files uses readFileSync(file,
'utf-8') without error handling which can crash if a file is removed or
inaccessible; wrap the readFileSync call in a try-catch around the body that
calls extractLinks and computes relativePath (inside the for (const file of
files) loop), log or report the caught error (using the existing logger/console
style used elsewhere) and continue to the next file instead of throwing; mirror
the try-catch pattern used earlier for readFileSync to ensure a single-broken
file doesn't fail the whole script.
- Line 160: Replace the manual string concat and replace used to compute
relativePath with a proper path API call: instead of file.replace(DOCS_DIR +
'/', ''), use path.relative(DOCS_DIR, file) (via the Node.js path module) to
compute the relative path robustly across platforms; update the reference to the
path module if not already imported.
In @website/src/rehype-markdown-links.js:
- Around line 67-68: The URL is being rebuilt in non-standard order: currently
node.properties.href = urlPath + anchor + query; change this to assemble as path
then query then fragment, e.g. node.properties.href = urlPath + (query || '') +
(anchor || ''); ensure the variables (urlPath, query, anchor) include their
delimiters ('?' for query and '#' for anchor) or normalize them before
concatenation so the final href follows the standard path?query#fragment format.
🧹 Nitpick comments (19)
docs/how-to/workflows/conduct-research.md (1)
49-52: Optional: Consider varying vocabulary for flow.The word "deep" appears in close proximity across the table and depth section (lines 49, 52, and 68). While the meaning is clear, you might strengthen the wording by using alternatives (e.g., "thorough," "in-depth," "comprehensive") to add variety. This is a minor stylistic observation.
Also applies to: 68-68
src/modules/cis/module.yaml (1)
8-12: Consider clarifying the documentation wording.The comment says "Variables from Core Config inserted:" but these variables don't appear in the YAML structure itself. The word "inserted" could be misleading—it suggests these variables are added to this configuration file, when they likely refer to runtime dependencies or references.
Consider using clearer wording such as "Variables used from Core Config:" or "Variables referenced from Core Config:" to better convey that these are dependencies the module accesses, not literal insertions into this structure.
🔎 Suggested wording improvement
# Variables used from Core Config: ## user_name ## communication_language ## document_output_language ## output_folderdocs/explanation/bmm/index.md (2)
28-28: Hyphenate compound adjective "one-size-fits-all".The phrase "one size fits all" should be hyphenated when used as a compound adjective: "one-size-fits-all".
🔎 Proposed fix
The BMad Method is meant to be adapted and customized to your specific needs. In this realm there is no one-size-fits-all - your needs are unique, and BMad Method is meant to support this (and if it does not, can be further customized or extended with new modules).
92-92: Hyphenate "stand-alone" or use "standalone".The phrase "stand alone" should be hyphenated as "stand-alone" when used as an adjective, or written as one word: "standalone".
🔎 Proposed fix (using "standalone")
→ Use the [Quick Flow Solo Dev](../agents/barry-quick-flow.md) directly with its dedicated standalone [Quick Bmad Spec Flow](../features/quick-flow.md) processwebsite/src/rehype-markdown-links.js (1)
35-38: Consider tightening the.mddetection.The check
href.includes('.md')will match paths like./file.mdxand process them unnecessarily (though they won't be transformed due to theendsWithcheck later). This is a minor inefficiency.🔎 Optional improvement
- // Don't transform if already doesn't have .md (already transformed or link to directory) - if (!href.includes('.md')) { + // Only transform links ending with .md (skip .mdx and already-transformed links) + if (!href.endsWith('.md') && !href.includes('.md#') && !href.includes('.md?')) { return; }Alternatively, the simpler approach would be to just remove this early-return and let the
endsWithchecks handle it, since the performance difference is negligible.tools/build-docs.js (2)
92-93: Remove commented-out code.The
injectAgentBannercall is commented out. If this functionality is no longer needed (banner is now handled by Astro/Starlight), remove the comment entirely rather than leaving dead code.- // No longer needed: Inject AI agents banner into every HTML page - // injectAgentBanner(siteDir); -
357-371: Unused functiongetAllFilesByExtension.This function appears to be unused after the
injectAgentBannerfunctionality was removed. Consider removing it to avoid dead code.-// ============================================================================= -// Post-build Injection -// ============================================================================= - -function getAllFilesByExtension(dir, ext) { - const result = []; - const entries = fs.readdirSync(dir, { withFileTypes: true }); - - for (const entry of entries) { - const fullPath = path.join(dir, entry.name); - if (entry.isDirectory()) { - result.push(...getAllFilesByExtension(fullPath, ext)); - } else if (entry.name.endsWith(ext)) { - result.push(fullPath); - } - } - - return result; -} -docs/how-to/index.md (1)
24-34: Consider adding placeholder notes or removing empty sections.The "Workflows", "Brownfield Projects", and "Troubleshooting" sections contain only descriptions without any links. This may confuse users who expect navigable content under these headings. Consider either:
- Adding "Coming soon" placeholders (similar to line 15)
- Temporarily removing these sections until content is available
- Adding at least one link per section to provide value
docs/reference/index.md (1)
8-26: Consider adding entry point links for each section.This reference hub contains only section descriptions without any links to actual content. While this may work as a high-level overview, adding at least one representative link per section would make the page more useful as an entry point. For example:
- Under "Agents": link to the agents index
- Under "Workflows": link to the workflows index
- And so forth
docs/how-to/installation/install-custom-modules.md (1)
1-3: Consistency check: Front matter structure across docs.This file uses front matter with only a
titlefield, whiledocs/how-to/workflows/setup-party-mode.mdincludes bothtitleanddescription. Consider standardizing front matter structure across similar documentation files to ensure consistent metadata handling in Astro/Starlight rendering.docs/how-to/workflows/setup-party-mode.md (1)
1-4: Front matter includes description field; verify consistency against other docs.This file's front matter includes both
titleanddescriptionfields, whiledocs/reference/configuration/global-config.mdanddocs/how-to/installation/install-custom-modules.mdinclude onlytitle. If thedescriptionfield is intended for How-To guides specifically, document this convention. Otherwise, standardize front matter structure across all documentation to ensure consistent metadata handling in Astro/Starlight.website/README.md (1)
40-69: Comprehensive Windows platform guidance.The Windows symlink documentation is thorough and provides practical alternatives. This is important given the symlink-based architecture of the site. The note about keeping a copied docs folder in sync (line 69) is valuable but consider documenting a strategy (e.g., npm script) to automate this if developers choose the copy approach.
Consider adding a brief note or npm script suggestion (if applicable) for automating docs sync:
Note: If copying, consider using an npm script or file watcher to keep the copy in sync automatically with changes to `docs/`.website/src/lib/site-url.js (1)
16-19: Consider adding validation for GITHUB_REPOSITORY format.While GitHub Actions consistently provides
GITHUB_REPOSITORYin the format "owner/repo", adding validation would make the function more robust against unexpected environments.🔎 Proposed defensive validation
// GitHub Actions: compute from repository context if (process.env.GITHUB_REPOSITORY) { const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/'); + if (!owner || !repo) { + console.warn(`Invalid GITHUB_REPOSITORY format: ${process.env.GITHUB_REPOSITORY}. Expected "owner/repo".`); + return 'http://localhost:3000'; + } return `https://${owner}.github.io/${repo}`; }docs/explanation/core-concepts/what-are-agents.md (1)
90-93: Consider restructuring the customization instruction for clarity.Line 92 contains a long compound sentence that weakens the emphasis on the critical guidance about not modifying installed agent .md files directly. Consider breaking this into separate sentences to highlight the important warning upfront:
You can modify any agent's behavior without editing core files. See [BMAD Customization](../../how-to/customization/index.md) for details. **Important:** Never modify an installed agent's .md file directly. Follow the customization process instead. This ensures future updates to the agent or module will continue to be applied and recompiled by the installer tool, while your customizations remain intact.docs/how-to/workflows/create-tech-spec.md (1)
2-3: Clarify workflow terminology in the description.The frontmatter description references "Quick Spec Flow," but the document content refers to the "tech-spec workflow" as part of "Quick Flow projects." Update the description to match how the workflow is named and categorized in the content to avoid reader confusion.
description: How to create a technical specification using the Tech Spec workflow in Quick Flowdocs/downloads.md (1)
36-40: Hardcoded domain in API example may not align with site configuration.The Python example hardcodes the domain
bmad-code-org.github.io/BMAD-METHOD/, which could become stale or inconsistent if the site URL or deployment context changes. Consider whether this should reference a configurable base URL or dynamically generated link.Given the Astro migration with cascading site URL configuration (per PR summary), verify that this hardcoded value is intentional and maintained in sync with the site's actual deployment URL.
docs/how-to/workflows/run-sprint-planning.md (1)
107-111: Inconsistent workflow reference: line 110 links toimplement-story.mdbut line 88 referencesdev-story.The "Related" section links to
./implement-story.md, but the "Typical Sprint Flow" section (line 88) instructs developers to rundev-story. This appears to be a naming inconsistency—verify that the linked file name is correct.If the workflow is actually named
dev-story.md, the link should be updated to match.website/src/components/MobileMenuFooter.astro (1)
5-5: Optional: Unused type import.The
Propstype is imported but never explicitly referenced. If this import serves as documentation or future-proofing, consider adding a comment. Otherwise, it can be safely removed.🔎 Proposed cleanup
--- import LanguageSelect from 'virtual:starlight/components/LanguageSelect'; import SocialIcons from 'virtual:starlight/components/SocialIcons'; import ThemeSelect from 'virtual:starlight/components/ThemeSelect'; ---tools/check-doc-links.js (1)
114-125: Extend file resolution to handle .mdx extension.The glob pattern at line 151 includes both
.mdand.mdxfiles, but the link resolution logic only tries the.mdextension (line 117). If a markdown link references a file without an extension and only a.mdxversion exists, the checker will incorrectly report it as a broken link.🔎 Proposed enhancement
// If link doesn't have extension, try .md - if (!resolved.endsWith('.md') && !existsSync(resolved)) { + if (!resolved.endsWith('.md') && !resolved.endsWith('.mdx') && !existsSync(resolved)) { const withMd = resolved + '.md'; if (existsSync(withMd)) { return withMd; } + const withMdx = resolved + '.mdx'; + if (existsSync(withMdx)) { + return withMdx; + } // Try as directory with index.md const asIndex = join(resolved, 'index.md'); if (existsSync(asIndex)) { return asIndex; } + const asIndexMdx = join(resolved, 'index.mdx'); + if (existsSync(asIndexMdx)) { + return asIndexMdx; + } }
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
docs/tutorials/getting-started/images/workflow-method-greenfield.svgis excluded by!**/*.svgdocs/tutorials/getting-started/images/workflow-overview.jpgis excluded by!**/*.jpgdocs/tutorials/getting-started/workflow-overview.jpgis excluded by!**/*.jpgpackage-lock.jsonis excluded by!**/package-lock.jsonwebsite/public/favicon.icois excluded by!**/*.icowebsite/public/img/logo.svgis excluded by!**/*.svg
📒 Files selected for processing (149)
.github/workflows/docs.yaml.gitignoredocs/404.mddocs/_contributing/index.mddocs/_contributing/tutorial-style.mddocs/bmad-core-concepts/index.mddocs/bmad-core-concepts/installing/index.mddocs/downloads.mddocs/explanation/agents/barry-quick-flow.mddocs/explanation/agents/index.mddocs/explanation/architecture/_category_.jsondocs/explanation/architecture/four-phases.mddocs/explanation/architecture/preventing-agent-conflicts.mddocs/explanation/architecture/why-solutioning-matters.mddocs/explanation/bmad-builder/_category_.jsondocs/explanation/bmad-builder/custom-content-types.mddocs/explanation/bmad-builder/index.mddocs/explanation/bmm/index.mddocs/explanation/core-concepts/_category_.jsondocs/explanation/core-concepts/agent-roles.mddocs/explanation/core-concepts/index.mddocs/explanation/core-concepts/what-are-agents.mddocs/explanation/core-concepts/what-are-modules.mddocs/explanation/core-concepts/what-are-workflows.mddocs/explanation/core/index.mddocs/explanation/creative-intelligence/_category_.jsondocs/explanation/creative-intelligence/index.mddocs/explanation/faq/brownfield-faq.mddocs/explanation/faq/getting-started-faq.mddocs/explanation/faq/implementation-faq.mddocs/explanation/faq/index.mddocs/explanation/faq/levels-and-tracks-faq.mddocs/explanation/faq/planning-faq.mddocs/explanation/faq/tools-faq.mddocs/explanation/faq/workflows-faq.mddocs/explanation/features/_category_.jsondocs/explanation/features/advanced-elicitation.mddocs/explanation/features/brainstorming-techniques.mddocs/explanation/features/party-mode.mddocs/explanation/features/quick-flow.mddocs/explanation/features/tea-overview.mddocs/explanation/features/web-bundles.mddocs/explanation/game-dev/_category_.jsondocs/explanation/game-dev/agents.mddocs/explanation/game-dev/bmgd-vs-bmm.mddocs/explanation/game-dev/game-types.mddocs/explanation/game-dev/index.mddocs/explanation/index.mddocs/explanation/philosophy/_category_.jsondocs/explanation/philosophy/facilitation-over-generation.mddocs/how-to/brownfield/_category_.jsondocs/how-to/brownfield/add-feature-to-existing.mddocs/how-to/brownfield/document-existing-project.mddocs/how-to/brownfield/index.mddocs/how-to/brownfield/quick-fix-in-brownfield.mddocs/how-to/customization/_category_.jsondocs/how-to/customization/customize-agents.mddocs/how-to/customization/customize-workflows.mddocs/how-to/customization/index.mddocs/how-to/customization/shard-large-documents.mddocs/how-to/customization/vendor-workflows.mddocs/how-to/ide-setup/_category_.jsondocs/how-to/index.mddocs/how-to/installation/_category_.jsondocs/how-to/installation/index.mddocs/how-to/installation/install-bmad.mddocs/how-to/installation/install-custom-modules.mddocs/how-to/installation/upgrade-to-v6.mddocs/how-to/troubleshooting/_category_.jsondocs/how-to/troubleshooting/bmgd-troubleshooting.mddocs/how-to/workflows/_category_.jsondocs/how-to/workflows/bmgd-quick-flow.mddocs/how-to/workflows/conduct-research.mddocs/how-to/workflows/create-architecture.mddocs/how-to/workflows/create-epics-and-stories.mddocs/how-to/workflows/create-prd.mddocs/how-to/workflows/create-product-brief.mddocs/how-to/workflows/create-story.mddocs/how-to/workflows/create-tech-spec.mddocs/how-to/workflows/create-ux-design.mddocs/how-to/workflows/implement-story.mddocs/how-to/workflows/run-brainstorming-session.mddocs/how-to/workflows/run-code-review.mddocs/how-to/workflows/run-implementation-readiness.mddocs/how-to/workflows/run-sprint-planning.mddocs/how-to/workflows/run-test-design.mddocs/how-to/workflows/setup-party-mode.mddocs/how-to/workflows/setup-test-framework.mddocs/index.mddocs/modules/bmb-bmad-builder/agent-creation-guide.mddocs/modules/bmb-bmad-builder/index.mddocs/modules/bmgd-bmad-game-dev/glossary.mddocs/modules/bmgd-bmad-game-dev/index.mddocs/modules/bmgd-bmad-game-dev/quick-start.mddocs/modules/bmm-bmad-method/bmad-quick-flow.mddocs/modules/bmm-bmad-method/faq.mddocs/modules/bmm-bmad-method/quick-spec-flow.mddocs/modules/bmm-bmad-method/quick-start.mddocs/modules/bmm-bmad-method/test-architecture.mddocs/modules/bmm-bmad-method/troubleshooting.mddocs/modules/bmm-bmad-method/workflows-analysis.mddocs/modules/bmm-bmad-method/workflows-implementation.mddocs/modules/bmm-bmad-method/workflows-planning.mddocs/modules/bmm-bmad-method/workflows-solutioning.mddocs/modules/core/index.mddocs/modules/core/party-mode.mddocs/reference/agents/_category_.jsondocs/reference/agents/index.mddocs/reference/configuration/_category_.jsondocs/reference/configuration/core-tasks.mddocs/reference/configuration/global-config.mddocs/reference/glossary/_category_.jsondocs/reference/glossary/index.mddocs/reference/index.mddocs/reference/workflows/_category_.jsondocs/reference/workflows/bmgd-workflows.mddocs/reference/workflows/core-workflows.mddocs/reference/workflows/document-project.mddocs/reference/workflows/index.mddocs/tutorials/advanced/_category_.jsondocs/tutorials/advanced/create-custom-agent.mddocs/tutorials/first-project/_category_.jsondocs/tutorials/getting-started/_category_.jsondocs/tutorials/getting-started/getting-started-bmadv4.mddocs/tutorials/getting-started/getting-started-bmadv6.mddocs/tutorials/getting-started/images/workflow-diagrams-README.mddocs/tutorials/getting-started/images/workflow-method-greenfield.excalidrawdocs/tutorials/getting-started/markdown-demo.mddocs/tutorials/getting-started/quick-start-bmgd.mddocs/tutorials/index.mdpackage.jsonsrc/modules/cis/module.yamltools/build-docs.jstools/check-doc-links.jswebsite/README.mdwebsite/astro.config.mjswebsite/css/custom.csswebsite/docusaurus.config.jswebsite/public/robots.txtwebsite/sidebars.jswebsite/src/components/Banner.astrowebsite/src/components/Header.astrowebsite/src/components/MobileMenuFooter.astrowebsite/src/content/config.tswebsite/src/content/docswebsite/src/lib/site-url.jswebsite/src/pages/index.jswebsite/src/rehype-markdown-links.jswebsite/src/styles/custom.css
💤 Files with no reviewable changes (23)
- docs/modules/bmgd-bmad-game-dev/index.md
- docs/bmad-core-concepts/installing/index.md
- website/sidebars.js
- docs/modules/bmb-bmad-builder/agent-creation-guide.md
- docs/modules/bmm-bmad-method/quick-spec-flow.md
- docs/modules/bmb-bmad-builder/index.md
- docs/modules/bmm-bmad-method/quick-start.md
- docs/modules/bmm-bmad-method/workflows-planning.md
- docs/bmad-core-concepts/index.md
- docs/modules/bmm-bmad-method/troubleshooting.md
- docs/modules/core/index.md
- docs/modules/bmm-bmad-method/workflows-solutioning.md
- docs/modules/bmgd-bmad-game-dev/quick-start.md
- docs/modules/bmm-bmad-method/workflows-implementation.md
- docs/modules/bmm-bmad-method/bmad-quick-flow.md
- docs/modules/core/party-mode.md
- docs/modules/bmm-bmad-method/test-architecture.md
- docs/modules/bmm-bmad-method/workflows-analysis.md
- docs/modules/bmgd-bmad-game-dev/glossary.md
- website/css/custom.css
- website/src/pages/index.js
- docs/modules/bmm-bmad-method/faq.md
- website/docusaurus.config.js
🧰 Additional context used
📓 Path-based instructions (2)
**/*
⚙️ CodeRabbit configuration file
**/*: Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:<code changes>
Files:
docs/explanation/philosophy/_category_.jsondocs/how-to/installation/index.mddocs/404.mddocs/how-to/customization/_category_.jsondocs/how-to/brownfield/quick-fix-in-brownfield.mddocs/explanation/features/_category_.jsondocs/how-to/workflows/create-prd.mddocs/how-to/customization/index.mddocs/explanation/game-dev/bmgd-vs-bmm.mddocs/how-to/workflows/run-code-review.mddocs/explanation/faq/index.mddocs/explanation/bmad-builder/_category_.jsondocs/how-to/index.mddocs/how-to/installation/upgrade-to-v6.mddocs/_contributing/tutorial-style.mddocs/how-to/brownfield/document-existing-project.mddocs/tutorials/getting-started/_category_.jsondocs/reference/index.mddocs/how-to/workflows/create-story.mddocs/explanation/features/quick-flow.mddocs/tutorials/advanced/_category_.jsondocs/explanation/faq/tools-faq.mddocs/reference/agents/index.mddocs/explanation/index.mdwebsite/README.mddocs/explanation/core/index.mddocs/how-to/installation/install-custom-modules.mddocs/tutorials/getting-started/images/workflow-diagrams-README.mddocs/explanation/philosophy/facilitation-over-generation.mddocs/explanation/faq/brownfield-faq.mddocs/how-to/customization/customize-workflows.mddocs/how-to/workflows/conduct-research.mddocs/explanation/architecture/preventing-agent-conflicts.mddocs/explanation/agents/index.mddocs/downloads.mddocs/explanation/faq/planning-faq.mddocs/explanation/creative-intelligence/index.mddocs/how-to/brownfield/index.mddocs/how-to/installation/install-bmad.mddocs/how-to/workflows/setup-test-framework.mddocs/explanation/core-concepts/_category_.jsondocs/how-to/brownfield/add-feature-to-existing.mddocs/how-to/ide-setup/_category_.jsondocs/_contributing/index.mddocs/how-to/workflows/implement-story.mddocs/how-to/workflows/bmgd-quick-flow.mddocs/reference/configuration/global-config.mddocs/reference/workflows/_category_.jsondocs/tutorials/first-project/_category_.jsondocs/explanation/features/tea-overview.mddocs/how-to/workflows/create-epics-and-stories.mddocs/how-to/workflows/run-test-design.mddocs/explanation/faq/getting-started-faq.mddocs/how-to/customization/shard-large-documents.mdwebsite/src/content/config.tsdocs/how-to/workflows/create-architecture.mddocs/explanation/game-dev/index.mddocs/explanation/architecture/four-phases.mddocs/explanation/core-concepts/what-are-agents.mddocs/how-to/troubleshooting/bmgd-troubleshooting.mddocs/explanation/features/web-bundles.mddocs/explanation/architecture/why-solutioning-matters.mddocs/how-to/workflows/create-tech-spec.mdtools/check-doc-links.jsdocs/tutorials/getting-started/markdown-demo.mddocs/reference/workflows/core-workflows.mddocs/how-to/workflows/create-ux-design.mddocs/explanation/bmad-builder/index.mddocs/reference/workflows/document-project.mddocs/reference/agents/_category_.jsondocs/how-to/workflows/run-implementation-readiness.mdwebsite/src/rehype-markdown-links.jsdocs/explanation/bmm/index.mddocs/reference/workflows/index.mdwebsite/src/styles/custom.cssdocs/reference/workflows/bmgd-workflows.mddocs/explanation/features/advanced-elicitation.mddocs/how-to/troubleshooting/_category_.jsondocs/explanation/game-dev/_category_.jsondocs/explanation/core-concepts/agent-roles.mddocs/tutorials/getting-started/getting-started-bmadv6.mddocs/explanation/game-dev/game-types.mddocs/explanation/core-concepts/what-are-workflows.mddocs/explanation/faq/workflows-faq.mdwebsite/src/lib/site-url.jsdocs/explanation/agents/barry-quick-flow.mddocs/explanation/core-concepts/index.mddocs/tutorials/advanced/create-custom-agent.mdwebsite/astro.config.mjsdocs/reference/glossary/index.mddocs/how-to/workflows/setup-party-mode.mddocs/reference/configuration/_category_.jsondocs/explanation/core-concepts/what-are-modules.mddocs/explanation/creative-intelligence/_category_.jsondocs/tutorials/getting-started/getting-started-bmadv4.mddocs/tutorials/index.mddocs/explanation/faq/levels-and-tracks-faq.mdwebsite/src/components/Banner.astrodocs/explanation/faq/implementation-faq.mddocs/explanation/architecture/_category_.jsonwebsite/src/components/MobileMenuFooter.astrodocs/index.mddocs/explanation/features/brainstorming-techniques.mddocs/reference/configuration/core-tasks.mddocs/how-to/customization/vendor-workflows.mdsrc/modules/cis/module.yamldocs/tutorials/getting-started/quick-start-bmgd.mddocs/explanation/bmad-builder/custom-content-types.mddocs/how-to/workflows/run-sprint-planning.mddocs/how-to/installation/_category_.jsondocs/how-to/brownfield/_category_.jsondocs/how-to/workflows/create-product-brief.mddocs/how-to/workflows/run-brainstorming-session.mdwebsite/src/components/Header.astrodocs/reference/glossary/_category_.jsondocs/how-to/workflows/_category_.jsonpackage.jsondocs/explanation/features/party-mode.mdtools/build-docs.jsdocs/how-to/customization/customize-agents.mdwebsite/src/content/docsdocs/explanation/game-dev/agents.md
**/*.js
⚙️ CodeRabbit configuration file
**/*.js: CLI tooling code. Check for: missing error handling on fs operations,
path.join vs string concatenation, proper cleanup in error paths.
Flag any process.exit() without error message.
Files:
tools/check-doc-links.jswebsite/src/rehype-markdown-links.jswebsite/src/lib/site-url.jstools/build-docs.js
🧬 Code graph analysis (2)
tools/check-doc-links.js (2)
tools/cli/installers/lib/ide/shared/module-injections.js (1)
pattern(111-111)tools/cli/installers/lib/ide/shared/bmad-artifacts.js (1)
filePath(42-42)
website/astro.config.mjs (2)
website/src/lib/site-url.js (1)
getSiteUrl(9-23)website/src/rehype-markdown-links.js (1)
rehypeMarkdownLinks(15-71)
🪛 LanguageTool
docs/_contributing/tutorial-style.md
[style] ~89-~89: To elevate your writing, try using a synonym here.
Context: ...** — Admonitions inside admonitions are hard to read ## Headers ### Budget - **8-...
(HARD_TO)
docs/explanation/index.md
[style] ~14-~14: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...core-concepts/what-are-workflows.md) - [What are Modules?](./core-concepts/what-are-...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/explanation/philosophy/facilitation-over-generation.md
[style] ~105-~105: Consider a different adjective to strengthen your wording.
Context: ...--- ## Benefits ### For Individuals - Deeper insights than pure generation - Ownersh...
(DEEP_PROFOUND)
docs/how-to/workflows/conduct-research.md
[style] ~49-~49: Consider a different adjective to strengthen your wording.
Context: ...s/platforms | | competitive | Deep competitor analysis ...
(DEEP_PROFOUND)
[style] ~68-~68: Consider a different adjective to strengthen your wording.
Context: ... - Balanced depth - Comprehensive - Deep analysis --- ## What You Get ### Mar...
(DEEP_PROFOUND)
docs/explanation/bmm/index.md
[grammar] ~28-~28: Use a hyphen to join words.
Context: ...fic needs. In this realm there is no one size fits all - your needs are unique, a...
(QB_NEW_EN_HYPHEN)
[grammar] ~28-~28: Use a hyphen to join words.
Context: ...eeds. In this realm there is no one size fits all - your needs are unique, and BM...
(QB_NEW_EN_HYPHEN)
[grammar] ~35-~35: Ensure spelling is correct
Context: ...or the dev agent based on the extensive planing completed - All 4 phases have optio...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~35-~35: Ensure spelling is correct
Context: ...based on the extensive planing completed - All 4 phases have optional steps in them...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~92-~92: Use a hyphen to join words.
Context: ...ow.md) directly with its dedicated stand alone [Quick Bmad Spec Flow](../features...
(QB_NEW_EN_HYPHEN)
docs/tutorials/advanced/create-custom-agent.md
[style] ~65-~65: Consider a different adjective to strengthen your wording.
Context: ...vides options: - [A] Advanced - Get deeper insights and reasoning - [P] Party ...
(DEEP_PROFOUND)
docs/explanation/faq/levels-and-tracks-faq.md
[style] ~58-~58: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 2136 characters long)
Context: .../discord.gg/gk8jAdXWmj) so we can add it!
(EN_EXCESSIVE_EXCLAMATION)
docs/explanation/faq/implementation-faq.md
[style] ~56-~56: Using many exclamation marks might seem excessive (in this case: 4 exclamation marks for a text that’s 1947 characters long)
Context: .../discord.gg/gk8jAdXWmj) so we can add it!
(EN_EXCESSIVE_EXCLAMATION)
docs/index.md
[style] ~18-~18: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...familiar with AI-assisted development?] Feel free to skip around. Use the sidebar to jump to...
(FEEL_FREE_TO_STYLE_ME)
docs/tutorials/getting-started/quick-start-bmgd.md
[grammar] ~134-~134: Use a hyphen to join words.
Context: ...e-specific sections. BMGD offers 24 game type templates that provide genre-specif...
(QB_NEW_EN_HYPHEN)
docs/explanation/bmad-builder/custom-content-types.md
[grammar] ~20-~20: Use a hyphen to join words.
Context: ...ofession ## Categories - [Custom Stand Alone Modules](#custom-stand-alone-modul...
(QB_NEW_EN_HYPHEN)
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...ustom-stand-alone-modules) - Custom Add On Modules - [C...
(QB_NEW_EN_HYPHEN)
[grammar] ~26-~26: Use a hyphen to join words.
Context: ...ows](#custom-workflows) ## Custom Stand Alone Modules Custom modules range from...
(QB_NEW_EN_HYPHEN)
[style] ~29-~29: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ad Method or even larger applications. Custom modules are [installable](../../how-to/...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
✅ Actions performedInitiated docstring generation; will generate only if new commits exist. |
|
Note Docstrings generation - SUCCESS |
Docstrings generation was requested by @alexeyv. * #1263 (comment) The following files were modified: * `tools/build-docs.js` * `tools/check-doc-links.js` * `website/src/lib/site-url.js` * `website/src/rehype-markdown-links.js`
Docstrings generation was requested by @alexeyv. * bmad-code-org#1263 (comment) The following files were modified: * `tools/build-docs.js` * `tools/check-doc-links.js` * `website/src/lib/site-url.js` * `website/src/rehype-markdown-links.js`
alexeyv
force-pushed
the
feat/diataxis-starlight
branch
from
807cccd to
b033b02
Compare
|
@CodeRabbit review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
tools/build-docs.js (1)
505-525: Add error handler for the write stream.If
fs.createWriteStream(outputPath)fails (e.g., invalid path, permission denied), the error won't be caught. Add an error listener on the output stream.Suggested fix
function createZipArchive(sourceDir, outputPath, exclude = []) { return new Promise((resolve, reject) => { const output = fs.createWriteStream(outputPath); const archive = archiver('zip', { zlib: { level: 9 } }); output.on('close', resolve); + output.on('error', reject); archive.on('error', reject);
🤖 Fix all issues with AI agents
In @docs/explanation/faq/levels-and-tracks-faq.md:
- Line 16: The Level 1 story range is inconsistent: the bullet "**Level 1:**
\"simple\", \"basic\", \"small feature\", \"add\" → 2-10 stories" on the
document conflicts with another instance stating "1-10 stories"; update the
Level 1 bullet(s) to use the consistent range "1-10 stories" by replacing "2-10
stories" with "1-10 stories" wherever the "**Level 1:** \"simple\", \"basic\",
\"small feature\", \"add\"" line appears (including the instance referenced
around line 39) so both entries match.
In @docs/explanation/index.md:
- Around line 16-35: Update the "Architecture" and "Philosophy" sections in the
explanation index to include navigation links to the existing articles: under
the "Architecture" heading add links to four-phases.md,
preventing-agent-conflicts.md, and why-solutioning-matters.md; under the
"Philosophy" heading add a link to facilitation-over-generation.md; ensure link
text is descriptive (e.g., "Four Phases", "Preventing Agent Conflicts", "Why
Solutioning Matters", "Facilitation Over Generation") and follow the same
relative-link style used for the Features list so the pages are discoverable
from the index.
In @docs/how-to/installation/install-bmad.md:
- Around line 96-104: Update the configuration example in the install docs to
include the missing key document_output_language; specifically, in the
`_bmad/[module]/config.yaml` sample that currently lists output_folder,
user_name and communication_language, add the document_output_language entry
with a value (e.g., "english") so the example matches the core module's
inheritable configuration.
In @tools/build-docs.js:
- Around line 336-350: runAstroBuild currently runs the Astro build and silently
skips the rename if the expected astroOutput ('website/dist') is missing; add
explicit error handling after computing astroOutput to detect when
fs.existsSync(astroOutput) is false and throw or log a clear error that includes
the astroOutput path and a hint to check Astro config, so callers (or the
process) fail fast instead of later breaking in copyArtifactsToSite; update
runAstroBuild to either throw a descriptive Error or call process.exit(1) with a
processLogger.error message referencing runAstroBuild, astroOutput and siteDir
so the failure is obvious.
In @website/src/lib/site-url.js:
- Around line 14-17: Validate process.env.GITHUB_REPOSITORY format before
destructuring: in the block that reads process.env.GITHUB_REPOSITORY and does
const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/'), first check that
the string exists and contains exactly one '/' (e.g., split results in two
non-empty parts) and only then assign owner and repo; if the format is invalid,
fall back to a safe default or skip building the GitHub Pages URL and optionally
log a warning so you don't return URLs like
https://undefined.github.io/undefined.
🧹 Nitpick comments (16)
docs/_STYLE_GUIDE.md (4)
12-35: Clarify which tutorial sections are essential vs. optional.The 15-step template (lines 14–32) is presented as a numbered list, which signals a required sequence, but line 34 disclaims that not all sections are required. This creates ambiguity for contributors deciding what to include.
Consider explicitly categorizing sections into:
- Essential: Title, What You'll Learn, Prerequisites, Steps, What You've Accomplished
- Recommended: Quick Path, Understanding [Topic], Quick Reference, Common Questions
- Optional: Getting Help, Key Takeaways (depending on context)
This will help contributors prioritize without sacrificing structure consistency.
289-309: Align checklist with essential vs. optional section distinction.The checklist presents all 16 items as required (checkbox format), which contradicts line 34's statement that not all tutorial sections are necessary. Contributors will interpret this checklist as a hard requirement, leading to submissions that include unnecessary sections or rejection feedback for missing optional content.
Suggest splitting the checklist into two tiers:
- Essential (must pass before review)
- Recommended (encouraged but not blockers)
This also improves the submission experience by clarifying what gate-keeps approval.
253-287: Consider adding a complete tutorial example to demonstrate full structure.The "Before and After" example (lines 255–287) is a helpful formatting guide for individual sections, but it doesn't show how all 15 sections come together in a complete tutorial. A contributor might still be uncertain about structure and flow once they finish writing.
Optional: Consider adding a link to or summary of a real tutorial in the codebase that exemplifies the full structure, or include a skeletal outline showing all sections with brief placeholders.
91-97: Minor: Strengthen word choice in admonition guideline.Line 96 reads: "Don't nest — Admonitions inside admonitions are hard to read." Consider replacing "hard to read" with a more precise synonym like "difficult to parse," "confusing," or "challenging to scan" to better align with the guide's instructional tone.
docs/how-to/workflows/run-implementation-readiness.md (1)
20-24: Expand context for skip conditions.Lines 22-23 mention "Quick Flow" and "BMad Method Simple" as skip scenarios, but these process variants aren't explained in this document. If these are standard BMad Method terms, reference or link to their definitions so users unfamiliar with them can understand when this workflow doesn't apply.
docs/explanation/bmad-builder/custom-content-types.md (1)
26-30: Consider rewording to avoid successive sentences starting with "Custom."Lines 28–30 contain two consecutive sentences beginning with "Custom modules." While the content is clear and accurate, varying the sentence structure would improve readability:
- Line 28: "Custom modules range from…"
- Line 30: "Custom modules are [installable]…"
Consider rephrasing one of these (e.g., "These modules are installable…") to provide more stylistic variety.
docs/how-to/installation/install-bmad.md (1)
113-116: Minor: Fix whitespace in bash code block.Line 115 has an extra blank line after the
brew install nodecommand, which may cause formatting issues when rendered.🔎 Proposed fix
brew install node -</details> </blockquote></details> <details> <summary>docs/explanation/bmm/index.md (1)</summary><blockquote> `28-28`: **Apply standard hyphenation for compound adjectives.** Compound adjectives preceding nouns should be hyphenated for clarity. Two instances need correction: 1. Line 28: "one size fits all" → "one-size-fits-all" 2. Line 92: "stand alone" → "stand-alone" <details> <summary>🔎 Proposed fixes</summary> Line 28: ```suggestion The BMad Method is meant to be adapted and customized to your specific needs. In this realm there is no one-size-fits-all - your needs are unique, and BMad Method is meant to support this (and if it does not, can be further customized or extended with new modules).Line 92:
→ Use the [Quick Flow Solo Dev](../agents/barry-quick-flow.md) directly with its dedicated stand-alone [Quick Bmad Spec Flow](../features/quick-flow.md) processAlso applies to: 92-92
website/src/rehype-markdown-links.js (1)
42-45: Consider a more precise check for.mdfiles.The current check uses
href.includes('.md'), which matches any href containing.mdas a substring, including edge cases like./folder.md/file.html. While the transformation logic (lines 68-72) correctly usesendsWith('.md'), files that pass this check but don't end with.mdwill still have their query strings and anchors extracted and reconstructed (lines 47-64, 75), potentially reordering them.For more precise behavior, consider extracting the path portion first (before
?and#), then checking if it ends with.md:🔎 Refactor to check path portion specifically
- // Don't transform if already doesn't have .md (already transformed or link to directory) - if (!href.includes('.md')) { - return; - } + // Extract the path portion (before query/anchor) to check for .md extension + const pathOnly = href.split('?')[0].split('#')[0]; + if (!pathOnly.endsWith('.md')) { + return; + }docs/explanation/index.md (2)
1-3: Consider adding a description field to front matter for consistency.File 1 and File 3 both include a
descriptionfield in their front matter, but this file omits it. Starlight uses this metadata for SEO and navigation context. Consider aligning with the broader documentation pattern.
12-14: Reduce repetition in list item openings.Three successive list items begin with "What are..." which creates repetitive phrasing. Consider rewording one or more items for variety, e.g., "Understanding Agents", "The Role of Workflows", etc.
docs/how-to/workflows/bmgd-quick-flow.md (1)
1-3: Consider adding adescriptionfield for consistency and SEO.Page descriptions are used for page metadata and picked up by search engines and in social media previews. While optional, files 2 and 3 in this review set include descriptions. For consistency across the documentation set, consider adding one here.
Suggested addition
--- title: "BMGD Quick-Flow Guide" +description: Fast-track workflows for rapid game prototyping and flexible development ---docs/how-to/brownfield/index.md (1)
1-14: Minor terminology inconsistency with Diataxis structure.Line 13 refers to this as a "tutorial," but the file resides in the
how-to/directory. Per Diataxis, tutorials and how-to guides serve different purposes. Consider rewording to align with the how-to classification:This guide covers the essential workflow for onboarding to brownfield projects with BMad Method.website/src/styles/custom.css (2)
205-211: Consider documenting or revisiting the!importantusage.The
!importantonpadding(line 206) may be necessary to override Starlight defaults, but it can make future style adjustments harder to debug. If this is intentional, a brief comment explaining why would help maintainability.
306-319: Broad selector may cause unintended hover effects.The selector
.sl-flex a[href], buttonapplies hover transforms broadly. This could affect elements where the lift effect isn't desired. Consider scoping more specifically if unexpected hover behaviors occur during testing.tools/build-docs.js (1)
361-371: Consider defensive checks for artifact files.
fs.copyFileSyncwill throw if the source files don't exist. While the build order ensuresllms.txtandllms-full.txtare created first, adding existence checks would provide clearer error messages if something goes wrong.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (3)
package-lock.jsonis excluded by!**/package-lock.jsonwebsite/public/favicon.icois excluded by!**/*.icowebsite/public/img/logo.svgis excluded by!**/*.svg
📒 Files selected for processing (106)
.github/workflows/docs.yaml.gitignoredocs/404.mddocs/_README_WORKFLOW_DIAGRAMS.mddocs/_STYLE_GUIDE.mddocs/downloads.mddocs/explanation/agents/barry-quick-flow.mddocs/explanation/agents/index.mddocs/explanation/architecture/four-phases.mddocs/explanation/architecture/preventing-agent-conflicts.mddocs/explanation/architecture/why-solutioning-matters.mddocs/explanation/bmad-builder/custom-content-types.mddocs/explanation/bmad-builder/index.mddocs/explanation/bmm/index.mddocs/explanation/core-concepts/agent-roles.mddocs/explanation/core-concepts/index.mddocs/explanation/core-concepts/what-are-agents.mddocs/explanation/core-concepts/what-are-modules.mddocs/explanation/core-concepts/what-are-workflows.mddocs/explanation/core/index.mddocs/explanation/creative-intelligence/index.mddocs/explanation/faq/brownfield-faq.mddocs/explanation/faq/getting-started-faq.mddocs/explanation/faq/implementation-faq.mddocs/explanation/faq/index.mddocs/explanation/faq/levels-and-tracks-faq.mddocs/explanation/faq/planning-faq.mddocs/explanation/faq/tools-faq.mddocs/explanation/faq/workflows-faq.mddocs/explanation/features/advanced-elicitation.mddocs/explanation/features/brainstorming-techniques.mddocs/explanation/features/party-mode.mddocs/explanation/features/quick-flow.mddocs/explanation/features/tea-overview.mddocs/explanation/features/web-bundles.mddocs/explanation/game-dev/agents.mddocs/explanation/game-dev/bmgd-vs-bmm.mddocs/explanation/game-dev/game-types.mddocs/explanation/game-dev/index.mddocs/explanation/index.mddocs/explanation/philosophy/facilitation-over-generation.mddocs/how-to/brownfield/add-feature-to-existing.mddocs/how-to/brownfield/document-existing-project.mddocs/how-to/brownfield/index.mddocs/how-to/brownfield/quick-fix-in-brownfield.mddocs/how-to/customization/customize-agents.mddocs/how-to/customization/customize-workflows.mddocs/how-to/customization/index.mddocs/how-to/customization/shard-large-documents.mddocs/how-to/customization/vendor-workflows.mddocs/how-to/index.mddocs/how-to/installation/index.mddocs/how-to/installation/install-bmad.mddocs/how-to/installation/install-custom-modules.mddocs/how-to/installation/upgrade-to-v6.mddocs/how-to/troubleshooting/bmgd-troubleshooting.mddocs/how-to/workflows/bmgd-quick-flow.mddocs/how-to/workflows/conduct-research.mddocs/how-to/workflows/create-architecture.mddocs/how-to/workflows/create-epics-and-stories.mddocs/how-to/workflows/create-prd.mddocs/how-to/workflows/create-product-brief.mddocs/how-to/workflows/create-story.mddocs/how-to/workflows/create-tech-spec.mddocs/how-to/workflows/create-ux-design.mddocs/how-to/workflows/implement-story.mddocs/how-to/workflows/run-brainstorming-session.mddocs/how-to/workflows/run-code-review.mddocs/how-to/workflows/run-implementation-readiness.mddocs/how-to/workflows/run-sprint-planning.mddocs/how-to/workflows/run-test-design.mddocs/how-to/workflows/setup-party-mode.mddocs/how-to/workflows/setup-test-framework.mddocs/index.mddocs/reference/agents/index.mddocs/reference/configuration/core-tasks.mddocs/reference/configuration/global-config.mddocs/reference/glossary/index.mddocs/reference/index.mddocs/reference/workflows/bmgd-workflows.mddocs/reference/workflows/core-workflows.mddocs/reference/workflows/document-project.mddocs/reference/workflows/index.mddocs/tutorials/advanced/create-custom-agent.mddocs/tutorials/getting-started/getting-started-bmadv4.mddocs/tutorials/getting-started/getting-started-bmadv6.mddocs/tutorials/getting-started/quick-start-bmgd.mddocs/tutorials/index.mdpackage.jsontools/build-docs.jstools/check-doc-links.jswebsite/README.mdwebsite/astro.config.mjswebsite/css/custom.csswebsite/docusaurus.config.jswebsite/public/robots.txtwebsite/sidebars.jswebsite/src/components/Banner.astrowebsite/src/components/Header.astrowebsite/src/components/MobileMenuFooter.astrowebsite/src/content/config.tswebsite/src/content/docswebsite/src/lib/site-url.jswebsite/src/pages/index.jswebsite/src/rehype-markdown-links.jswebsite/src/styles/custom.css
💤 Files with no reviewable changes (4)
- website/css/custom.css
- website/src/pages/index.js
- website/docusaurus.config.js
- website/sidebars.js
✅ Files skipped from review due to trivial changes (12)
- docs/_README_WORKFLOW_DIAGRAMS.md
- website/src/content/docs
- docs/explanation/features/brainstorming-techniques.md
- docs/explanation/architecture/four-phases.md
- docs/explanation/core/index.md
- docs/how-to/customization/vendor-workflows.md
- docs/explanation/features/advanced-elicitation.md
- docs/explanation/core-concepts/index.md
- docs/explanation/bmad-builder/index.md
- docs/how-to/workflows/run-code-review.md
- docs/how-to/index.md
- docs/explanation/core-concepts/what-are-workflows.md
🚧 Files skipped from review as they are similar to previous changes (41)
- docs/how-to/installation/index.md
- docs/explanation/game-dev/bmgd-vs-bmm.md
- docs/how-to/workflows/run-brainstorming-session.md
- docs/404.md
- docs/how-to/workflows/implement-story.md
- docs/explanation/game-dev/index.md
- docs/explanation/architecture/why-solutioning-matters.md
- docs/how-to/workflows/create-tech-spec.md
- docs/how-to/workflows/create-prd.md
- docs/explanation/architecture/preventing-agent-conflicts.md
- docs/how-to/brownfield/document-existing-project.md
- docs/reference/configuration/core-tasks.md
- docs/how-to/brownfield/add-feature-to-existing.md
- docs/explanation/features/tea-overview.md
- docs/reference/workflows/document-project.md
- docs/how-to/workflows/create-product-brief.md
- website/astro.config.mjs
- docs/explanation/core-concepts/what-are-agents.md
- docs/reference/workflows/index.md
- docs/how-to/customization/customize-workflows.md
- website/src/components/Banner.astro
- .github/workflows/docs.yaml
- tools/check-doc-links.js
- docs/explanation/faq/tools-faq.md
- docs/how-to/workflows/create-story.md
- docs/reference/workflows/bmgd-workflows.md
- docs/explanation/features/party-mode.md
- docs/explanation/features/quick-flow.md
- website/README.md
- docs/tutorials/index.md
- docs/how-to/installation/upgrade-to-v6.md
- docs/how-to/workflows/create-epics-and-stories.md
- docs/how-to/customization/shard-large-documents.md
- docs/explanation/faq/index.md
- docs/reference/index.md
- docs/how-to/workflows/create-architecture.md
- docs/explanation/features/web-bundles.md
- docs/explanation/core-concepts/what-are-modules.md
- .gitignore
- docs/how-to/workflows/run-test-design.md
- docs/how-to/workflows/run-sprint-planning.md
🧰 Additional context used
📓 Path-based instructions (2)
**/*
⚙️ CodeRabbit configuration file
**/*: Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:<code changes>
Files:
docs/tutorials/getting-started/getting-started-bmadv6.mdwebsite/src/rehype-markdown-links.jsdocs/explanation/faq/getting-started-faq.mdwebsite/src/lib/site-url.jsdocs/how-to/customization/customize-agents.mddocs/explanation/bmm/index.mddocs/_STYLE_GUIDE.mddocs/downloads.mdwebsite/src/content/config.tsdocs/how-to/workflows/setup-test-framework.mddocs/how-to/customization/index.mddocs/how-to/workflows/setup-party-mode.mddocs/how-to/brownfield/index.mddocs/explanation/game-dev/agents.mddocs/explanation/faq/workflows-faq.mddocs/reference/configuration/global-config.mddocs/how-to/troubleshooting/bmgd-troubleshooting.mddocs/explanation/game-dev/game-types.mdpackage.jsondocs/explanation/agents/index.mddocs/how-to/workflows/run-implementation-readiness.mddocs/reference/workflows/core-workflows.mddocs/index.mddocs/how-to/workflows/bmgd-quick-flow.mddocs/explanation/faq/brownfield-faq.mddocs/explanation/agents/barry-quick-flow.mdwebsite/src/styles/custom.cssdocs/reference/agents/index.mddocs/reference/glossary/index.mddocs/how-to/installation/install-bmad.mdwebsite/src/components/Header.astrodocs/explanation/creative-intelligence/index.mddocs/how-to/installation/install-custom-modules.mddocs/tutorials/getting-started/quick-start-bmgd.mdtools/build-docs.jsdocs/tutorials/getting-started/getting-started-bmadv4.mddocs/how-to/brownfield/quick-fix-in-brownfield.mddocs/explanation/faq/planning-faq.mdwebsite/src/components/MobileMenuFooter.astrodocs/explanation/core-concepts/agent-roles.mddocs/how-to/workflows/create-ux-design.mddocs/explanation/bmad-builder/custom-content-types.mddocs/explanation/faq/implementation-faq.mddocs/explanation/faq/levels-and-tracks-faq.mddocs/explanation/index.mddocs/explanation/philosophy/facilitation-over-generation.mddocs/how-to/workflows/conduct-research.mddocs/tutorials/advanced/create-custom-agent.md
**/*.js
⚙️ CodeRabbit configuration file
**/*.js: CLI tooling code. Check for: missing error handling on fs operations,
path.join vs string concatenation, proper cleanup in error paths.
Flag any process.exit() without error message.
Files:
website/src/rehype-markdown-links.jswebsite/src/lib/site-url.jstools/build-docs.js
🪛 LanguageTool
docs/explanation/bmm/index.md
[grammar] ~28-~28: Use a hyphen to join words.
Context: ...fic needs. In this realm there is no one size fits all - your needs are unique, a...
(QB_NEW_EN_HYPHEN)
[grammar] ~28-~28: Use a hyphen to join words.
Context: ...eeds. In this realm there is no one size fits all - your needs are unique, and BM...
(QB_NEW_EN_HYPHEN)
[grammar] ~92-~92: Use a hyphen to join words.
Context: ...ow.md) directly with its dedicated stand alone [Quick Bmad Spec Flow](../features...
(QB_NEW_EN_HYPHEN)
docs/_STYLE_GUIDE.md
[style] ~96-~96: To elevate your writing, try using a synonym here.
Context: ...** — Admonitions inside admonitions are hard to read ## Headers ### Budget - **8-...
(HARD_TO)
docs/index.md
[style] ~18-~18: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...familiar with AI-assisted development?] Feel free to skip around. Use the sidebar to jump to...
(FEEL_FREE_TO_STYLE_ME)
docs/tutorials/getting-started/quick-start-bmgd.md
[grammar] ~134-~134: Use a hyphen to join words.
Context: ...e-specific sections. BMGD offers 24 game type templates that provide genre-specif...
(QB_NEW_EN_HYPHEN)
docs/explanation/bmad-builder/custom-content-types.md
[style] ~29-~29: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ad Method or even larger applications. Custom modules are [installable](../../how-to/...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/explanation/faq/implementation-faq.md
[style] ~56-~56: Using many exclamation marks might seem excessive (in this case: 4 exclamation marks for a text that’s 1947 characters long)
Context: .../discord.gg/gk8jAdXWmj) so we can add it!
(EN_EXCESSIVE_EXCLAMATION)
docs/explanation/faq/levels-and-tracks-faq.md
[style] ~58-~58: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 2136 characters long)
Context: .../discord.gg/gk8jAdXWmj) so we can add it!
(EN_EXCESSIVE_EXCLAMATION)
docs/explanation/index.md
[style] ~14-~14: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...core-concepts/what-are-workflows.md) - [What are Modules?](./core-concepts/what-are-...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/explanation/philosophy/facilitation-over-generation.md
[style] ~105-~105: Consider a different adjective to strengthen your wording.
Context: ...--- ## Benefits ### For Individuals - Deeper insights than pure generation - Ownersh...
(DEEP_PROFOUND)
docs/how-to/workflows/conduct-research.md
[style] ~49-~49: Consider a different adjective to strengthen your wording.
Context: ...s/platforms | | competitive | Deep competitor analysis ...
(DEEP_PROFOUND)
[style] ~68-~68: Consider a different adjective to strengthen your wording.
Context: ... - Balanced depth - Comprehensive - Deep analysis --- ## What You Get ### Mar...
(DEEP_PROFOUND)
docs/tutorials/advanced/create-custom-agent.md
[style] ~65-~65: Consider a different adjective to strengthen your wording.
Context: ...vides options: - [A] Advanced - Get deeper insights and reasoning - [P] Party ...
(DEEP_PROFOUND)
🔇 Additional comments (59)
docs/reference/configuration/global-config.md (1)
1-3: YAML frontmatter correctly applied.The conversion from top-level H1 header to YAML frontmatter is properly formatted and aligns with the Astro/Starlight migration pattern described in this PR. The title is descriptive and matches the document scope.
docs/reference/workflows/core-workflows.md (2)
1-4: YAML front matter properly formatted and aligns with migration goals.The front-matter metadata follows the expected structure and the
titlefield matches the document's primary subject.
10-10: All internal link destinations exist and are correctly positioned.The relative link paths in lines 10, 14, and 18 pointing to
../../explanation/features/are valid. All three destination files are in place:
docs/explanation/features/party-mode.md✓docs/explanation/features/brainstorming-techniques.md✓docs/explanation/features/advanced-elicitation.md✓docs/reference/agents/index.md (4)
1-140: Summary mismatch: AI description references workflows, but file documents agents.The AI-generated summary describes reference workflows content, but the actual file is a comprehensive agent reference guide. This appears to be a metadata discrepancy rather than a content issue.
1-4: Front matter structure looks good for Astro/Starlight migration.The YAML front matter properly defines title and description metadata, aligning with the documented site migration patterns.
11-125: Well-structured agent reference with consistent formatting.Each agent section follows a clear pattern: header, role description, formatted command list, and divider. Command syntax is uniform and content is comprehensive.
140-141: Verify that linked explanation pages exist at the specified paths.The relative links reference:
../../explanation/core-concepts/agent-roles.md../../explanation/core-concepts/what-are-agents.mdThe paths resolve correctly from the file location, and the PR indicates the link checker passed, but confirm these files exist in the restructured documentation tree.
docs/how-to/workflows/create-ux-design.md (1)
1-119: ✓ Well-structured how-to guide aligned with Diataxis format.The document effectively guides users through the UX design workflow with clear decision criteria (when/skip), prerequisites, step-by-step execution, concrete examples, and integration points. Structure, pacing, and content depth are appropriate for a how-to guide.
docs/explanation/agents/barry-quick-flow.md (2)
1-3: Frontmatter correctly follows Astro/Starlight conventions.The YAML frontmatter properly replaces the previous H1 header and provides structured metadata. The title matches the agent's persona and is correctly formatted.
313-317: Related Documentation links are correctly updated and verified.The five updated links use consistent relative paths that correctly navigate from the file's location (
docs/explanation/agents/) to the new Diataxis-reorganized structure (tutorials, explanation, how-to). The relative path structure (../../ascending todocs/) is accurate for the file location, and the link checker passing during deployment verification confirms these links work correctly with the rehype plugin transformation.docs/how-to/workflows/run-implementation-readiness.md (4)
27-32: Clarify dependencies between prerequisites.Lines 29-30 list "BMad Method installed" and "Architect agent available" as separate prerequisites, but it's unclear whether the Architect agent is provided by BMad Method or is a separate external dependency. Align this with how other workflow docs handle similar prerequisites for consistency.
1-162: Overall structure is well-organized and follows the Diataxis how-to pattern effectively.The document provides clear purpose, prerequisites, actionable steps, and concrete outcomes. The gate decision framework (PASS/CONCERNS/FAIL) is logically structured and actionable. The example section grounds the guidance in a realistic scenario. Once prerequisite and phase terminology are aligned with related docs, this will integrate well into the reorganized documentation.
158-162: Relative links in the Related section are correct.All three referenced workflow documents exist in the same directory and resolve correctly:
./create-architecture.md✅./create-epics-and-stories.md✅./run-sprint-planning.md✅
13-15: No action needed—Phase 4 terminology and sequencing are well-defined and consistent.Phase 4 (Implementation) is clearly defined in the reference documentation and consistently applied across all workflow guides. The sequencing is accurate: implementation-readiness validates alignment after create-epics-and-stories and before sprint-planning, as a required gate check for BMad Method and Enterprise projects. The documentation provides sufficient context for these phase references.
docs/how-to/installation/install-custom-modules.md (1)
1-9: Cross-reference paths verified; front matter correctly formatted.The YAML front matter and the link to Custom Content Types (line 8) are properly configured for the Diataxis restructure. The relative path
../../explanation/bmad-builder/custom-content-types.mdcorrectly navigates fromdocs/how-to/installation/to the explanation section.docs/explanation/bmad-builder/custom-content-types.md (1)
20-24: Hyphenation correctly applied; cross-reference paths verified.The hyphenation of compound modifiers (Stand-Alone Modules, Add-On Modules) across section headers and anchor links is consistent and correct, addressing the prior documentation standards. The bidirectional cross-reference between this file (line 30) and
install-custom-modules.md(line 8) is properly configured with correct relative paths (../../how-to/installation/install-custom-modules.mdand../../explanation/bmad-builder/custom-content-types.md). This creates appropriate linking within the Diataxis structure.Also applies to: 26-39, 47-47
docs/reference/glossary/index.md (2)
1-338: Navigation and structure look solid.The glossary reorganization is well-executed: the new navigation link (line 20) properly anchors to the Game Development Terms section, existing definitions have been thoughtfully expanded (Technical Writer, Party Mode), and new agent roles (Game Architect, Game Designer) integrate cleanly into the Agents and Roles section. The formatting and anchor patterns are consistent throughout.
280-338: Game Development Terms section is accurate and well-aligned with BMAD implementation.The definitions correctly reflect both BMAD-specific concepts (Core Fantasy, Core Loop, Design Pillar, Game Type, Narrative Complexity) and industry-standard game dev terminology. Core Fantasy and Core Loop are established concepts in BMAD's game designer workflow, Game Type references the 24 supported GDD templates, and Narrative Complexity aligns with BMAD's narrative level classifications (narrative-critical, narrative-heavy, narrative-moderate). The section is comprehensive and appropriately integrated with the glossary.
docs/explanation/bmm/index.md (1)
1-135: Link structure appears sound for Diataxis migration context.The internal navigation references use consistent relative path patterns appropriate for the reorganized directory structure. Anchor references (e.g.,
#workflow-guidesat line 32) align with corresponding section headers. Given the PR's documentation restructuring scope, the link patterns look correct.If you haven't already validated the deployed site, run the internal link checker mentioned in the PR objectives to confirm all referenced files resolve correctly in the final build.
docs/how-to/workflows/setup-test-framework.md (1)
1-113: Clear, well-structured how-to guide for TEA framework setup.The document provides actionable steps, clear prerequisites, concrete output examples, and appropriate optional integrations. Structure follows best practices for how-to documentation.
Verify that the external npm package reference at line 78 (
@seontechnologies/playwright-utils) is correct and available. Also confirm that the sibling file references at lines 112-113 (./run-test-design.md,./create-architecture.md) exist in the workflows folder.docs/tutorials/advanced/create-custom-agent.md (1)
1-171: Comprehensive, well-paced tutorial with clear learning progression.The tutorial effectively scaffolds the agent creation journey from type selection through installation and validation. Clear learning objectives, prerequisites, tables for quick reference, a worked example section, and a strong FAQ make this accessible to first-time users.
Verify that the referenced documentation links at lines 162-164 exist:
../../explanation/core-concepts/what-are-agents.md../../how-to/customization/customize-agents.md../../how-to/installation/install-custom-modules.mdAlso confirm that the GitHub links to example agents at lines 152-153 are still valid and point to the correct reference implementations.
docs/how-to/customization/customize-agents.md (1)
204-206: All "Next Steps" documentation links are correctly implemented. The three referenced files exist with proper Starlight-compatible front-matter:
docs/explanation/core-concepts/what-are-agents.md✓docs/tutorials/advanced/create-custom-agent.md✓docs/explanation/bmm/index.md✓docs/how-to/customization/index.md (1)
12-13: No action required —customize-workflows.mdexists in the correct location with proper YAML front matter and contains expected content.docs/how-to/workflows/setup-party-mode.md (1)
116-117: All documentation links are correctly referenced.Both files exist at the expected paths and relative links are properly structured.
docs/explanation/core-concepts/agent-roles.md (1)
1-204: LGTM! Well-structured agent taxonomy documentation.The agent roles documentation is comprehensive, well-organized with clear phase mapping, and includes helpful cross-references. The table structure and internal links follow consistent patterns aligned with the Diataxis restructure.
docs/explanation/game-dev/game-types.md (2)
1-3: LGTM! Front matter addition aligns with Astro migration.The YAML front matter follows standard Astro/Starlight conventions and provides proper page metadata.
504-506: LGTM! Link updates consistent with Diataxis restructure.The updated navigation links correctly point to the reorganized documentation structure (tutorials, reference sections).
docs/how-to/workflows/conduct-research.md (1)
1-130: LGTM! Clear and comprehensive research workflow guide.The documentation provides well-structured guidance with clear prerequisites, steps, research type comparison table, and examples. Internal links follow consistent patterns aligned with the documentation restructure.
docs/explanation/faq/planning-faq.md (1)
1-47: LGTM! Clear and helpful planning FAQ.The FAQ provides concise answers to common planning questions with appropriate context and recommendations. The links to related documentation and community resources are well-placed.
docs/how-to/troubleshooting/bmgd-troubleshooting.md (2)
1-3: LGTM - Front matter addition is correct.The YAML front matter follows proper Astro/Starlight conventions and provides the necessary metadata for the documentation site.
259-261: LGTM - Navigation links updated correctly.The relative paths are structured correctly for the new Diataxis-based directory organization. The PR notes indicate link validation passed, confirming these targets exist.
website/src/content/config.ts (1)
1-6: LGTM - Standard Astro v5 + Starlight content collection configuration.This correctly implements the content collections API for Astro v5 with Starlight's documentation schema, enabling structured content loading from the
website/src/content/docs/directory.docs/downloads.md (3)
1-3: LGTM - Front matter addition is correct.Proper YAML front matter for Astro/Starlight integration.
7-13: LGTM - Source Bundles section is well-structured.The new section provides clear download options with descriptive table format.
25-40: AI summary inconsistency detected.The AI summary states that "inline code-block guidance under Claude Projects, ChatGPT, and API Usage sections, including their example blocks" were removed, along with "the Python API usage code block." However, these code examples are still present in the file at lines 25-40. The actual code takes precedence over the summary.
docs/tutorials/getting-started/quick-start-bmgd.md (3)
1-4: LGTM - Front matter is complete and correct.Includes both title and description fields for proper Starlight integration.
134-134: Static analysis false positive - no hyphen needed.The LanguageTool suggestion to hyphenate "game type" is incorrect. The phrase "game type templates" means "templates for game types" and does not require hyphenation. Hyphens are only needed when "game type" functions as a compound adjective directly modifying a noun (e.g., "game-type-specific structure").
1-260: LGTM - Comprehensive and well-structured tutorial.The tutorial provides clear step-by-step guidance with proper use of Starlight callouts, tables, and code examples. Content aligns well with the BMGD workflow structure.
docs/explanation/game-dev/agents.md (2)
1-3: LGTM - Front matter addition is correct.Proper YAML front matter format for Astro/Starlight documentation.
408-410: LGTM - Navigation links correctly updated for new structure.The relative paths are correctly structured for the Diataxis reorganization, and the PR indicates link validation passed successfully.
docs/explanation/creative-intelligence/index.md (1)
120-121: Linked markdown files verified. Both referenced explanation pages exist at the expected locations in the documentation structure:
- ✓
docs/explanation/philosophy/facilitation-over-generation.md- ✓
docs/explanation/features/brainstorming-techniques.mdThe relative paths in lines 120-121 are correct.
docs/explanation/agents/index.md (1)
15-27: All referenced documentation files exist. The five markdown files linked from this index page are present at their correct relative paths in the documentation structure.docs/how-to/workflows/bmgd-quick-flow.md (1)
287-291: Updated navigation links look good.All paths follow correct relative routing from
docs/how-to/workflows/, and the updated navigation properly reflects the reorganized Diataxis structure. Given that link validation passed, these should resolve correctly.docs/how-to/brownfield/quick-fix-in-brownfield.md (1)
1-94: Documentation structure and content look solid.The file is well-organized with clear sections, appropriate front matter with SEO-friendly description, and consistent internal linking. The content aligns with the broader brownfield workflow guidance mentioned in the PR context.
docs/explanation/faq/workflows-faq.md (1)
1-68: FAQ content and structure are well-executed.Clear Q&A format with consistent front matter, appropriate links to related documentation, and the closing note inviting community engagement is good practice. The content provides practical answers to anticipated questions about BMad Method workflows.
docs/index.md (1)
1-65: LGTM - Clean documentation restructure.The new landing page effectively introduces BMad with clear navigation, well-organized sections following the Diataxis framework, and helpful quick-start guidance. The structure, front-matter metadata, and internal links align well with the broader Astro/Starlight migration.
docs/tutorials/getting-started/getting-started-bmadv6.md (1)
1-247: Tutorial structure is comprehensive and clear.The v6 Alpha tutorial provides excellent coverage of the workflow, with helpful callouts for alpha software warnings, fresh chat reminders, and phase-by-phase guidance. The command syntax inconsistency flagged in the previous review remains the primary issue to address.
website/src/components/Header.astro (1)
1-121: LGTM - Well-structured Astro component.The Header component follows standard Astro and Starlight patterns with proper conditional rendering logic, correct BASE_URL usage for path resolution, and intentional grid layout CSS for content alignment. The component integrations (Banner, Search, navigation elements) are cleanly implemented.
docs/explanation/faq/brownfield-faq.md (1)
1-80: LGTM - Clear and actionable FAQ.The brownfield FAQ provides concise, well-structured answers to common questions with appropriate cross-references to related documentation. The Q&A format effectively addresses workflow selection, context management, and convention-handling decisions.
docs/tutorials/getting-started/getting-started-bmadv4.md (1)
1-247: LGTM - Well-structured and pedagogically sound tutorial.The v4 tutorial provides comprehensive, step-by-step guidance with a clear and consistent approach to command syntax: natural language instructions first (e.g., "Run workflow-init"), followed by explicitly labeled shorthand alternatives (e.g., "Or use the shorthand:
*workflow-init"). This pattern effectively teaches both approaches without confusion.docs/how-to/brownfield/index.md (1)
90-102: LGTM!The internal documentation links are well-structured with consistent relative paths. The Next Steps and Related Documentation sections provide clear navigation to related brownfield content.
website/src/styles/custom.css (2)
15-42: LGTM!The light mode color palette follows Starlight's naming conventions correctly. The CSS variable mapping from Docusaurus to Starlight is well-documented in the header comments, making future maintenance easier.
362-447: LGTM!The admonition (Starlight Aside) styling provides clear visual distinction between tip, note, caution, and danger states with appropriate color choices for both light and dark modes. The removal of the left border bar in favor of rounded corners with subtle backgrounds is a clean design choice.
package.json (2)
30-32: LGTM!The new Astro-based documentation scripts are correctly configured with the
--root websiteflag pointing to the site directory. The addition ofdocs:check-linksfor pre-build validation is a good practice.
88-92: No action needed. Starlight 0.37.0 requires Astro >= 5.5.0, and the specified version astro ^5.16.0 exceeds this requirement, confirming full compatibility.tools/build-docs.js (4)
42-65: LGTM!The main pipeline orchestration is clean with proper async/await handling and error logging before
process.exit(1). The pre-build link validation step is a good addition to catch issues early.
199-213: LGTM!Good resilient error handling pattern - individual file read failures are logged as warnings without aborting the entire build. This allows the pipeline to complete while still surfacing issues for investigation.
273-282: LGTM!The
validateLlmSizefunction correctly provides an error message before callingprocess.exit(1), and the warning threshold gives early notice before hitting the hard limit.
556-567: LGTM!The
checkDocLinksfunction correctly handles the external script failure with a clear error message beforeprocess.exit(1). Using an empty catch parameter (catch { }) is fine here since the error details come from the child process's stdio.
Replace Docusaurus with Astro and the Starlight documentation theme for improved performance, better customization, and modern tooling. Build pipeline changes: - New build-docs.js orchestrates link checking, artifact generation, and Astro build in sequence - Add check-doc-links.js for validating internal links and anchors - Generate llms.txt and llms-full.txt for LLM-friendly documentation - Create downloadable source bundles (bmad-sources.zip, bmad-prompts.zip) - Suppress MODULE_TYPELESS_PACKAGE_JSON warning in Astro build - Output directly to build/site for cleaner deployment Website architecture: - Add rehype-markdown-links.js plugin to transform .md links to routes - Add site-url.js helper for GitHub Pages URL resolution with strict validation (throws on invalid GITHUB_REPOSITORY format) - Custom Astro components: Banner, Header, MobileMenuFooter - Symlink docs/ into website/src/content/docs for Starlight Documentation cleanup: - Remove Docusaurus _category_.json files (Starlight uses frontmatter) - Convert all docs to use YAML frontmatter with title field - Move downloads.md from website/src/pages to docs/ - Consolidate style guide and workflow diagram docs - Add 404.md and tutorials/index.md
alexeyv
force-pushed
the
feat/diataxis-starlight
branch
from
bf77f0a to
6064903
Compare
3 participants
Summary
This PR combines two major documentation initiatives:
1. Diataxis Restructure (Force Trainer)
2. Astro/Starlight Migration (alexeyv)
3. Additional Fixes
Test Plan
npm test)Breaking Changes
🤖 Generated with Claude Code