diff --git a/docs/404.md b/docs/404.md index 11b7c223..b42841e9 100644 --- a/docs/404.md +++ b/docs/404.md @@ -6,4 +6,4 @@ template: splash The page you're looking for doesn't exist or has been moved. -[Return to Home](/) +[Return to Home](/docs/index.md) diff --git a/docs/explanation/agents/barry-quick-flow.md b/docs/explanation/agents/barry-quick-flow.md index c2427f00..11ffd0ea 100644 --- a/docs/explanation/agents/barry-quick-flow.md +++ b/docs/explanation/agents/barry-quick-flow.md @@ -310,11 +310,11 @@ Implement OAuth 2.0 authentication with JWT tokens and role-based access control ## Related Documentation -- **[Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/)** - Getting started with BMM -- **[Agents Guide](/explanation/core-concepts/agent-roles/)** - Complete agent reference -- **[Four Phases](/explanation/architecture/four-phases/)** - Understanding development tracks -- **[Workflow Implementation](/how-to/workflows/run-sprint-planning/)** - Implementation workflows -- **[Party Mode](/explanation/features/party-mode/)** - Multi-agent collaboration +- **[Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md)** - Getting started with BMM +- **[Agents Guide](/docs/explanation/core-concepts/agent-roles.md)** - Complete agent reference +- **[Four Phases](/docs/explanation/architecture/four-phases.md)** - Understanding development tracks +- **[Workflow Implementation](/docs/how-to/workflows/run-sprint-planning.md)** - Implementation workflows +- **[Party Mode](/docs/explanation/features/party-mode.md)** - Multi-agent collaboration --- diff --git a/docs/explanation/agents/index.md b/docs/explanation/agents/index.md index 3adda807..ff47b035 100644 --- a/docs/explanation/agents/index.md +++ b/docs/explanation/agents/index.md @@ -12,17 +12,17 @@ Comprehensive guides to BMad's AI agents - their roles, capabilities, and how to ### BMM Agents -- **[Agent Roles](/explanation/core-concepts/agent-roles/)** - Overview of all BMM agent roles and responsibilities -- **[Quick Flow Solo Dev (Barry)](/explanation/agents/barry-quick-flow/)** - The dedicated agent for rapid development +- **[Agent Roles](/docs/explanation/core-concepts/agent-roles.md)** - Overview of all BMM agent roles and responsibilities +- **[Quick Flow Solo Dev (Barry)](/docs/explanation/agents/barry-quick-flow.md)** - The dedicated agent for rapid development ### BMGD Agents -- **[Game Development Agents](/explanation/game-dev/agents/)** - Complete guide to BMGD's specialized game dev agents +- **[Game Development Agents](/docs/explanation/game-dev/agents.md)** - Complete guide to BMGD's specialized game dev agents --- ## Related -- **[What Are Agents?](/explanation/core-concepts/what-are-agents/)** - Core concept explanation -- **[Party Mode](/explanation/features/party-mode/)** - Multi-agent collaboration -- **[Customize Agents](/how-to/customization/customize-agents/)** - How to customize agent behavior +- **[What Are Agents?](/docs/explanation/core-concepts/what-are-agents.md)** - Core concept explanation +- **[Party Mode](/docs/explanation/features/party-mode.md)** - Multi-agent collaboration +- **[Customize Agents](/docs/how-to/customization/customize-agents.md)** - How to customize agent behavior diff --git a/docs/explanation/architecture/four-phases.md b/docs/explanation/architecture/four-phases.md index 7692f6ed..83538b9f 100644 --- a/docs/explanation/architecture/four-phases.md +++ b/docs/explanation/architecture/four-phases.md @@ -121,6 +121,6 @@ Same as BMad Method with optional extended workflows. ## Related -- [Why Solutioning Matters](/explanation/architecture/why-solutioning-matters/) -- [Preventing Agent Conflicts](/explanation/architecture/preventing-agent-conflicts/) -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) +- [Why Solutioning Matters](/docs/explanation/architecture/why-solutioning-matters.md) +- [Preventing Agent Conflicts](/docs/explanation/architecture/preventing-agent-conflicts.md) +- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) diff --git a/docs/explanation/architecture/preventing-agent-conflicts.md b/docs/explanation/architecture/preventing-agent-conflicts.md index 708bacac..6d0f7563 100644 --- a/docs/explanation/architecture/preventing-agent-conflicts.md +++ b/docs/explanation/architecture/preventing-agent-conflicts.md @@ -133,6 +133,6 @@ Document written once, never updated ## Related -- [Why Solutioning Matters](/explanation/architecture/why-solutioning-matters/) -- [Four Phases](/explanation/architecture/four-phases/) -- [Create Architecture](/how-to/workflows/create-architecture/) +- [Why Solutioning Matters](/docs/explanation/architecture/why-solutioning-matters.md) +- [Four Phases](/docs/explanation/architecture/four-phases.md) +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) diff --git a/docs/explanation/architecture/why-solutioning-matters.md b/docs/explanation/architecture/why-solutioning-matters.md index af894c73..d10f76d2 100644 --- a/docs/explanation/architecture/why-solutioning-matters.md +++ b/docs/explanation/architecture/why-solutioning-matters.md @@ -86,6 +86,6 @@ Catching alignment issues in solutioning is 10Γ— faster than discovering them du ## Related -- [Four Phases](/explanation/architecture/four-phases/) - Overview of all phases -- [Preventing Agent Conflicts](/explanation/architecture/preventing-agent-conflicts/) - Detailed conflict prevention -- [Create Architecture](/how-to/workflows/create-architecture/) - How to do it +- [Four Phases](/docs/explanation/architecture/four-phases.md) - Overview of all phases +- [Preventing Agent Conflicts](/docs/explanation/architecture/preventing-agent-conflicts.md) - Detailed conflict prevention +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - How to do it diff --git a/docs/explanation/bmad-builder/custom-content-types.md b/docs/explanation/bmad-builder/custom-content-types.md index 54f01e88..d593d50b 100644 --- a/docs/explanation/bmad-builder/custom-content-types.md +++ b/docs/explanation/bmad-builder/custom-content-types.md @@ -27,7 +27,7 @@ This flexibility transforms the platform beyond its current capabilities, enabli Custom modules range from simple collections of related agents, workflows, and tools designed to work independently, to complex, expansive systems like the BMad Method or even larger applications. -Custom modules are [installable](/how-to/installation/install-custom-modules/) using the standard BMad method and support advanced features: +Custom modules are [installable](/docs/how-to/installation/install-custom-modules.md) using the standard BMad method and support advanced features: - Optional user information collection during installation/updates - Versioning and upgrade paths diff --git a/docs/explanation/bmad-builder/index.md b/docs/explanation/bmad-builder/index.md index 557db42a..b1d0f39f 100644 --- a/docs/explanation/bmad-builder/index.md +++ b/docs/explanation/bmad-builder/index.md @@ -10,7 +10,7 @@ Create custom agents, workflows, and modules for BMad. ## Quick Start -- **[Agent Creation Guide](/tutorials/advanced/create-custom-agent/)** - Step-by-step guide to building your first agent +- **[Agent Creation Guide](/docs/tutorials/advanced/create-custom-agent.md)** - Step-by-step guide to building your first agent --- @@ -56,11 +56,11 @@ Production-ready examples available in the BMB reference folder: ## Installation Guide For installing standalone simple and expert agents, see: -- [Install Custom Modules](/how-to/installation/install-custom-modules/) +- [Install Custom Modules](/docs/how-to/installation/install-custom-modules.md) --- ## Related -- [Custom Content Types](/explanation/bmad-builder/custom-content-types/) - Understanding content types -- [Create Custom Agent](/tutorials/advanced/create-custom-agent/) - Tutorial +- [Custom Content Types](/docs/explanation/bmad-builder/custom-content-types.md) - Understanding content types +- [Create Custom Agent](/docs/tutorials/advanced/create-custom-agent.md) - Tutorial diff --git a/docs/explanation/bmm/index.md b/docs/explanation/bmm/index.md index 37dad17b..29e0cd21 100644 --- a/docs/explanation/bmm/index.md +++ b/docs/explanation/bmm/index.md @@ -11,7 +11,7 @@ Complete guides for the BMad Method Module (BMM) - AI-powered agile development **New to BMM?** Start here: -- **[Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/)** - Step-by-step guide to building your first project +- **[Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md)** - Step-by-step guide to building your first project - Installation and setup - Understanding the four phases - Running your first workflows @@ -36,26 +36,26 @@ First know there is the full BMad Method Process and then there is a Quick Flow - All 4 phases have optional steps in them, depending on how rigorous you want to go with planning, research ideation, validation, testing and traceability. - While there is a lot here, know that even this can be distilled down to a simple PRD, Epic and Story list and then jump into the dev cycle. But if that is all you want, you might be better off with the BMad Quick Flow described next -- **[BMad Quick Flow](/explanation/features/quick-flow/)** - Fast-track development workflow +- **[BMad Quick Flow](/docs/explanation/features/quick-flow.md)** - Fast-track development workflow - 3-step process: spec β†’ dev β†’ optional review - Perfect for bug fixes and small features - Rapid prototyping with production quality - Implementation in minutes, not days - - Has a specialized single agent that does all of this: **[Quick Flow Solo Dev Agent](/explanation/agents/barry-quick-flow/)** + - Has a specialized single agent that does all of this: **[Quick Flow Solo Dev Agent](/docs/explanation/agents/barry-quick-flow.md)** -- **TEA engagement (optional)** - Choose TEA engagement: none, TEA-only (standalone), or integrated by track. See **[Test Architect Guide](/explanation/features/tea-overview/)**. +- **TEA engagement (optional)** - Choose TEA engagement: none, TEA-only (standalone), or integrated by track. See **[Test Architect Guide](/docs/explanation/features/tea-overview.md)**. ## πŸ€– Agents and Collaboration Complete guide to BMM's AI agent team: -- **[Agents Guide](/explanation/core-concepts/agent-roles/)** - Comprehensive agent reference +- **[Agents Guide](/docs/explanation/core-concepts/agent-roles.md)** - Comprehensive agent reference - 12 specialized BMM agents + BMad Master - Agent roles, workflows, and when to use them - Agent customization system - Best practices and common patterns -- **[Party Mode Guide](/explanation/features/party-mode/)** - Multi-agent collaboration +- **[Party Mode Guide](/docs/explanation/features/party-mode.md)** - Multi-agent collaboration - How party mode works (19+ agents collaborate in real-time) - When to use it (strategic, creative, cross-functional, complex) - Example party compositions @@ -67,7 +67,7 @@ Complete guide to BMM's AI agent team: Comprehensive guide for brownfield development: -- **[Brownfield Development Guide](/how-to/brownfield/)** - Complete guide for existing codebases +- **[Brownfield Development Guide](/docs/how-to/brownfield/index.md)** - Complete guide for existing codebases - Documentation phase strategies - Track selection for brownfield - Integration with existing patterns @@ -78,49 +78,49 @@ Comprehensive guide for brownfield development: Essential reference materials: -- **[Glossary](/reference/glossary/)** - Key terminology and concepts -- **[FAQ](/explanation/faq/)** - Frequently asked questions across all topics +- **[Glossary](/docs/reference/glossary/index.md)** - Key terminology and concepts +- **[FAQ](/docs/explanation/faq/index.md)** - Frequently asked questions across all topics ## 🎯 Choose Your Path ### I need to... **Build something new (greenfield)** -β†’ Start with [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) +β†’ Start with [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) **Fix a bug or add small feature** -β†’ Use the [Quick Flow Solo Dev](/explanation/agents/barry-quick-flow/) directly with its dedicated stand alone [Quick Bmad Spec Flow](/explanation/features/quick-flow/) process +β†’ Use the [Quick Flow Solo Dev](/docs/explanation/agents/barry-quick-flow.md) directly with its dedicated stand alone [Quick Bmad Spec Flow](/docs/explanation/features/quick-flow.md) process **Work with existing codebase (brownfield)** -β†’ Read [Brownfield Development Guide](/how-to/brownfield/) +β†’ Read [Brownfield Development Guide](/docs/how-to/brownfield/index.md) β†’ Pay special attention to documentation requirements for brownfield projects ## πŸ“‹ Workflow Guides Comprehensive documentation for all BMM workflows organized by phase: -- **[Phase 1: Analysis Workflows](/how-to/workflows/run-brainstorming-session/)** - Optional exploration and research workflows (595 lines) +- **[Phase 1: Analysis Workflows](/docs/how-to/workflows/run-brainstorming-session.md)** - Optional exploration and research workflows (595 lines) - brainstorm-project, product-brief, research, and more - When to use analysis workflows - Creative and strategic tools -- **[Phase 2: Planning Workflows](/how-to/workflows/create-prd/)** - Scale-adaptive planning (967 lines) +- **[Phase 2: Planning Workflows](/docs/how-to/workflows/create-prd.md)** - Scale-adaptive planning (967 lines) - prd, tech-spec, gdd, narrative, ux - Track-based planning approach (Quick Flow, BMad Method, Enterprise Method) - Which planning workflow to use -- **[Phase 3: Solutioning Workflows](/how-to/workflows/create-architecture/)** - Architecture and validation (638 lines) +- **[Phase 3: Solutioning Workflows](/docs/how-to/workflows/create-architecture.md)** - Architecture and validation (638 lines) - architecture, create-epics-and-stories, implementation-readiness - V6: Epics created AFTER architecture for better quality - Required for BMad Method and Enterprise Method tracks - Preventing agent conflicts -- **[Phase 4: Implementation Workflows](/how-to/workflows/run-sprint-planning/)** - Sprint-based development (1,634 lines) +- **[Phase 4: Implementation Workflows](/docs/how-to/workflows/run-sprint-planning.md)** - Sprint-based development (1,634 lines) - sprint-planning, create-story, dev-story, code-review - Complete story lifecycle - One-story-at-a-time discipline -- **[Testing & QA Workflows](/explanation/features/tea-overview/)** - Comprehensive quality assurance (1,420 lines) +- **[Testing & QA Workflows](/docs/explanation/features/tea-overview.md)** - Comprehensive quality assurance (1,420 lines) - Test strategy, automation, quality gates - TEA agent and test healing @@ -132,4 +132,4 @@ Comprehensive documentation for all BMM workflows organized by phase: - **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features - **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and walkthroughs -**Ready to begin?** β†’ [Start with the Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) +**Ready to begin?** β†’ [Start with the Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) diff --git a/docs/explanation/core-concepts/agent-roles.md b/docs/explanation/core-concepts/agent-roles.md index 9f46ea43..f9717ac4 100644 --- a/docs/explanation/core-concepts/agent-roles.md +++ b/docs/explanation/core-concepts/agent-roles.md @@ -199,6 +199,6 @@ Fast solo development without handoffs. ## Related -- [What Are Agents](/explanation/core-concepts/what-are-agents/) - Foundational concepts -- [Agent Reference](/reference/agents/) - Complete command reference -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) +- [What Are Agents](/docs/explanation/core-concepts/what-are-agents.md) - Foundational concepts +- [Agent Reference](/docs/reference/agents/index.md) - Complete command reference +- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) diff --git a/docs/explanation/core-concepts/index.md b/docs/explanation/core-concepts/index.md index 2dc09b4c..ef03bbd2 100644 --- a/docs/explanation/core-concepts/index.md +++ b/docs/explanation/core-concepts/index.md @@ -9,32 +9,32 @@ Understanding the fundamental building blocks of the BMad Method. | Concept | Description | Guide | |---------|-------------|-------| -| **Agents** | AI assistants with personas, capabilities, and menus | [Agents Guide](/explanation/core-concepts/what-are-agents/) | -| **Workflows** | Structured processes for achieving specific outcomes | [Workflows Guide](/explanation/core-concepts/what-are-workflows/) | -| **Modules** | Packaged collections of agents and workflows | [Modules Guide](/explanation/core-concepts/what-are-modules/) | +| **Agents** | AI assistants with personas, capabilities, and menus | [Agents Guide](/docs/explanation/core-concepts/what-are-agents.md) | +| **Workflows** | Structured processes for achieving specific outcomes | [Workflows Guide](/docs/explanation/core-concepts/what-are-workflows.md) | +| **Modules** | Packaged collections of agents and workflows | [Modules Guide](/docs/explanation/core-concepts/what-are-modules.md) | ## Getting Started ### New to BMad? Start here to understand what BMad is and how it works: -1. **[Agents Guide](/explanation/core-concepts/what-are-agents/)** - Learn about Simple and Expert agents -2. **[Workflows Guide](/explanation/core-concepts/what-are-workflows/)** - Understand how workflows orchestrate tasks -3. **[Modules Guide](/explanation/core-concepts/what-are-modules/)** - See how modules organize functionality +1. **[Agents Guide](/docs/explanation/core-concepts/what-are-agents.md)** - Learn about Simple and Expert agents +2. **[Workflows Guide](/docs/explanation/core-concepts/what-are-workflows.md)** - Understand how workflows orchestrate tasks +3. **[Modules Guide](/docs/explanation/core-concepts/what-are-modules.md)** - See how modules organize functionality ### Installing BMad -- **[Installation Guide](/how-to/installation/)** - Set up BMad in your project -- **[Upgrading from v4](/how-to/installation/upgrade-to-v6/)** - Migrate from earlier versions +- **[Installation Guide](/docs/how-to/installation/index.md)** - Set up BMad in your project +- **[Upgrading from v4](/docs/how-to/installation/upgrade-to-v6.md)** - Migrate from earlier versions ### Configuration -- **[BMad Customization](/how-to/customization/)** - Personalize agents and workflows +- **[BMad Customization](/docs/how-to/customization/index.md)** - Personalize agents and workflows ### Advanced -- **[Web Bundles](/explanation/features/web-bundles/)** - Use BMad in Gemini Gems and Custom GPTs +- **[Web Bundles](/docs/explanation/features/web-bundles.md)** - Use BMad in Gemini Gems and Custom GPTs --- -**Next:** Read the [Agents Guide](/explanation/core-concepts/what-are-agents/) to understand the core building block of BMad. +**Next:** Read the [Agents Guide](/docs/explanation/core-concepts/what-are-agents.md) to understand the core building block of BMad. diff --git a/docs/explanation/core-concepts/what-are-agents.md b/docs/explanation/core-concepts/what-are-agents.md index 7b79dd8c..1f3169b1 100644 --- a/docs/explanation/core-concepts/what-are-agents.md +++ b/docs/explanation/core-concepts/what-are-agents.md @@ -85,12 +85,12 @@ All agents share these building blocks: ## Creating Custom Agents -BMad provides the **BMad Builder (BMB)** module for creating your own agents. See the [Agent Creation Guide](/tutorials/advanced/create-custom-agent/) for step-by-step instructions. +BMad provides the **BMad Builder (BMB)** module for creating your own agents. See the [Agent Creation Guide](/docs/tutorials/advanced/create-custom-agent.md) for step-by-step instructions. ## Customizing Existing Agents -You can modify any agent's behavior without editing core files. See [BMad Customization](/how-to/customization/) for details. It is critical to never modify an installed agents .md file directly and follow the customization process, this way future updates to the agent or module its part of will continue to be updated and recompiled with the installer tool, and your customizations will still be retained. +You can modify any agent's behavior without editing core files. See [BMad Customization](/docs/how-to/customization/index.md) for details. It is critical to never modify an installed agents .md file directly and follow the customization process, this way future updates to the agent or module its part of will continue to be updated and recompiled with the installer tool, and your customizations will still be retained. --- -**Next:** Learn about [Workflows](/explanation/core-concepts/what-are-workflows/) to see how agents accomplish complex tasks. +**Next:** Learn about [Workflows](/docs/explanation/core-concepts/what-are-workflows.md) to see how agents accomplish complex tasks. diff --git a/docs/explanation/core-concepts/what-are-modules.md b/docs/explanation/core-concepts/what-are-modules.md index f4083bb5..3d6ae383 100644 --- a/docs/explanation/core-concepts/what-are-modules.md +++ b/docs/explanation/core-concepts/what-are-modules.md @@ -72,8 +72,8 @@ Custom modules are installed the same way as official modules. During BMad installation, you choose which modules to install. You can also add or remove modules later by re-running the installer. -See [Installation Guide](/how-to/installation/) for details. +See [Installation Guide](/docs/how-to/installation/index.md) for details. --- -**Next:** Read the [Installation Guide](/how-to/installation/) to set up BMad with the modules you need. +**Next:** Read the [Installation Guide](/docs/how-to/installation/index.md) to set up BMad with the modules you need. diff --git a/docs/explanation/core/index.md b/docs/explanation/core/index.md index 5dd85d43..de7687dc 100644 --- a/docs/explanation/core/index.md +++ b/docs/explanation/core/index.md @@ -7,12 +7,12 @@ The Core Module is installed with all installations of BMad modules and provides ## Core Module Components -- **[Global Core Config](/reference/configuration/global-config/)** β€” Inheritable configuration that impacts all modules and custom content -- **[Core Workflows](/reference/workflows/core-workflows/)** β€” Domain-agnostic workflows usable by any module - - [Party Mode](/explanation/features/party-mode/) β€” Multi-agent conversation orchestration - - [Brainstorming](/explanation/features/brainstorming-techniques/) β€” Structured creative sessions with 60+ techniques - - [Advanced Elicitation](/explanation/features/advanced-elicitation/) β€” LLM rethinking with 50+ reasoning methods -- **[Core Tasks](/reference/configuration/core-tasks/)** β€” Common tasks available across modules - - [Index Docs](/reference/configuration/core-tasks/#index-docs) β€” Generate directory index files - - [Adversarial Review](/reference/configuration/core-tasks/#adversarial-review-general) β€” Critical content review - - [Shard Document](/reference/configuration/core-tasks/#shard-document) β€” Split large documents into sections +- **[Global Core Config](/docs/reference/configuration/global-config.md)** β€” Inheritable configuration that impacts all modules and custom content +- **[Core Workflows](/docs/reference/workflows/core-workflows.md)** β€” Domain-agnostic workflows usable by any module + - [Party Mode](/docs/explanation/features/party-mode.md) β€” Multi-agent conversation orchestration + - [Brainstorming](/docs/explanation/features/brainstorming-techniques.md) β€” Structured creative sessions with 60+ techniques + - [Advanced Elicitation](/docs/explanation/features/advanced-elicitation.md) β€” LLM rethinking with 50+ reasoning methods +- **[Core Tasks](/docs/reference/configuration/core-tasks.md)** β€” Common tasks available across modules + - [Index Docs](/docs/reference/configuration/core-tasks.md#index-docs) β€” Generate directory index files + - [Adversarial Review](/docs/reference/configuration/core-tasks.md#adversarial-review-general) β€” Critical content review + - [Shard Document](/docs/reference/configuration/core-tasks.md#shard-document) β€” Split large documents into sections diff --git a/docs/explanation/creative-intelligence/index.md b/docs/explanation/creative-intelligence/index.md index dc8dc961..ecc3e7a9 100644 --- a/docs/explanation/creative-intelligence/index.md +++ b/docs/explanation/creative-intelligence/index.md @@ -117,5 +117,5 @@ CIS workflows integrate with: ## Related -- [Facilitation Over Generation](/explanation/philosophy/facilitation-over-generation/) - Core philosophy -- [Brainstorming Techniques](/explanation/features/brainstorming-techniques/) - Technique reference +- [Facilitation Over Generation](/docs/explanation/philosophy/facilitation-over-generation.md) - Core philosophy +- [Brainstorming Techniques](/docs/explanation/features/brainstorming-techniques.md) - Technique reference diff --git a/docs/explanation/faq/getting-started-faq.md b/docs/explanation/faq/getting-started-faq.md index f8428e47..424e1013 100644 --- a/docs/explanation/faq/getting-started-faq.md +++ b/docs/explanation/faq/getting-started-faq.md @@ -21,7 +21,7 @@ No, once you learn the flow you can go directly to workflows. However, workflow- - Creates the tracking status file - Routes you to the correct starting workflow -For experienced users: use the [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) to go directly to the right agent/workflow. +For experienced users: use the [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) to go directly to the right agent/workflow. ### Why do I need fresh chats for each workflow? diff --git a/docs/explanation/faq/tools-faq.md b/docs/explanation/faq/tools-faq.md index ac72d228..215d90e3 100644 --- a/docs/explanation/faq/tools-faq.md +++ b/docs/explanation/faq/tools-faq.md @@ -228,7 +228,7 @@ Party mode is a unique multi-agent collaboration feature where ALL your installe - Emergent insights from agent interaction - Natural collaboration across modules -**For complete documentation:** See the [Party Mode Guide](/explanation/features/party-mode/) +**For complete documentation:** See the [Party Mode Guide](/docs/explanation/features/party-mode.md) ## Getting Help diff --git a/docs/explanation/features/party-mode.md b/docs/explanation/features/party-mode.md index 24e74bf6..a3a494fa 100644 --- a/docs/explanation/features/party-mode.md +++ b/docs/explanation/features/party-mode.md @@ -103,9 +103,9 @@ _(Multiple perspectives reveal the right answer)_ ## Related Documentation -- [Agents Reference](/reference/agents/) - Complete agent reference -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Getting started with BMM -- [Setup Party Mode](/how-to/workflows/setup-party-mode/) - How to use it +- [Agents Reference](/docs/reference/agents/index.md) - Complete agent reference +- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM +- [Setup Party Mode](/docs/how-to/workflows/setup-party-mode.md) - How to use it --- diff --git a/docs/explanation/features/quick-flow.md b/docs/explanation/features/quick-flow.md index 0c403703..23ca08cc 100644 --- a/docs/explanation/features/quick-flow.md +++ b/docs/explanation/features/quick-flow.md @@ -164,6 +164,6 @@ Start with Quick Flow, but switch to BMad Method when: ## Related -- [Create Tech Spec](/how-to/workflows/create-tech-spec/) - How to use Quick Flow -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Getting started -- [Four Phases](/explanation/architecture/four-phases/) - Understanding the full methodology +- [Create Tech Spec](/docs/how-to/workflows/create-tech-spec.md) - How to use Quick Flow +- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started +- [Four Phases](/docs/explanation/architecture/four-phases.md) - Understanding the full methodology diff --git a/docs/explanation/features/tea-overview.md b/docs/explanation/features/tea-overview.md index 486c8a3c..11e4c8f3 100644 --- a/docs/explanation/features/tea-overview.md +++ b/docs/explanation/features/tea-overview.md @@ -214,5 +214,5 @@ Epic/Release Gate β†’ TEA: *nfr-assess, *trace Phase 2 (release decision) ## Related Documentation -- [Setup Test Framework](/how-to/workflows/setup-test-framework/) - How to set up testing infrastructure -- [Run Test Design](/how-to/workflows/run-test-design/) - Creating test plans +- [Setup Test Framework](/docs/how-to/workflows/setup-test-framework.md) - How to set up testing infrastructure +- [Run Test Design](/docs/how-to/workflows/run-test-design.md) - Creating test plans diff --git a/docs/explanation/game-dev/agents.md b/docs/explanation/game-dev/agents.md index c45680f5..1c429683 100644 --- a/docs/explanation/game-dev/agents.md +++ b/docs/explanation/game-dev/agents.md @@ -405,6 +405,6 @@ The `project-context.md` file (if present) serves as the authoritative source fo ## Next Steps -- **[Quick Start Guide](/tutorials/getting-started/quick-start-bmgd/)** - Get started with BMGD -- **[Workflows Guide](/reference/workflows/)** - Detailed workflow reference -- **[Game Types Guide](/explanation/game-dev/game-types/)** - Game type templates +- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD +- **[Workflows Guide](/docs/reference/workflows/index.md)** - Detailed workflow reference +- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Game type templates diff --git a/docs/explanation/game-dev/bmgd-vs-bmm.md b/docs/explanation/game-dev/bmgd-vs-bmm.md index 258475e0..3ce2d181 100644 --- a/docs/explanation/game-dev/bmgd-vs-bmm.md +++ b/docs/explanation/game-dev/bmgd-vs-bmm.md @@ -145,6 +145,6 @@ This means you get all of BMM's implementation structure plus game-specific enha ## Related -- [BMGD Overview](/explanation/game-dev/) - Getting started with BMGD -- [Game Types Guide](/explanation/game-dev/game-types/) - Understanding game templates -- [Quick Start BMGD](/tutorials/getting-started/quick-start-bmgd/) - Tutorial +- [BMGD Overview](/docs/explanation/game-dev/index.md) - Getting started with BMGD +- [Game Types Guide](/docs/explanation/game-dev/game-types.md) - Understanding game templates +- [Quick Start BMGD](/docs/tutorials/getting-started/quick-start-bmgd.md) - Tutorial diff --git a/docs/explanation/game-dev/game-types.md b/docs/explanation/game-dev/game-types.md index 54f4e682..1e754035 100644 --- a/docs/explanation/game-dev/game-types.md +++ b/docs/explanation/game-dev/game-types.md @@ -501,6 +501,6 @@ When you select a game type, BMGD adds these GDD sections: ## Next Steps -- **[Quick Start Guide](/tutorials/getting-started/quick-start-bmgd/)** - Get started with BMGD -- **[Workflows Guide](/reference/workflows/bmgd-workflows/)** - GDD workflow details -- **[Glossary](/reference/glossary/)** - Game development terminology +- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD +- **[Workflows Guide](/docs/reference/workflows/bmgd-workflows.md)** - GDD workflow details +- **[Glossary](/docs/reference/glossary/index.md)** - Game development terminology diff --git a/docs/explanation/game-dev/index.md b/docs/explanation/game-dev/index.md index 9e176b92..b84704a4 100644 --- a/docs/explanation/game-dev/index.md +++ b/docs/explanation/game-dev/index.md @@ -12,7 +12,7 @@ Complete guides for the BMad Game Development Module (BMGD) - AI-powered workflo **New to BMGD?** Start here: -- **[Quick Start Guide](/tutorials/getting-started/quick-start-bmgd/)** - Get started building your first game +- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started building your first game - Installation and setup - Understanding the game development phases - Running your first workflows @@ -24,8 +24,8 @@ Complete guides for the BMad Game Development Module (BMGD) - AI-powered workflo ## Core Documentation -- **[Game Types Guide](/explanation/game-dev/game-types/)** - Selecting and using game type templates (24 supported types) -- **[BMGD vs BMM](/explanation/game-dev/bmgd-vs-bmm/)** - Understanding the differences +- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Selecting and using game type templates (24 supported types) +- **[BMGD vs BMM](/docs/explanation/game-dev/bmgd-vs-bmm.md)** - Understanding the differences --- @@ -58,7 +58,7 @@ BMGD follows four phases aligned with game development: ### I need to... **Start a new game project** -β†’ Start with [Quick Start Guide](/tutorials/getting-started/quick-start-bmgd/) +β†’ Start with [Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md) β†’ Run `brainstorm-game` for ideation β†’ Create a Game Brief with `create-brief` @@ -74,12 +74,12 @@ BMGD follows four phases aligned with game development: β†’ Follow the sprint-based development cycle **Quickly test an idea** -β†’ Use [Quick-Flow](/how-to/workflows/bmgd-quick-flow/) for rapid prototyping +β†’ Use [Quick-Flow](/docs/how-to/workflows/bmgd-quick-flow.md) for rapid prototyping --- ## Related -- [Game Types Guide](/explanation/game-dev/game-types/) - Understanding game type templates -- [BMGD vs BMM](/explanation/game-dev/bmgd-vs-bmm/) - Comparison with core method -- [Glossary](/reference/glossary/) - Terminology reference +- [Game Types Guide](/docs/explanation/game-dev/game-types.md) - Understanding game type templates +- [BMGD vs BMM](/docs/explanation/game-dev/bmgd-vs-bmm.md) - Comparison with core method +- [Glossary](/docs/reference/glossary/index.md) - Terminology reference diff --git a/docs/explanation/philosophy/facilitation-over-generation.md b/docs/explanation/philosophy/facilitation-over-generation.md index c3e094ae..92552651 100644 --- a/docs/explanation/philosophy/facilitation-over-generation.md +++ b/docs/explanation/philosophy/facilitation-over-generation.md @@ -117,5 +117,5 @@ But the core creative work happens through facilitated discovery. ## Related -- [Creative Intelligence Suite](/explanation/creative-intelligence/) - CIS overview -- [Brainstorming Techniques](/explanation/features/brainstorming-techniques/) - Available techniques +- [Creative Intelligence Suite](/docs/explanation/creative-intelligence/index.md) - CIS overview +- [Brainstorming Techniques](/docs/explanation/features/brainstorming-techniques.md) - Available techniques diff --git a/docs/how-to/brownfield/add-feature-to-existing.md b/docs/how-to/brownfield/add-feature-to-existing.md index 480c44ab..98683ec6 100644 --- a/docs/how-to/brownfield/add-feature-to-existing.md +++ b/docs/how-to/brownfield/add-feature-to-existing.md @@ -86,6 +86,6 @@ Follow the standard Phase 4 implementation workflows: ## Related -- [Brownfield Development Guide](/how-to/brownfield/) -- [Document Existing Project](/how-to/brownfield/document-existing-project/) -- [Quick Fix in Brownfield](/how-to/brownfield/quick-fix-in-brownfield/) +- [Brownfield Development Guide](/docs/how-to/brownfield/index.md) +- [Document Existing Project](/docs/how-to/brownfield/document-existing-project.md) +- [Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md) diff --git a/docs/how-to/brownfield/document-existing-project.md b/docs/how-to/brownfield/document-existing-project.md index 8bd7346f..68303742 100644 --- a/docs/how-to/brownfield/document-existing-project.md +++ b/docs/how-to/brownfield/document-existing-project.md @@ -80,5 +80,5 @@ Review the documentation for: ## Related -- [Brownfield Development Guide](/how-to/brownfield/) -- [Add Feature to Existing Project](/how-to/brownfield/add-feature-to-existing/) +- [Brownfield Development Guide](/docs/how-to/brownfield/index.md) +- [Add Feature to Existing Project](/docs/how-to/brownfield/add-feature-to-existing.md) diff --git a/docs/how-to/brownfield/index.md b/docs/how-to/brownfield/index.md index a9c92f47..070f1a88 100644 --- a/docs/how-to/brownfield/index.md +++ b/docs/how-to/brownfield/index.md @@ -89,14 +89,14 @@ Pay close attention here to prevent reinventing the wheel or making decisions th ## Next Steps -- **[Document Existing Project](/how-to/brownfield/document-existing-project/)** - How to document your brownfield codebase -- **[Add Feature to Existing Project](/how-to/brownfield/add-feature-to-existing/)** - Adding new functionality -- **[Quick Fix in Brownfield](/how-to/brownfield/quick-fix-in-brownfield/)** - Bug fixes and ad-hoc changes -- **[Brownfield FAQ](/explanation/faq/brownfield-faq/)** - Common questions about brownfield development +- **[Document Existing Project](/docs/how-to/brownfield/document-existing-project.md)** - How to document your brownfield codebase +- **[Add Feature to Existing Project](/docs/how-to/brownfield/add-feature-to-existing.md)** - Adding new functionality +- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes +- **[Brownfield FAQ](/docs/explanation/faq/brownfield-faq.md)** - Common questions about brownfield development --- ## Related Documentation -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Getting started with BMM -- [Quick Spec Flow](/explanation/features/quick-flow/) - Fast path for small changes +- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM +- [Quick Spec Flow](/docs/explanation/features/quick-flow.md) - Fast path for small changes diff --git a/docs/how-to/brownfield/quick-fix-in-brownfield.md b/docs/how-to/brownfield/quick-fix-in-brownfield.md index dd797fb0..8a695b55 100644 --- a/docs/how-to/brownfield/quick-fix-in-brownfield.md +++ b/docs/how-to/brownfield/quick-fix-in-brownfield.md @@ -89,6 +89,6 @@ Consider using Quick Flow or full BMad Method when: ## Related -- [Brownfield Development Guide](/how-to/brownfield/) -- [Add Feature to Existing Project](/how-to/brownfield/add-feature-to-existing/) -- [Quick Spec Flow](/explanation/features/quick-flow/) +- [Brownfield Development Guide](/docs/how-to/brownfield/index.md) +- [Add Feature to Existing Project](/docs/how-to/brownfield/add-feature-to-existing.md) +- [Quick Spec Flow](/docs/explanation/features/quick-flow.md) diff --git a/docs/how-to/customization/customize-agents.md b/docs/how-to/customization/customize-agents.md index 49854140..cf0a228b 100644 --- a/docs/how-to/customization/customize-agents.md +++ b/docs/how-to/customization/customize-agents.md @@ -201,8 +201,8 @@ memories: ## Next Steps -- **[Learn about Agents](/explanation/core-concepts/what-are-agents/)** - Understand Simple vs Expert agents -- **[Agent Creation Guide](/tutorials/advanced/create-custom-agent/)** - Build completely custom agents -- **[BMM Complete Documentation](/explanation/bmm/)** - Full BMad Method reference +- **[Learn about Agents](/docs/explanation/core-concepts/what-are-agents.md)** - Understand Simple vs Expert agents +- **[Agent Creation Guide](/docs/tutorials/advanced/create-custom-agent.md)** - Build completely custom agents +- **[BMM Complete Documentation](/docs/explanation/bmm/index.md)** - Full BMad Method reference -[← Back to Customization](/how-to/customization/) +[← Back to Customization](/docs/how-to/customization/index.md) diff --git a/docs/how-to/customization/customize-workflows.md b/docs/how-to/customization/customize-workflows.md index a87c267a..97ddccd5 100644 --- a/docs/how-to/customization/customize-workflows.md +++ b/docs/how-to/customization/customize-workflows.md @@ -23,11 +23,11 @@ Workflow customization will allow you to: While workflow customization is in development, you can: - **Create Custom Workflows** - Use the BMad Builder to create entirely new workflows -- **Customize Agents** - Modify agent behavior using [Agent Customization](/how-to/customization/customize-agents/) +- **Customize Agents** - Modify agent behavior using [Agent Customization](/docs/how-to/customization/customize-agents.md) - **Provide Feedback** - Share your workflow customization needs with the community --- -**In the meantime:** Learn how to [create custom workflows](/explanation/bmad-builder/) from scratch. +**In the meantime:** Learn how to [create custom workflows](/docs/explanation/bmad-builder/index.md) from scratch. -[← Back to Customization](/how-to/customization/) +[← Back to Customization](/docs/how-to/customization/index.md) diff --git a/docs/how-to/customization/index.md b/docs/how-to/customization/index.md index ee16ab62..f13f0726 100644 --- a/docs/how-to/customization/index.md +++ b/docs/how-to/customization/index.md @@ -9,8 +9,8 @@ Personalize agents and workflows to match your needs. | Guide | Description | |-------|-------------| -| **[Agent Customization](/how-to/customization/customize-agents/)** | Modify agent behavior without editing core files | -| **[Workflow Customization](/how-to/customization/customize-workflows/)** | Customize and optimize workflows | +| **[Agent Customization](/docs/how-to/customization/customize-agents.md)** | Modify agent behavior without editing core files | +| **[Workflow Customization](/docs/how-to/customization/customize-workflows.md)** | Customize and optimize workflows | ## Overview @@ -24,4 +24,4 @@ Replace or extend workflow steps to create tailored processes. (Coming soon) --- -**Next:** Read the [Agent Customization Guide](/how-to/customization/customize-agents/) to start personalizing your agents. +**Next:** Read the [Agent Customization Guide](/docs/how-to/customization/customize-agents.md) to start personalizing your agents. diff --git a/docs/how-to/get-answers-about-bmad.md b/docs/how-to/get-answers-about-bmad.md index fbe8c350..3f5cf880 100644 --- a/docs/how-to/get-answers-about-bmad.md +++ b/docs/how-to/get-answers-about-bmad.md @@ -45,7 +45,7 @@ Fetch `llms-full.txt` into your session: https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt ``` -You can also find this and other downloadable resources on the [Downloads page](/downloads). +You can also find this and other downloadable resources on the [Downloads page](/docs/downloads.md). :::tip[Verify Surprising Answers] LLMs occasionally get things wrong. If an answer seems off, check the source file it referenced or ask on Discord. diff --git a/docs/how-to/installation/index.md b/docs/how-to/installation/index.md index 51eff3f3..928aa7db 100644 --- a/docs/how-to/installation/index.md +++ b/docs/how-to/installation/index.md @@ -10,6 +10,6 @@ How-to guides for installing and configuring the BMad Method. | Guide | Description | |-------|-------------| -| **[Install BMad](/how-to/installation/install-bmad/)** | Step-by-step installation instructions | -| **[Install Custom Modules](/how-to/installation/install-custom-modules/)** | Add custom agents, workflows, and modules | -| **[Upgrade to v6](/how-to/installation/upgrade-to-v6/)** | Migrate from BMad v4 to v6 | +| **[Install BMad](/docs/how-to/installation/install-bmad.md)** | Step-by-step installation instructions | +| **[Install Custom Modules](/docs/how-to/installation/install-custom-modules.md)** | Add custom agents, workflows, and modules | +| **[Upgrade to v6](/docs/how-to/installation/upgrade-to-v6.md)** | Migrate from BMad v4 to v6 | diff --git a/docs/how-to/installation/install-bmad.md b/docs/how-to/installation/install-bmad.md index 74c0ec54..d439c888 100644 --- a/docs/how-to/installation/install-bmad.md +++ b/docs/how-to/installation/install-bmad.md @@ -133,6 +133,6 @@ npx bmad-method install --verbose ## Related -- [Quick Start Guide](/tutorials/getting-started/getting-started-bmadv6/) - Getting started with BMM -- [Upgrade to V6](/how-to/installation/upgrade-to-v6/) - Upgrading from previous versions -- [Install Custom Modules](/how-to/installation/install-custom-modules/) - Adding custom content +- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM +- [Upgrade to V6](/docs/how-to/installation/upgrade-to-v6.md) - Upgrading from previous versions +- [Install Custom Modules](/docs/how-to/installation/install-custom-modules.md) - Adding custom content diff --git a/docs/how-to/installation/install-custom-modules.md b/docs/how-to/installation/install-custom-modules.md index ad60b818..1c6e2fed 100644 --- a/docs/how-to/installation/install-custom-modules.md +++ b/docs/how-to/installation/install-custom-modules.md @@ -5,7 +5,7 @@ title: "Custom Content Installation" This guide explains how to create and install custom BMad content including agents, workflows, and modules. Custom content extends BMad's functionality with specialized tools and workflows that can be shared across projects or teams. -For detailed information about the different types of custom content available, see [Custom Content Types](/explanation/bmad-builder/custom-content-types/). +For detailed information about the different types of custom content available, see [Custom Content Types](/docs/explanation/bmad-builder/custom-content-types.md). You can find example custom modules in the `samples/sample-custom-modules/` folder of the repository. Download either of the sample folders to try them out. diff --git a/docs/how-to/installation/upgrade-to-v6.md b/docs/how-to/installation/upgrade-to-v6.md index 707cffff..6a1349f4 100644 --- a/docs/how-to/installation/upgrade-to-v6.md +++ b/docs/how-to/installation/upgrade-to-v6.md @@ -123,7 +123,7 @@ persona: - Always upbeat and adventurous ``` -There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](/how-to/customization/customize-agents/) +There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](/docs/how-to/customization/customize-agents.md) CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations. diff --git a/docs/how-to/troubleshooting/bmgd-troubleshooting.md b/docs/how-to/troubleshooting/bmgd-troubleshooting.md index 405c9588..68942b95 100644 --- a/docs/how-to/troubleshooting/bmgd-troubleshooting.md +++ b/docs/how-to/troubleshooting/bmgd-troubleshooting.md @@ -256,6 +256,6 @@ When reporting issues, include: ## Next Steps -- **[Quick Start Guide](/tutorials/getting-started/quick-start-bmgd/)** - Getting started -- **[Workflows Guide](/reference/workflows/)** - Workflow reference -- **[Glossary](/reference/glossary/)** - Terminology +- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started +- **[Workflows Guide](/docs/reference/workflows/index.md)** - Workflow reference +- **[Glossary](/docs/reference/glossary/index.md)** - Terminology diff --git a/docs/how-to/workflows/bmgd-quick-flow.md b/docs/how-to/workflows/bmgd-quick-flow.md index 1e03d9e9..61dad971 100644 --- a/docs/how-to/workflows/bmgd-quick-flow.md +++ b/docs/how-to/workflows/bmgd-quick-flow.md @@ -286,6 +286,6 @@ If quick-dev keeps expanding scope, stop and create proper stories. ## Next Steps -- **[Workflows Guide](/reference/workflows/bmgd-workflows/)** - Full workflow reference -- **[Agents Guide](/explanation/game-dev/agents/)** - Agent capabilities -- **[Quick Start Guide](/tutorials/getting-started/quick-start-bmgd/)** - Getting started with BMGD +- **[Workflows Guide](/docs/reference/workflows/bmgd-workflows.md)** - Full workflow reference +- **[Agents Guide](/docs/explanation/game-dev/agents.md)** - Agent capabilities +- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started with BMGD diff --git a/docs/how-to/workflows/conduct-research.md b/docs/how-to/workflows/conduct-research.md index 87aab277..ee6e02ef 100644 --- a/docs/how-to/workflows/conduct-research.md +++ b/docs/how-to/workflows/conduct-research.md @@ -125,6 +125,6 @@ After research: ## Related -- [Run Brainstorming Session](/how-to/workflows/run-brainstorming-session/) - Explore ideas before research -- [Create Product Brief](/how-to/workflows/create-product-brief/) - Capture strategic vision -- [Create PRD](/how-to/workflows/create-prd/) - Move to formal planning +- [Run Brainstorming Session](/docs/how-to/workflows/run-brainstorming-session.md) - Explore ideas before research +- [Create Product Brief](/docs/how-to/workflows/create-product-brief.md) - Capture strategic vision +- [Create PRD](/docs/how-to/workflows/create-prd.md) - Move to formal planning diff --git a/docs/how-to/workflows/create-architecture.md b/docs/how-to/workflows/create-architecture.md index cd045b26..1e55896c 100644 --- a/docs/how-to/workflows/create-architecture.md +++ b/docs/how-to/workflows/create-architecture.md @@ -141,7 +141,7 @@ After architecture: ## Related -- [Create PRD](/how-to/workflows/create-prd/) - Requirements before architecture -- [Create Epics and Stories](/how-to/workflows/create-epics-and-stories/) - Next step -- [Run Implementation Readiness](/how-to/workflows/run-implementation-readiness/) - Gate check -- [Why Solutioning Matters](/explanation/architecture/why-solutioning-matters/) +- [Create PRD](/docs/how-to/workflows/create-prd.md) - Requirements before architecture +- [Create Epics and Stories](/docs/how-to/workflows/create-epics-and-stories.md) - Next step +- [Run Implementation Readiness](/docs/how-to/workflows/run-implementation-readiness.md) - Gate check +- [Why Solutioning Matters](/docs/explanation/architecture/why-solutioning-matters.md) diff --git a/docs/how-to/workflows/create-epics-and-stories.md b/docs/how-to/workflows/create-epics-and-stories.md index 2d0a3c3d..78b662b7 100644 --- a/docs/how-to/workflows/create-epics-and-stories.md +++ b/docs/how-to/workflows/create-epics-and-stories.md @@ -131,6 +131,6 @@ After creating epics and stories: ## Related -- [Create Architecture](/how-to/workflows/create-architecture/) - Do this first -- [Run Implementation Readiness](/how-to/workflows/run-implementation-readiness/) - Gate check -- [Run Sprint Planning](/how-to/workflows/run-sprint-planning/) - Start implementation +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Do this first +- [Run Implementation Readiness](/docs/how-to/workflows/run-implementation-readiness.md) - Gate check +- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Start implementation diff --git a/docs/how-to/workflows/create-prd.md b/docs/how-to/workflows/create-prd.md index 9a9f93f5..36053cdc 100644 --- a/docs/how-to/workflows/create-prd.md +++ b/docs/how-to/workflows/create-prd.md @@ -125,6 +125,6 @@ After PRD: ## Related -- [Create Product Brief](/how-to/workflows/create-product-brief/) - Input for PRD -- [Create UX Design](/how-to/workflows/create-ux-design/) - Optional UX workflow -- [Create Architecture](/how-to/workflows/create-architecture/) - Next step after PRD +- [Create Product Brief](/docs/how-to/workflows/create-product-brief.md) - Input for PRD +- [Create UX Design](/docs/how-to/workflows/create-ux-design.md) - Optional UX workflow +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Next step after PRD diff --git a/docs/how-to/workflows/create-product-brief.md b/docs/how-to/workflows/create-product-brief.md index 668342e1..7d388a9f 100644 --- a/docs/how-to/workflows/create-product-brief.md +++ b/docs/how-to/workflows/create-product-brief.md @@ -112,6 +112,6 @@ Planning workflows automatically load the product brief if it exists. ## Related -- [Run Brainstorming Session](/how-to/workflows/run-brainstorming-session/) - Explore ideas first -- [Conduct Research](/how-to/workflows/conduct-research/) - Validate ideas -- [Create PRD](/how-to/workflows/create-prd/) - Next step after product brief +- [Run Brainstorming Session](/docs/how-to/workflows/run-brainstorming-session.md) - Explore ideas first +- [Conduct Research](/docs/how-to/workflows/conduct-research.md) - Validate ideas +- [Create PRD](/docs/how-to/workflows/create-prd.md) - Next step after product brief diff --git a/docs/how-to/workflows/create-story.md b/docs/how-to/workflows/create-story.md index 9012e5c3..53c083a9 100644 --- a/docs/how-to/workflows/create-story.md +++ b/docs/how-to/workflows/create-story.md @@ -114,6 +114,6 @@ Implement email verification flow for new user registrations. ## Related -- [Run Sprint Planning](/how-to/workflows/run-sprint-planning/) - Initialize tracking -- [Implement Story](/how-to/workflows/implement-story/) - Next step -- [Run Code Review](/how-to/workflows/run-code-review/) - After implementation +- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Initialize tracking +- [Implement Story](/docs/how-to/workflows/implement-story.md) - Next step +- [Run Code Review](/docs/how-to/workflows/run-code-review.md) - After implementation diff --git a/docs/how-to/workflows/create-tech-spec.md b/docs/how-to/workflows/create-tech-spec.md index faca1c62..a7ffefb6 100644 --- a/docs/how-to/workflows/create-tech-spec.md +++ b/docs/how-to/workflows/create-tech-spec.md @@ -154,6 +154,6 @@ If your "single change" needs 3+ files, it might be a multi-story feature. Let t ## Related -- [Quick Flow](/explanation/features/quick-flow/) - Understanding Quick Spec Flow -- [Implement Story](/how-to/workflows/implement-story/) - After tech spec -- [Create PRD](/how-to/workflows/create-prd/) - For larger projects needing full BMad Method +- [Quick Flow](/docs/explanation/features/quick-flow.md) - Understanding Quick Spec Flow +- [Implement Story](/docs/how-to/workflows/implement-story.md) - After tech spec +- [Create PRD](/docs/how-to/workflows/create-prd.md) - For larger projects needing full BMad Method diff --git a/docs/how-to/workflows/create-ux-design.md b/docs/how-to/workflows/create-ux-design.md index 4cdf76a0..a10fa7cf 100644 --- a/docs/how-to/workflows/create-ux-design.md +++ b/docs/how-to/workflows/create-ux-design.md @@ -112,6 +112,6 @@ The UX spec feeds into: ## Related -- [Create PRD](/how-to/workflows/create-prd/) - Create requirements first -- [Create Architecture](/how-to/workflows/create-architecture/) - Technical design -- [Create Epics and Stories](/how-to/workflows/create-epics-and-stories/) - Work breakdown +- [Create PRD](/docs/how-to/workflows/create-prd.md) - Create requirements first +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Technical design +- [Create Epics and Stories](/docs/how-to/workflows/create-epics-and-stories.md) - Work breakdown diff --git a/docs/how-to/workflows/implement-story.md b/docs/how-to/workflows/implement-story.md index 625f8180..038886e0 100644 --- a/docs/how-to/workflows/implement-story.md +++ b/docs/how-to/workflows/implement-story.md @@ -122,6 +122,6 @@ A: Split the story and document the change. ## Related -- [Create Story](/how-to/workflows/create-story/) - Prepare the story first -- [Run Code Review](/how-to/workflows/run-code-review/) - After implementation -- [Run Sprint Planning](/how-to/workflows/run-sprint-planning/) - Sprint organization +- [Create Story](/docs/how-to/workflows/create-story.md) - Prepare the story first +- [Run Code Review](/docs/how-to/workflows/run-code-review.md) - After implementation +- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Sprint organization diff --git a/docs/how-to/workflows/run-brainstorming-session.md b/docs/how-to/workflows/run-brainstorming-session.md index 90ae0332..298d9e8c 100644 --- a/docs/how-to/workflows/run-brainstorming-session.md +++ b/docs/how-to/workflows/run-brainstorming-session.md @@ -89,6 +89,6 @@ After brainstorming: ## Related -- [Conduct Research](/how-to/workflows/conduct-research/) - Validate your ideas -- [Create Product Brief](/how-to/workflows/create-product-brief/) - Capture strategic vision -- [Create PRD](/how-to/workflows/create-prd/) - Move to formal planning +- [Conduct Research](/docs/how-to/workflows/conduct-research.md) - Validate your ideas +- [Create Product Brief](/docs/how-to/workflows/create-product-brief.md) - Capture strategic vision +- [Create PRD](/docs/how-to/workflows/create-prd.md) - Move to formal planning diff --git a/docs/how-to/workflows/run-code-review.md b/docs/how-to/workflows/run-code-review.md index e14e0c34..bbd3f211 100644 --- a/docs/how-to/workflows/run-code-review.md +++ b/docs/how-to/workflows/run-code-review.md @@ -136,6 +136,6 @@ Every story goes through code-review before being marked done. This ensures: ## Related -- [Implement Story](/how-to/workflows/implement-story/) - Before code review -- [Create Story](/how-to/workflows/create-story/) - Move to next story -- [Run Sprint Planning](/how-to/workflows/run-sprint-planning/) - Sprint organization +- [Implement Story](/docs/how-to/workflows/implement-story.md) - Before code review +- [Create Story](/docs/how-to/workflows/create-story.md) - Move to next story +- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Sprint organization diff --git a/docs/how-to/workflows/run-implementation-readiness.md b/docs/how-to/workflows/run-implementation-readiness.md index f43fdd93..27be2d54 100644 --- a/docs/how-to/workflows/run-implementation-readiness.md +++ b/docs/how-to/workflows/run-implementation-readiness.md @@ -157,6 +157,6 @@ E-commerce platform β†’ CONCERNS ⚠️ ## Related -- [Create Architecture](/how-to/workflows/create-architecture/) - Architecture workflow -- [Create Epics and Stories](/how-to/workflows/create-epics-and-stories/) - Work breakdown -- [Run Sprint Planning](/how-to/workflows/run-sprint-planning/) - Start implementation +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Architecture workflow +- [Create Epics and Stories](/docs/how-to/workflows/create-epics-and-stories.md) - Work breakdown +- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Start implementation diff --git a/docs/how-to/workflows/run-sprint-planning.md b/docs/how-to/workflows/run-sprint-planning.md index f020ca8c..e92f42a4 100644 --- a/docs/how-to/workflows/run-sprint-planning.md +++ b/docs/how-to/workflows/run-sprint-planning.md @@ -106,6 +106,6 @@ Stories move through these states in the sprint status file: ## Related -- [Create Story](/how-to/workflows/create-story/) - Prepare stories for implementation -- [Implement Story](/how-to/workflows/implement-story/) - Dev workflow -- [Run Code Review](/how-to/workflows/run-code-review/) - Quality assurance +- [Create Story](/docs/how-to/workflows/create-story.md) - Prepare stories for implementation +- [Implement Story](/docs/how-to/workflows/implement-story.md) - Dev workflow +- [Run Code Review](/docs/how-to/workflows/run-code-review.md) - Quality assurance diff --git a/docs/how-to/workflows/run-test-design.md b/docs/how-to/workflows/run-test-design.md index 6742a9a3..f2b6361f 100644 --- a/docs/how-to/workflows/run-test-design.md +++ b/docs/how-to/workflows/run-test-design.md @@ -123,6 +123,6 @@ TEA generates a comprehensive test design document. ## Related -- [TEA Overview](/explanation/features/tea-overview/) - Understanding the Test Architect -- [Setup Test Framework](/how-to/workflows/setup-test-framework/) - Setting up testing infrastructure -- [Create Architecture](/how-to/workflows/create-architecture/) - Architecture workflow +- [TEA Overview](/docs/explanation/features/tea-overview.md) - Understanding the Test Architect +- [Setup Test Framework](/docs/how-to/workflows/setup-test-framework.md) - Setting up testing infrastructure +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Architecture workflow diff --git a/docs/how-to/workflows/setup-party-mode.md b/docs/how-to/workflows/setup-party-mode.md index 8aaf7499..3e82e440 100644 --- a/docs/how-to/workflows/setup-party-mode.md +++ b/docs/how-to/workflows/setup-party-mode.md @@ -113,5 +113,5 @@ Type "exit" or "done" to conclude the session. Participating agents will say per ## Related -- [Party Mode](/explanation/features/party-mode/) - Understanding Party Mode -- [Agent Roles](/explanation/core-concepts/agent-roles/) - Available agents +- [Party Mode](/docs/explanation/features/party-mode.md) - Understanding Party Mode +- [Agent Roles](/docs/explanation/core-concepts/agent-roles.md) - Available agents diff --git a/docs/how-to/workflows/setup-test-framework.md b/docs/how-to/workflows/setup-test-framework.md index 93ecf471..508d6144 100644 --- a/docs/how-to/workflows/setup-test-framework.md +++ b/docs/how-to/workflows/setup-test-framework.md @@ -108,6 +108,6 @@ Configure in your IDE's MCP settings. ## Related -- [TEA Overview](/explanation/features/tea-overview/) - Understanding the Test Architect -- [Run Test Design](/how-to/workflows/run-test-design/) - Creating test plans -- [Create Architecture](/how-to/workflows/create-architecture/) - Architecture workflow +- [TEA Overview](/docs/explanation/features/tea-overview.md) - Understanding the Test Architect +- [Run Test Design](/docs/how-to/workflows/run-test-design.md) - Creating test plans +- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Architecture workflow diff --git a/docs/index.md b/docs/index.md index 2550c897..abc96030 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,10 +12,10 @@ If you're comfortable working with AI coding assistants like Claude, Cursor, or The fastest way to understand BMad is to try it. Choose a tutorial to walk through your first project in about 10 minutes. -- **[Get Started with BMad](/tutorials/getting-started/getting-started-bmadv6/)** β€” Latest features, still in active development +- **[Get Started with BMad](/docs/tutorials/getting-started/getting-started-bmadv6.md)** β€” Latest features, still in active development :::tip[Already familiar with AI-assisted development?] -Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](/explanation/core-concepts/what-are-agents/) to understand how BMad organizes its AI personas. +Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](/docs/explanation/core-concepts/what-are-agents.md) to understand how BMad organizes its AI personas. ::: --- @@ -60,4 +60,4 @@ Get help, share what you're building, or contribute to BMad: Ready to dive in? Pick a tutorial and start building. -- **[Get Started with BMad](/tutorials/getting-started/getting-started-bmadv6/)** β€” Explore the latest features +- **[Get Started with BMad](/docs/tutorials/getting-started/getting-started-bmadv6.md)** β€” Explore the latest features diff --git a/docs/reference/agents/index.md b/docs/reference/agents/index.md index 2274569a..1077f385 100644 --- a/docs/reference/agents/index.md +++ b/docs/reference/agents/index.md @@ -137,5 +137,5 @@ Available to all agents: ## Related -- [Agent Roles](/explanation/core-concepts/agent-roles/) - Understanding agent responsibilities -- [What Are Agents](/explanation/core-concepts/what-are-agents/) - Foundational concepts +- [Agent Roles](/docs/explanation/core-concepts/agent-roles.md) - Understanding agent responsibilities +- [What Are Agents](/docs/explanation/core-concepts/what-are-agents.md) - Foundational concepts diff --git a/docs/reference/workflows/bmgd-workflows.md b/docs/reference/workflows/bmgd-workflows.md index f20c0575..79d19165 100644 --- a/docs/reference/workflows/bmgd-workflows.md +++ b/docs/reference/workflows/bmgd-workflows.md @@ -262,7 +262,7 @@ Checks current project status across all phases. Shows completed documents, curr ## Quick-Flow Workflows -Fast-track workflows that skip full planning phases. See **[Quick-Flow Guide](/how-to/workflows/bmgd-quick-flow/)** for detailed usage. +Fast-track workflows that skip full planning phases. See **[Quick-Flow Guide](/docs/how-to/workflows/bmgd-quick-flow.md)** for detailed usage. ### Quick-Prototype @@ -460,7 +460,7 @@ This means: ## Next Steps -- **[Quick Start Guide](/tutorials/getting-started/quick-start-bmgd/)** - Get started with BMGD -- **[Quick-Flow Guide](/how-to/workflows/bmgd-quick-flow/)** - Rapid prototyping and development -- **[Agents Guide](/explanation/game-dev/agents/)** - Agent reference -- **[Game Types Guide](/explanation/game-dev/game-types/)** - Game type templates +- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD +- **[Quick-Flow Guide](/docs/how-to/workflows/bmgd-quick-flow.md)** - Rapid prototyping and development +- **[Agents Guide](/docs/explanation/game-dev/agents.md)** - Agent reference +- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Game type templates diff --git a/docs/reference/workflows/core-workflows.md b/docs/reference/workflows/core-workflows.md index 806c119a..ef27d5c9 100644 --- a/docs/reference/workflows/core-workflows.md +++ b/docs/reference/workflows/core-workflows.md @@ -7,15 +7,15 @@ Core Workflows are domain-agnostic workflows that can be utilized by any BMad-co ## Available Core Workflows -### [Party Mode](/explanation/features/party-mode/) +### [Party Mode](/docs/explanation/features/party-mode.md) Orchestrate dynamic multi-agent conversations with your entire BMad team. Engage with multiple specialized perspectives simultaneouslyβ€”each agent maintaining their unique personality, expertise, and communication style. -### [Brainstorming](/explanation/features/brainstorming-techniques/) +### [Brainstorming](/docs/explanation/features/brainstorming-techniques.md) Facilitate structured creative sessions using 60+ proven ideation techniques. The AI acts as coach and guide, using proven creativity methods to draw out ideas and insights that are already within you. -### [Advanced Elicitation](/explanation/features/advanced-elicitation/) +### [Advanced Elicitation](/docs/explanation/features/advanced-elicitation.md) Push the LLM to rethink its work through 50+ reasoning methodsβ€”the inverse of brainstorming. The LLM applies sophisticated techniques to re-examine and enhance content it has just generated, essentially "LLM brainstorming" to find better approaches and uncover improvements. diff --git a/docs/reference/workflows/document-project.md b/docs/reference/workflows/document-project.md index 08da12ba..f6eaba55 100644 --- a/docs/reference/workflows/document-project.md +++ b/docs/reference/workflows/document-project.md @@ -70,5 +70,5 @@ The workflow can be interrupted and resumed without losing progress: **Related Documentation:** -- [Brownfield Development Guide](/how-to/brownfield/) -- [Implementation Workflows](/how-to/workflows/run-sprint-planning/) +- [Brownfield Development Guide](/docs/how-to/brownfield/index.md) +- [Implementation Workflows](/docs/how-to/workflows/run-sprint-planning.md) diff --git a/docs/reference/workflows/index.md b/docs/reference/workflows/index.md index f2d2fc83..d1da2924 100644 --- a/docs/reference/workflows/index.md +++ b/docs/reference/workflows/index.md @@ -8,9 +8,9 @@ Complete reference documentation for all BMad Method workflows. ## Core Workflows -- [Core Workflows](/reference/workflows/core-workflows/) - Domain-agnostic workflows available to all modules -- [Document Project](/reference/workflows/document-project/) - Brownfield project documentation workflow +- [Core Workflows](/docs/reference/workflows/core-workflows.md) - Domain-agnostic workflows available to all modules +- [Document Project](/docs/reference/workflows/document-project.md) - Brownfield project documentation workflow ## Module-Specific Workflows -- [BMGD Workflows](/reference/workflows/bmgd-workflows/) - Game development workflows +- [BMGD Workflows](/docs/reference/workflows/bmgd-workflows.md) - Game development workflows diff --git a/docs/tutorials/advanced/create-custom-agent.md b/docs/tutorials/advanced/create-custom-agent.md index 626697ad..1050b341 100644 --- a/docs/tutorials/advanced/create-custom-agent.md +++ b/docs/tutorials/advanced/create-custom-agent.md @@ -159,9 +159,9 @@ Study the reference agents in `src/modules/bmb/reference/agents/`: ## Further Reading -- **[What Are Agents](/explanation/core-concepts/what-are-agents/)** - Deep technical details on agent types -- **[Agent Customization](/how-to/customization/customize-agents/)** - Modify agents without editing core files -- **[Custom Content Installation](/how-to/installation/install-custom-modules/)** - Package and distribute your agents +- **[What Are Agents](/docs/explanation/core-concepts/what-are-agents.md)** - Deep technical details on agent types +- **[Agent Customization](/docs/how-to/customization/customize-agents.md)** - Modify agents without editing core files +- **[Custom Content Installation](/docs/how-to/installation/install-custom-modules.md)** - Package and distribute your agents :::tip[Key Takeaways] - **Start small** - Your first agent should solve one problem well diff --git a/docs/tutorials/getting-started/getting-started-bmadv6.md b/docs/tutorials/getting-started/getting-started-bmadv6.md index 83f104ba..ed674cb3 100644 --- a/docs/tutorials/getting-started/getting-started-bmadv6.md +++ b/docs/tutorials/getting-started/getting-started-bmadv6.md @@ -3,7 +3,7 @@ title: "Getting Started with the BMad Method" description: Install BMad and build your first project --- -**Upgrading from previous versions?** See the [Upgrade Guide](/how-to/installation/upgrade-to-v6/) instead. +**Upgrading from previous versions?** See the [Upgrade Guide](/docs/how-to/installation/upgrade-to-v6.md) instead. --- @@ -83,7 +83,7 @@ your-project/ ``` :::tip[Troubleshooting] -Having issues? See [Install BMad](/how-to/installation/install-bmad/) for common solutions. +Having issues? See [Install BMad](/docs/how-to/installation/install-bmad.md) for common solutions. ::: ## Step 1: Initialize Your Project @@ -230,7 +230,7 @@ Yes, once you learn the flow. Use the Quick Reference to go directly to needed w - **During workflows** β€” Agents guide you with questions and explanations - **Community** β€” [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) -- **Documentation** β€” [BMM Workflow Reference](/reference/workflows/) +- **Documentation** β€” [BMM Workflow Reference](/docs/reference/workflows/index.md) - **Video tutorials** β€” [BMad Code YouTube](https://www.youtube.com/@BMadCode) ## Key Takeaways diff --git a/docs/tutorials/getting-started/quick-start-bmgd.md b/docs/tutorials/getting-started/quick-start-bmgd.md index d482e32d..421ea867 100644 --- a/docs/tutorials/getting-started/quick-start-bmgd.md +++ b/docs/tutorials/getting-started/quick-start-bmgd.md @@ -7,7 +7,7 @@ description: Build games with BMad's Game Development Module Build games faster using AI-powered workflows with specialized game development agents that guide you through preproduction, design, architecture, and implementation. :::note[Module Extension] -BMGD (BMad Game Development) is a module that extends BMad Method. You'll need BMad installed firstβ€”see the [BMad v6 tutorial](/tutorials/getting-started/getting-started-bmadv6/) if you haven't installed it yet. +BMGD (BMad Game Development) is a module that extends BMad Method. You'll need BMad installed firstβ€”see the [BMad v6 tutorial](/docs/tutorials/getting-started/getting-started-bmadv6.md) if you haven't installed it yet. ::: ## What You'll Learn @@ -244,7 +244,7 @@ Yes. Documents are living artifactsβ€”return to update them as your vision evolv - **During workflows** β€” Agents guide you with questions and explanations - **Community** β€” [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) -- **Documentation** β€” [BMGD Workflow Reference](/reference/workflows/bmgd-workflows/) +- **Documentation** β€” [BMGD Workflow Reference](/docs/reference/workflows/bmgd-workflows.md) - **Video tutorials** β€” [BMad Code YouTube](https://www.youtube.com/@BMadCode) ## Key Takeaways diff --git a/tools/fix-doc-links.js b/tools/fix-doc-links.js index 34d832d0..dbfcc862 100644 --- a/tools/fix-doc-links.js +++ b/tools/fix-doc-links.js @@ -1,11 +1,13 @@ /** * Fix Documentation Links * - * Converts relative markdown links to site-relative paths. - * - ./file.md β†’ /current/path/file/ - * - ../other/file.md β†’ /resolved/path/file/ - * - /absolute/file.md β†’ /absolute/file/ - * - index.md β†’ parent directory (e.g., /path/index.md β†’ /path/) + * Converts relative markdown links to repo-relative paths with .md extension. + * This ensures links work both in GitHub and on the Astro/Starlight site + * (the rehype plugin transforms /docs/path/file.md β†’ /path/file/ at build time). + * + * - ./file.md β†’ /docs/current/path/file.md + * - ../other/file.md β†’ /docs/resolved/path/file.md + * - /path/file/ β†’ /docs/path/file.md (or /docs/path/file/index.md if it's a directory) * * Usage: * node tools/fix-doc-links.js # Dry run (shows what would change) @@ -18,8 +20,12 @@ const path = require('node:path'); const DOCS_ROOT = path.resolve(__dirname, '../docs'); const DRY_RUN = !process.argv.includes('--write'); -// Regex to match markdown links: [text](path.md) or [text](path.md#anchor) -const MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]+\.md(?:#[^)]*)?(?:\?[^)]*)?)\)/g; +// Regex to match markdown links: +// - [text](path.md) or [text](path.md#anchor) - existing .md links +// - [text](/path/to/page/) or [text](/path/to/page/#anchor) - site-relative links to convert +const MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]+(?:\.md|\/))(?:#[^)]*)?(?:\?[^)]*)?\)/g; +// Simpler approach: match all markdown links and filter in the handler +const ALL_MARKDOWN_LINKS_REGEX = /\[([^\]]*)\]\(([^)]+)\)/g; /** * Get all markdown files in docs directory, excluding _* directories/files @@ -51,16 +57,21 @@ function getMarkdownFiles(dir) { } /** - * Convert a markdown link href to site-relative path + * Convert a markdown link href to repo-relative path with .md extension * - * @param {string} href - The original href (e.g., "./file.md", "../other/file.md#anchor") + * @param {string} href - The original href (e.g., "./file.md", "/path/to/page/", "/path/to/page/#anchor") * @param {string} currentFilePath - Absolute path to the file containing this link - * @returns {string} - Site-relative path (e.g., "/path/to/file/", "/path/to/file/#anchor") + * @returns {string|null} - Repo-relative path (e.g., "/docs/path/to/file.md"), or null if shouldn't be converted */ -function convertToSiteRelative(href, currentFilePath) { +function convertToRepoRelative(href, currentFilePath) { // Skip external links - if (href.includes('://')) { - return href; + if (href.includes('://') || href.startsWith('mailto:') || href.startsWith('tel:')) { + return null; + } + + // Skip anchor-only links + if (href.startsWith('#')) { + return null; } // Extract anchor and query string if present @@ -90,10 +101,27 @@ function convertToSiteRelative(href, currentFilePath) { } } + // Skip non-documentation links (images, external assets, etc.) + const ext = path.extname(pathPortion).toLowerCase(); + if ( + ext && + ext !== '.md' && + !['.md'].includes(ext) && // Has an extension that's not .md - skip unless it's a trailing slash path + !pathPortion.endsWith('/') + ) { + return null; + } + + // Check if original path ends with / (directory reference) BEFORE path.join normalizes it + const isDirectoryPath = pathPortion.endsWith('/'); + let absolutePath; - if (pathPortion.startsWith('/')) { - // Already site-relative - resolve from docs root + if (pathPortion.startsWith('/docs/')) { + // Already repo-relative with /docs/ prefix + absolutePath = path.join(path.dirname(DOCS_ROOT), pathPortion); + } else if (pathPortion.startsWith('/')) { + // Site-relative (e.g., /tutorials/getting-started/) - resolve from docs root absolutePath = path.join(DOCS_ROOT, pathPortion); } else { // Relative path (./, ../, or bare filename) - resolve from current file's directory @@ -101,20 +129,36 @@ function convertToSiteRelative(href, currentFilePath) { absolutePath = path.resolve(currentDir, pathPortion); } - // Convert to site-relative path (relative to docs root) - let siteRelative = '/' + path.relative(DOCS_ROOT, absolutePath); + // Convert to repo-relative path (with /docs/ prefix) + let repoRelative = '/docs/' + path.relative(DOCS_ROOT, absolutePath); // Normalize path separators for Windows - siteRelative = siteRelative.split(path.sep).join('/'); + repoRelative = repoRelative.split(path.sep).join('/'); - // Transform .md to trailing slash - if (siteRelative.endsWith('/index.md')) { - siteRelative = siteRelative.replace(/\/index\.md$/, '/'); - } else if (siteRelative.endsWith('.md')) { - siteRelative = siteRelative.replace(/\.md$/, '/'); + // If original path was a directory reference (ended with /), check for index.md or file.md + if (isDirectoryPath) { + const relativeDir = repoRelative.slice(6); // Remove '/docs/' + + // Handle root path case (relativeDir is empty or just '.') + const normalizedDir = relativeDir === '' || relativeDir === '.' ? '' : relativeDir; + const indexPath = path.join(DOCS_ROOT, normalizedDir, 'index.md'); + const filePath = normalizedDir ? path.join(DOCS_ROOT, normalizedDir + '.md') : null; + + if (fs.existsSync(indexPath)) { + // Avoid double slash when repoRelative is '/docs/' (root case) + repoRelative = repoRelative.endsWith('/') ? repoRelative + 'index.md' : repoRelative + '/index.md'; + } else if (filePath && fs.existsSync(filePath)) { + repoRelative = repoRelative + '.md'; + } else { + // Neither exists - default to index.md and let validation catch it + repoRelative = repoRelative.endsWith('/') ? repoRelative + 'index.md' : repoRelative + '/index.md'; + } + } else if (!repoRelative.endsWith('.md')) { + // Path doesn't end with .md - add .md + repoRelative = repoRelative + '.md'; } - return siteRelative + query + anchor; + return repoRelative + query + anchor; } /** @@ -138,14 +182,14 @@ function processFile(filePath) { }); // Process links only in non-code-block content - contentWithPlaceholders = contentWithPlaceholders.replaceAll(MARKDOWN_LINK_REGEX, (match, linkText, href) => { - // Skip external links - if (href.includes('://')) { + contentWithPlaceholders = contentWithPlaceholders.replaceAll(ALL_MARKDOWN_LINKS_REGEX, (match, linkText, href) => { + const newHref = convertToRepoRelative(href, filePath); + + // Skip if conversion returned null (external link, anchor, etc.) + if (newHref === null) { return match; } - const newHref = convertToSiteRelative(href, filePath); - // Only record as change if actually different if (newHref !== href) { changes.push({ from: href, to: newHref }); @@ -170,21 +214,16 @@ function processFile(filePath) { } /** - * Validate that a site-relative link points to an existing file + * Validate that a repo-relative link points to an existing file */ -function validateLink(siteRelativePath) { - // Strip trailing slash and anchor/query - const checkPath = siteRelativePath.split('#')[0].split('?')[0]; +function validateLink(repoRelativePath) { + // Strip anchor/query + const checkPath = repoRelativePath.split('#')[0].split('?')[0]; - if (checkPath.endsWith('/')) { - // Could be directory/index.md or file.md that became directory/ - const asIndex = path.join(DOCS_ROOT, checkPath, 'index.md'); - const asFile = path.join(DOCS_ROOT, checkPath.slice(0, -1) + '.md'); + // Remove /docs/ prefix to get path relative to DOCS_ROOT + const relativePath = checkPath.startsWith('/docs/') ? checkPath.slice(6) : checkPath.slice(1); - return fs.existsSync(asIndex) || fs.existsSync(asFile); - } - - return fs.existsSync(path.join(DOCS_ROOT, checkPath)); + return fs.existsSync(path.join(DOCS_ROOT, relativePath)); } // Main execution diff --git a/website/src/rehype-markdown-links.js b/website/src/rehype-markdown-links.js index c7e6d0b8..97d8dec3 100644 --- a/website/src/rehype-markdown-links.js +++ b/website/src/rehype-markdown-links.js @@ -6,7 +6,10 @@ * ./path/index.md β†’ ./path/ (index.md becomes directory root) * ../path/file.md#anchor β†’ ../path/file/#anchor * ./file.md?query=param β†’ ./file/?query=param - * /absolute/path/file.md β†’ /absolute/path/file/ + * /docs/absolute/path/file.md β†’ /absolute/path/file/ + * + * For absolute paths starting with /docs/, the /docs prefix is stripped + * since the Astro site serves content from the docs directory as the root. * * Affects relative links (./, ../) and absolute paths (/) - external links are unchanged */ @@ -79,6 +82,11 @@ export default function rehypeMarkdownLinks() { } } + // Strip /docs/ prefix from absolute paths (repo-relative β†’ site-relative) + if (urlPath.startsWith('/docs/')) { + urlPath = urlPath.slice(5); // Remove '/docs' prefix, keeping the leading / + } + // Transform .md to / // Special case: index.md β†’ directory root (e.g., ./tutorials/index.md β†’ ./tutorials/) if (urlPath.endsWith('/index.md')) {