Skip to content

Commit 930c211

Browse files
alexeyvclaude
alexeyv
and
claude
committed
refactor(docs): migrate from Docusaurus to Astro+Starlight
Complete documentation site migration with the following changes: - Migrate from Docusaurus to Astro + Starlight framework - Add AI agents banner with sticky positioning - Implement cascading site URL configuration for GitHub repo variable support - Add downloads page with header/mobile navigation links - Update theme colors to purple and fix banner/logo styling - Add internal link and anchor checker tooling - Transform markdown file links to page routes with rehype plugin - Remove duplicate h1 headings across documentation - Extract getSiteUrl to shared utility 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 0434cfe commit 930c211

File tree

110 files changed

+11893
-21983
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

110 files changed

+11893
-21983
lines changed

‎.github/workflows/docs.yaml‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -39,20 +39,11 @@ jobs:
3939
- name: Install dependencies
4040
run: npm ci
4141

42-
- name: Determine site URL
43-
id: site-url
44-
run: |
45-
if [ "${{ github.repository }}" = "bmad-code-org/BMAD-METHOD" ]; then
46-
echo "url=https://bmad-code-org.github.io/BMAD-METHOD" >> $GITHUB_OUTPUT
47-
else
48-
OWNER="${{ github.repository_owner }}"
49-
REPO="${{ github.event.repository.name }}"
50-
echo "url=https://${OWNER}.github.io/${REPO}" >> $GITHUB_OUTPUT
51-
fi
52-
5342
- name: Build documentation
5443
env:
55-
SITE_URL: ${{ steps.site-url.outputs.url }}
44+
# Override site URL from GitHub repo variable if set
45+
# Otherwise, astro.config.mjs will compute from GITHUB_REPOSITORY
46+
SITE_URL: ${{ vars.SITE_URL }}
5647
run: npm run docs:build
5748

5849
- name: Upload artifact

‎.gitignore‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ _bmad-output
7575

7676
bmad-custom-src/
7777

78-
# Docusaurus / Documentation Build
79-
.docusaurus/
78+
# Astro / Documentation Build
79+
website/.astro/
80+
website/dist/
8081
build/

‎docs/404.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Page Not Found
3+
template: splash
4+
---
5+
6+
7+
The page you're looking for doesn't exist or has been moved.
8+
9+
[Return to Home](/)

‎docs/_contributing/tutorial-style.md‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -50,22 +50,18 @@ Not all sections are required for every tutorial, but this is the standard flow.
5050

5151
## Admonitions
5252

53-
Use Docusaurus admonitions strategically:
53+
Use Starlight admonitions strategically:
5454

5555
```md
5656
:::tip[Title]
5757
Shortcuts, best practices, "pro tips"
5858
:::
5959

60-
:::info[Title]
60+
:::note[Title]
6161
Context, definitions, examples, prerequisites
6262
:::
6363

64-
:::note
65-
Supplementary information (can be collapsed)
66-
:::
67-
68-
:::warning[Title]
64+
:::caution[Title]
6965
Caveats, potential issues, things to watch out for
7066
:::
7167

@@ -78,10 +74,10 @@ Critical warnings only — data loss, security issues
7874

7975
| Admonition | Standard Use in Tutorials |
8076
|------------|---------------------------|
81-
| `:::info[Prerequisites]` | What users need before starting |
77+
| `:::note[Prerequisites]` | What users need before starting |
8278
| `:::tip[Quick Path]` | TL;DR summary at top of tutorial |
83-
| `:::warning[Fresh Chats]` | Context limitation reminders |
84-
| `:::info[Example]` | Command/response examples |
79+
| `:::caution[Fresh Chats]` | Context limitation reminders |
80+
| `:::note[Example]` | Command/response examples |
8581
| `:::tip[Check Your Status]` | How to verify progress |
8682
| `:::tip[Remember These]` | Key takeaways at end |
8783

@@ -128,7 +124,7 @@ Agent: [Response here]
128124
For command/response examples, use an admonition instead:
129125

130126
```md
131-
:::info[Example]
127+
:::note[Example]
132128
Run `workflow-status` and the agent will tell you the next recommended workflow.
133129
:::
134130
```
@@ -278,7 +274,7 @@ your-project/
278274

279275
Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.
280276

281-
:::info[What Happens]
277+
:::note[What Happens]
282278
You'll describe your project goals and complexity. The workflow then recommends a planning track.
283279
:::
284280
```

