Add link auditor, reorganize documentation, and README update #1277
Conversation
- Add audit-doc-links.js to scan docs for broken links with auto-resolution - Add fix-doc-links.js to apply suggested fixes (dry-run by default) - Remove stale "Back to Core Concepts" breadcrumb links - Update BMad acronym to "Breakthrough Method of Agile AI Driven Development" - Update README links to docs.bmad-method.org - Simplify upgrade callout in getting-started tutorial Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Remove unused section index files (tutorials, how-to, explanation, reference) - Move getting-started-bmadv4.md to _archive - Update quick-start-bmgd.md to remove archived file reference - Update upgrade-to-v6.md - Update astro.config.mjs for new structure Co-Authored-By: Claude Opus 4.5 <[email protected]>
Update check-doc-links.js to skip _archive, _planning, and other underscore-prefixed directories when validating links. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add links to v4 documentation archive and upgrade guide for users migrating from previous versions. Co-Authored-By: Claude Opus 4.5 <[email protected]>
📝 WalkthroughWalkthroughThis PR restructures the documentation from autogenerated flat indexes to a hierarchical Starlight sidebar navigation, removes and consolidates documentation index pages, updates tutorial content formatting, rewrites the README with streamlined branding, and introduces new tooling for auditing and fixing broken documentation links. Changes
Sequence Diagram(s)sequenceDiagram
participant FS as File System
participant Auditor as Link Auditor
participant Resolver as Path Resolver
participant Searcher as Moved File Searcher
participant Reporter as Report Generator
FS->>Auditor: Scan all .md/.mdx files
Auditor->>Auditor: Extract links from each file
Auditor->>Resolver: Resolve link to absolute path
Resolver-->>Auditor: File exists or not found
alt Link Not Found
Auditor->>Searcher: Search for moved file
Searcher->>FS: Glob pattern search
FS-->>Searcher: Potential matches
Searcher-->>Auditor: Single/multiple/no matches
Auditor->>Auditor: Classify as auto-fixable/needs-review/missing
end
Auditor->>Reporter: Aggregate findings
Reporter->>Reporter: Generate JSON report
Reporter->>FS: Write .link-audit-report.json
Reporter->>Reporter: Output console summary
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes Possibly related PRs
🚥 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: 3
🤖 Fix all issues with AI agents
In @docs/how-to/installation/upgrade-to-v6.md:
- Around line 2-8: The document title "Upgrading from Previous Versions" is too
generic for the file named upgrade-to-v6.md and the v4→v6-specific content;
either make the scope explicit by changing the title and heading to "BMad v4 to
v6 Upgrade Guide" (update the title string and any H1/H2 headings) so the
filename and content match, or convert this into a true generic upgrade guide by
renaming the file to upgrade-guide.md and broadening the content to cover
multiple version transitions; pick one approach and apply it consistently across
the title text and filename so search/findability and user expectations match.
In @README.md:
- Line 8: Clarify whether "21 specialized agents" and "12+ domain experts (PM,
Architect, Developer, UX, Scrum Master, and more)" are overlapping,
hierarchical, or separate categories: either update the README to explain the
relationship (e.g., "21 specialized agents, including 12+ domain experts such as
PM, Architect, Developer, UX, Scrum Master..." or "21 specialized agents (core
AI roles) plus 12+ human domain experts for oversight and strategy") or
reconcile the counts to avoid confusion by aligning the terminology and numbers
so both phrases consistently describe the same group.
In @tools/audit-doc-links.js:
- Around line 82-103: extractLinksWithPositions currently computes matches on
strippedContent (using LINK_PATTERN) but passes indexes into getLineNumber for
the stripped text, producing incorrect file line numbers when code blocks were
removed; fix by making the code translate match.index back to the original
content offset before calling getLineNumber (either update stripCodeBlocks to
return a mapping of removed-block ranges or offsets, or compute removed ranges
and add their cumulative length back to the match.index), then call
getLineNumber(originalContent, translatedIndex) so reported line numbers reflect
the original file; update references in extractLinksWithPositions (and keep
shouldIgnoreLink checks and fullMatch extraction unchanged).
🧹 Nitpick comments (4)
tools/fix-doc-links.js (1)
102-107: Consider validating the report structure.If the audit report is malformed or manually edited, accessing
report.autoFixable.lengthon undefined will throw a TypeError with an unhelpful message. A simple validation would improve error messaging.♻️ Suggested fix
const report = loadReport(); + if (!Array.isArray(report.autoFixable)) { + console.error(`\n ${colors.red}Error:${colors.reset} Invalid report format - missing autoFixable array.\n`); + process.exit(1); + } + if (report.autoFixable.length === 0) { console.log(` ${colors.green}✓${colors.reset} No auto-fixable links found.\n`); process.exit(0); }tools/audit-doc-links.js (3)
210-214: Consider wrapping file read in try/catch.While unlikely, a file could be deleted between the glob scan and this read. The global error handler would catch it, but the error message wouldn't indicate which file failed.
♻️ Suggested fix
for (const file of files) { - const content = readFileSync(file, 'utf-8'); + let content; + try { + content = readFileSync(file, 'utf-8'); + } catch (error) { + console.warn(` ${colors.yellow}⚠${colors.reset} Skipping unreadable file: ${relative(DOCS_DIR, file)}`); + continue; + } const links = extractLinksWithPositions(content, file);
209-210: Unused variableallFiles.This variable is declared but never used. Consider removing it.
225-229: Unused variablefileName.The
fileNamevariable is declared but never used.// Check if target exists if (!existsSync(targetFile)) { // Try to find the file elsewhere const candidates = await findMovedFile(linkPath);
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (16)
README.mddocs/_archive/getting-started-bmadv4.mddocs/explanation/features/web-bundles.mddocs/explanation/index.mddocs/how-to/customization/index.mddocs/how-to/index.mddocs/how-to/installation/upgrade-to-v6.mddocs/index.mddocs/reference/index.mddocs/tutorials/getting-started/getting-started-bmadv6.mddocs/tutorials/getting-started/quick-start-bmgd.mddocs/tutorials/index.mdtools/audit-doc-links.jstools/check-doc-links.jstools/fix-doc-links.jswebsite/astro.config.mjs
💤 Files with no reviewable changes (6)
- docs/how-to/customization/index.md
- docs/explanation/features/web-bundles.md
- docs/tutorials/index.md
- docs/explanation/index.md
- docs/how-to/index.md
- docs/reference/index.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:
tools/fix-doc-links.jsREADME.mdwebsite/astro.config.mjstools/check-doc-links.jstools/audit-doc-links.jsdocs/index.mddocs/how-to/installation/upgrade-to-v6.mddocs/tutorials/getting-started/quick-start-bmgd.mddocs/tutorials/getting-started/getting-started-bmadv6.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/fix-doc-links.jstools/check-doc-links.jstools/audit-doc-links.js
🧬 Code graph analysis (3)
tools/fix-doc-links.js (2)
tools/audit-doc-links.js (5)
require(13-13)require(14-14)require(15-15)REPORT_PATH(18-18)report(265-277)website/src/rehype-markdown-links.js (3)
node(24-86)tree(23-87)rehypeMarkdownLinks(22-88)
tools/audit-doc-links.js (1)
tools/fix-doc-links.js (6)
require(12-12)require(13-13)REPORT_PATH(15-15)content(38-38)content(51-51)report(102-102)
docs/index.md (1)
tools/build-docs.js (1)
main(42-60)
🔇 Additional comments (8)
website/astro.config.mjs (1)
85-199: All referenced directories exist and are properly configured.The sidebar configuration correctly references all directories:
- Tutorials:
getting-startedandadvanceddirectories exist- How-To: All five subdirectories (
installation,workflows,customization,brownfield,troubleshooting) exist, and the slug fileget-answers-about-bmad.mdis present- Explanation: All eleven subdirectories exist
- Reference: All four subdirectories exist
The mixed approach in the How-To section (combining the direct slug reference on line 105 with autogenerate subdirectories) is intentional and working correctly. Section index files have been properly removed as referenced in the PR objectives.
README.md (2)
49-58: Verify documentation links are accessible.The documentation links reference
docs.bmad-method.orgas the primary documentation site. Ensure that:
- The full documentation URL (line 51) is properly configured and publicly accessible
- The specific tutorial and upgrade guide links (lines 53-54) resolve correctly
- The v4 documentation reference (line 58) to the V4 branch remains stable
This aligns with the PR objective to update links to the new documentation site, but verification is important for user experience.
1-79: README structure and branding align well with PR objectives.The rewrite successfully streamlines the documentation experience by:
- Consolidating module descriptions into a clear, scannable table (Modules section)
- Providing a concise quick-start workflow with track selection guidance
- Removing historical context and v4/v6 migration narratives
- Unifying branding around BMAD terminology throughout
The structure prioritizes getting started and documentation discovery, which is consistent with the broader documentation reorganization goals. Overall presentation is clear and developer-friendly.
tools/check-doc-links.js (1)
199-203: LGTM!The ignore pattern correctly excludes underscore-prefixed directories from scanning. This aligns well with the documentation reorganization that archives content under
_archiveand keeps planning docs under_planning.tools/fix-doc-links.js (2)
30-45: LGTM!Good error handling with existence check before reading and try/catch around JSON parsing with informative error messages.
50-76: LGTM!The function correctly handles anchor preservation and uses proper regex escaping. The caller wraps this in try/catch for I/O error handling.
tools/audit-doc-links.js (2)
137-170: LGTM!Good multi-strategy approach to finding moved files with appropriate handling for the generic
index.mdcase.
20-21: Reference-style links are not supported, but none exist in the documentation.The
LINK_PATTERNregex only matches inline[text](path)links, unlikecheck-doc-links.jswhich supports both inline and reference-style[text]: pathformats. However, no reference-style links are present in the docs, so this difference has no practical impact.
| title: "Upgrading from Previous Versions" | ||
| --- | ||
|
|
||
|
|
||
| ## Overview | ||
|
|
||
| BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6. | ||
| The latest version of BMad represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate from version 4. |
There was a problem hiding this comment.
Title and content scope mismatch.
The title "Upgrading from Previous Versions" suggests a generic upgrade guide, but the filename (upgrade-to-v6.md) and all content are specifically about migrating from v4 to v6. This inconsistency could confuse users:
- Users upgrading from future versions (e.g., v7→v8) might expect this guide to help them
- The generic title doesn't align with the specific filename, creating a findability problem
- Search results and links may mislead users about the document's scope
Consider either:
- Keeping the specific title: "BMad v4 to v6 Upgrade Guide"
- Or renaming the file to match the generic scope:
upgrade-guide.mdand restructuring content to handle multiple version transitions
🤖 Prompt for AI Agents
In @docs/how-to/installation/upgrade-to-v6.md around lines 2 - 8, The document
title "Upgrading from Previous Versions" is too generic for the file named
upgrade-to-v6.md and the v4→v6-specific content; either make the scope explicit
by changing the title and heading to "BMad v4 to v6 Upgrade Guide" (update the
title string and any H1/H2 headings) so the filename and content match, or
convert this into a true generic upgrade guide by renaming the file to
upgrade-guide.md and broadening the content to cover multiple version
transitions; pick one approach and apply it consistently across the title text
and filename so search/findability and user expectations match.
| **Build More, Architect Dreams** (BMAD) with **21 specialized AI agents** across 4 official modules, and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms, and new step file workflows that allow for incredibly long workflows to stay on the rails longer than ever before! | ||
|
|
||
| Additionally - when we say 'Build More, Architect Dreams' - we mean it! The BMad Builder has landed, and now as of Alpha.15 is fully supported in the installation flow via NPX - custom stand along agents, workflows and the modules of your dreams! The community forge will soon open, endless possibility awaits! | ||
| **Build More, Architect Dreams** — An AI-driven agile development framework with 21 specialized agents, 50+ guided workflows, and scale-adaptive intelligence that adjusts from bug fixes to enterprise systems. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
head -80 README.md | cat -nRepository: bmad-code-org/BMAD-METHOD
Length of output: 4226
Clarify the distinction between "21 specialized agents" and "12+ domain experts".
Line 8 mentions "21 specialized agents" while line 16 states "12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)". These numbers and terminology may refer to different concept groups, but the distinction is unclear to readers. Either clarify the relationship between these two categories or align the numbers and terminology.
🤖 Prompt for AI Agents
In @README.md at line 8, Clarify whether "21 specialized agents" and "12+ domain
experts (PM, Architect, Developer, UX, Scrum Master, and more)" are overlapping,
hierarchical, or separate categories: either update the README to explain the
relationship (e.g., "21 specialized agents, including 12+ domain experts such as
PM, Architect, Developer, UX, Scrum Master..." or "21 specialized agents (core
AI roles) plus 12+ human domain experts for oversight and strategy") or
reconcile the counts to avoid confusion by aligning the terminology and numbers
so both phrases consistently describe the same group.
tools/audit-doc-links.js
Outdated
| function extractLinksWithPositions(content, filePath) { | ||
| const strippedContent = stripCodeBlocks(content); | ||
| const links = []; | ||
|
|
||
| let match; | ||
| LINK_PATTERN.lastIndex = 0; | ||
|
|
||
| while ((match = LINK_PATTERN.exec(strippedContent)) !== null) { | ||
| const rawLink = match[2]; | ||
| if (!shouldIgnoreLink(rawLink)) { | ||
| const lineNumber = getLineNumber(strippedContent, match.index); | ||
| links.push({ | ||
| raw: rawLink, | ||
| text: match[1], | ||
| line: lineNumber, | ||
| fullMatch: match[0], | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| return links; | ||
| } |
There was a problem hiding this comment.
Line numbers may be inaccurate due to code block stripping.
getLineNumber operates on strippedContent (after code blocks are removed), not the original content. This means reported line numbers won't match actual file positions when code blocks precede the link.
Consider calculating line numbers from the original content using the match position adjusted for removed blocks, or document this limitation.
🤖 Prompt for AI Agents
In @tools/audit-doc-links.js around lines 82 - 103, extractLinksWithPositions
currently computes matches on strippedContent (using LINK_PATTERN) but passes
indexes into getLineNumber for the stripped text, producing incorrect file line
numbers when code blocks were removed; fix by making the code translate
match.index back to the original content offset before calling getLineNumber
(either update stripCodeBlocks to return a mapping of removed-block ranges or
offsets, or compute removed ranges and add their cumulative length back to the
match.index), then call getLineNumber(originalContent, translatedIndex) so
reported line numbers reflect the original file; update references in
extractLinksWithPositions (and keep shouldIgnoreLink checks and fullMatch
extraction unchanged).
- Convert all relative links (./ ../) to site-relative paths (/path/) - Strip .md extensions and use trailing slashes for Astro/Starlight - Add fix-doc-links.js to convert relative links to site-relative - Add validate-doc-links.js to check links point to existing files - Remove old audit-doc-links.js and check-doc-links.js - Update build-docs.js to use new validation script - Add npm scripts: docs:fix-links, docs:validate-links - Update style guide with validation steps Co-Authored-By: Claude Opus 4.5 <[email protected]>
Replace incorrect "BMAD" with correct "BMad" in text and frontmatter while preserving "BMAD-METHOD" in GitHub URLs. Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Correct acronym to "Breakthrough Method of Agile AI Driven Development" - Remove unused README-draft.md Co-Authored-By: Claude Opus 4.5 <[email protected]>
Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Add TOC with jump links under "## Questions" - Use ### headers for questions (no Q: prefix) - Direct answers without **A:** prefix - Remove horizontal rules and "Related Documentation" sections - End each FAQ with issue/Discord CTA - Update style guide with new FAQ guidelines - Delete redundant faq/index.md (sidebar handles navigation) Co-Authored-By: Claude Opus 4.5 <[email protected]>
Convert all documentation links to repo-relative format (/docs/path/file.md) so they work when browsing on GitHub. The rehype plugin strips /docs/ prefix and converts .md to trailing slash at build time for Astro/Starlight. - Update rehype-markdown-links.js to strip /docs/ prefix from absolute paths - Update fix-doc-links.js to generate /docs/ prefixed paths with .md extension - Convert 217 links across 64 files to new format Co-Authored-By: Claude Opus 4.5 <[email protected]>
Update resolveLink to strip /docs/ prefix from repo-relative links before checking if files exist. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Re-add the FAQ index page that was accidentally deleted, with updated repo-relative link format. Co-Authored-By: Claude Opus 4.5 <[email protected]>
3 participants
Summary
check-doc-links.jsand replaced with 'validate-doc-links.js' to ensure links are valid before build can complete.Test plan
npm run docs:fix-linksfixes any relative pathsnpm run docs:buildpasses locally