Describe your idea
Add a version selector to the docs site (docs.bmad-method.org) so users can browse documentation matching their installed release, rather than always seeing the latest main branch.
Why is this needed?
The docs site currently always reflects main, which can diverge from the latest release tag. For example, in v6.2.2 the tutorial references bmad-agent-sm (the Scrum Master agent / Bob), but the live docs no longer mention it since that agent was removed on main. Users on a tagged release may be confused when the docs don't match what they have installed.
The default view should reflect the latest release tag — since that's what most users install — with the option to switch to older versions or main for those tracking unreleased changes.
How should it work?
A version dropdown in the site header with options like:
- Latest release (default, e.g.
6.2.2)
- Specific older releases (e.g.
6.1.0, etc.)
- Main (current
main branch)
Possible implementation approaches:
starlight-versions community plugin — adds a version dropdown with minimal config- Static archived snapshots — deploy versioned docs to paths like
/v6.2.2/ with a manual dropdown
- Version banner — simpler option: show a "you are viewing docs for vX.Y.Z" banner with a link to the changelog
PR
Not currently working on this, but happy to discuss.
Additional context
The site uses @astrojs/starlight, which does not have built-in versioning. The project version is tracked in package.json and could be used to automate version tagging on release.
Describe your idea
Add a version selector to the docs site (docs.bmad-method.org) so users can browse documentation matching their installed release, rather than always seeing the latest
mainbranch.Why is this needed?
The docs site currently always reflects
main, which can diverge from the latest release tag. For example, in v6.2.2 the tutorial referencesbmad-agent-sm(the Scrum Master agent / Bob), but the live docs no longer mention it since that agent was removed onmain. Users on a tagged release may be confused when the docs don't match what they have installed.The default view should reflect the latest release tag — since that's what most users install — with the option to switch to older versions or
mainfor those tracking unreleased changes.How should it work?
A version dropdown in the site header with options like:
6.2.2)6.1.0, etc.)mainbranch)Possible implementation approaches:
starlight-versionscommunity plugin — adds a version dropdown with minimal config/v6.2.2/with a manual dropdownPR
Not currently working on this, but happy to discuss.
Additional context
The site uses
@astrojs/starlight, which does not have built-in versioning. The project version is tracked inpackage.jsonand could be used to automate version tagging on release.