website/src/pages/downloads.md renamed to docs/downloads.md

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,38 @@
1-
# Downloads
1+
---
2+
title: Downloads
3+
---
24

35
Download BMAD Method resources for offline use, AI training, or integration.
46

7+
## Source Bundles
8+
9+
| File | Description |
10+
|------|-------------|
11+
| **[bmad-sources.zip](/downloads/bmad-sources.zip)** | Complete BMAD source files |
12+
| **[bmad-prompts.zip](/downloads/bmad-prompts.zip)** | Agent and workflow prompts only |
13+
514
## LLM-Optimized Files
615

716
These files are designed for AI consumption - perfect for loading into Claude, ChatGPT, or any LLM context window.
817

9-
| File | Description | Use Case |
10-
| ----------------------------------- | ----------------------------------- | -------------------------- |
11-
| **[llms.txt](/llms.txt)** | Documentation index with summaries | Quick overview, navigation |
12-
| **[llms-full.txt](/llms-full.txt)** | Complete documentation concatenated | Full context loading |
18+
| File | Description | Use Case |
19+
|------|-------------|----------|
20+
| **[llms.txt](/llms.txt)** | Documentation index with summaries | Quick overview, navigation |
21+
| **[llms-full.txt](/llms-full.txt)** | Complete documentation concatenated | Full context loading |
1322

1423
### Using with LLMs
1524

1625
**Claude Projects:**
17-
1826
```
1927
Upload llms-full.txt as project knowledge
2028
```
2129

2230
**ChatGPT:**
23-
2431
```
2532
Paste llms.txt for navigation, or sections from llms-full.txt as needed
2633
```
2734

2835
**API Usage:**
29-
3036
```python
3137
import requests
3238
docs = requests.get("https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt").text

‎docs/explanation/agents/barry-quick-flow.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Quick Flow Solo Dev Agent (Barry)
1+
---
2+
title: "Quick Flow Solo Dev Agent (Barry)"
3+
---
4+
25

36
**Agent ID:** `_bmad/bmm/agents/quick-flow-solo-dev.md`
47
**Icon:** 🚀

‎docs/explanation/agents/index.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
---
2-
sidebar_label: Agents
2+
title: "Understanding Agents"
33
description: Understanding BMAD agents and their roles
44
---
55

6-
# Understanding Agents
76

87
Comprehensive guides to BMAD's AI agents - their roles, capabilities, and how to work with them effectively.
98

‎docs/explanation/architecture/four-phases.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
---
2-
sidebar_label: Four Phases
2+
title: "The Four Phases of BMad Method"
33
description: Understanding the four phases of the BMad Method
44
---
55

6-
# The Four Phases of BMad Method
76

87
BMad Method uses a four-phase approach that adapts to project complexity while ensuring consistent quality.
98

‎docs/explanation/architecture/preventing-agent-conflicts.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
---
2-
sidebar_label: Preventing Agent Conflicts
2+
title: "Preventing Agent Conflicts"
33
description: How architecture prevents conflicts when multiple agents implement a system
44
---
55

6-
# Preventing Agent Conflicts
76

87
When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
98

‎docs/explanation/architecture/why-solutioning-matters.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
---
2-
sidebar_label: Why Solutioning Matters
2+
title: "Why Solutioning Matters"
33
description: Understanding why the solutioning phase is critical for multi-epic projects
44
---
55

6-
# Why Solutioning Matters
76

87
Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
98

0 commit comments

Comments
 (0)