From 7dfbfd9453e24bab377aa0b4dd83a55f46c0368d Mon Sep 17 00:00:00 2001 From: forcetrainer Date: Sat, 3 Jan 2026 01:01:55 -0500 Subject: [PATCH] feat(docs): add Diataxis folder structure and update sidebar styling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create tutorials, how-to, explanation, reference directories with subdirectories - Add index.md files for each main Diataxis section - Update homepage with Diataxis card navigation layout - Implement clean React Native-inspired sidebar styling - Convert sidebar to autogenerated for both Diataxis and legacy sections - Update docusaurus config with dark mode default and navbar changes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/explanation/index.md | 32 +++ docs/how-to/index.md | 31 +++ docs/index.md | 168 ++++++-------- docs/reference/index.md | 23 ++ docs/tutorials/index.md | 20 ++ website/css/custom.css | 418 ++++++++++++++++++++++++++++++++--- website/docusaurus.config.js | 65 ++++-- website/sidebars.js | 165 ++++---------- 8 files changed, 665 insertions(+), 257 deletions(-) create mode 100644 docs/explanation/index.md create mode 100644 docs/how-to/index.md create mode 100644 docs/reference/index.md create mode 100644 docs/tutorials/index.md diff --git a/docs/explanation/index.md b/docs/explanation/index.md new file mode 100644 index 00000000..c0072486 --- /dev/null +++ b/docs/explanation/index.md @@ -0,0 +1,32 @@ +# Explanation + +Understanding-oriented content that explains concepts, architecture, and the reasoning behind BMAD's design. + +## Core Concepts + +Foundational concepts you need to understand BMAD. + +- [What are Agents?](./core-concepts/what-are-agents.md) +- [What are Workflows?](./core-concepts/what-are-workflows.md) +- [What are Modules?](./core-concepts/what-are-modules.md) + +## Architecture + +How BMAD is designed and why. + +## Philosophy + +The thinking behind BMAD's approach. + +## Features + +Deep dives into specific BMAD features. + +- [Party Mode](./features/party-mode.md) +- [Brainstorming Techniques](./features/brainstorming-techniques.md) +- [Advanced Elicitation](./features/advanced-elicitation.md) +- [Web Bundles](./features/web-bundles.md) + +## Modules + +Explanations of BMAD's module ecosystem. diff --git a/docs/how-to/index.md b/docs/how-to/index.md new file mode 100644 index 00000000..4241e400 --- /dev/null +++ b/docs/how-to/index.md @@ -0,0 +1,31 @@ +# How-To Guides + +Task-oriented guides that show you how to accomplish specific goals. Each guide assumes you already understand the basics. + +## Installation + +- [Upgrade to V6](./installation/upgrade-to-v6.md) +- [Install Custom Modules](./installation/install-custom-modules.md) + +## IDE Setup + +*Coming soon* + +## Customization + +- [Customize Agents](./customization/customize-agents.md) +- [Customize Workflows](./customization/customize-workflows.md) +- [Vendor Workflows](./customization/vendor-workflows.md) +- [Shard Large Documents](./customization/shard-large-documents.md) + +## Workflows + +Guides for running specific BMAD workflows. + +## Brownfield Projects + +Working with existing codebases. + +## Troubleshooting + +Solutions to common problems. diff --git a/docs/index.md b/docs/index.md index d9b22a2f..53cc37ea 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,111 +1,85 @@ -# BMAD Documentation +--- +slug: / +sidebar_position: 1 +title: Welcome to BMAD +--- -Complete documentation for the BMAD Method. +# BMAD Method Documentation -## Getting Started - -### New to BMAD? -Start with the core concepts to understand how BMAD works: - -- **[Core Concepts](./bmad-core-concepts/)** - Agents, workflows, and modules explained -- **[Installation Guide](./bmad-core-concepts/installing/)** - Set up BMAD in your project -- **[Quick Start Guide](./modules/bmm-bmad-method/quick-start)** - Build your first feature - -### Upgrading from v4? -- **[v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md)** - Migration path for v4 users +> **Build More, Architect Dreams** — An AI-driven agile development framework with specialized agents, guided workflows, and scale-adaptive intelligence. --- -## Module Documentation +## Choose Your Path -### BMAD Method (BMM) - Software & Game Development - -The flagship module for agile AI-driven development. - -- **[BMM Module Index](./modules/bmm-bmad-method/index)** - Module overview, agents, and documentation - - [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Step-by-step guide - - [Quick Spec Flow](./modules/bmm-bmad-method/quick-spec-flow) - Rapid Level 0-1 development - - [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Working with existing codebases -- **[BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides)** - Essential reading - -### BMAD Builder (BMB) - Create Custom Solutions - -Build your own agents, workflows, and modules. - -- **[BMB Module Overview](./modules/bmb-bmad-builder/index)** - Module overview and capabilities -- **[Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md)** - Create custom agents -- **[Custom Content Installation](./modules/bmb-bmad-builder/custom-content-installation.md)** - Share and install custom creations - -### Creative Intelligence Suite (CIS) - Innovation & Creativity - -- **[CIS Documentation](./modules/cis-creative-intelligence-suite/index)** - -### BMAD Game Dev (BMGD) - -- **[BMGD Documentation](./modules/bmgd-bmad-game-dev/index)** - Game development workflows +
+
+
+
+

Tutorials

+
+
+

Learn BMAD step by step. Start here if you're new.

+
+ +
+
+
+
+
+

How-To Guides

+
+
+

Solve specific problems. Task-focused, practical guides.

+
+ +
+
+
+
+
+

Explanation

+
+
+

Understand the concepts. Why BMAD works the way it does.

+
+ +
+
+
+
+
+

Reference

+
+
+

Look up details. Agents, workflows, configuration options.

+
+ +
+
+
--- -## Core Module +## Quick Links -### Global Core Entities - -- **[Core Module Index](./modules/core/index)** - Shared functionality available to all modules - - [Global Core Config](./modules/core/global-core-config.md) - Inheritable configuration - - [Core Workflows](./modules/core/core-workflows.md) - Domain-agnostic workflows - - [Party Mode](./modules/core/party-mode.md) - Multi-agent conversations - - [Brainstorming](./modules/core/brainstorming.md) - Structured creative sessions - - [Advanced Elicitation](./modules/core/advanced-elicitation.md) - LLM reasoning techniques - - [Core Tasks](./modules/core/core-tasks.md) - Common tasks across modules +- **New to BMAD?** → [Quick Start Tutorial](/docs/tutorials/getting-started/quick-start-bmm) +- **Installing?** → [Installation Guide](/docs/how-to/installation) +- **What are agents?** → [Understanding Agents](/docs/explanation/core-concepts/what-are-agents) +- **Looking for a workflow?** → [Workflow Reference](/docs/reference/workflows) --- -## Advanced Topics +## Community -### Customization - -- **[BMAD Customization](./bmad-core-concepts/bmad-customization/)** - Modify agents and workflows - -### Platform Guides - -- **[Web Bundles](./bmad-core-concepts/web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs - ---- - -## Recommended Reading Paths - -### Path 1: Brand New to BMAD (Software Project) - -1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows -2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD -3. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on -4. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology - -### Path 2: Game Development Project - -1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows -2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD -3. [BMGD Workflows Guide](./modules/bmgd-bmad-game-dev/workflows-guide) - Game-specific workflows - -### Path 3: Upgrading from v4 - -1. [v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md) - Understand what changed -2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Reorient yourself -3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Learn new v6 workflows - -### Path 4: Working with Existing Codebase (Brownfield) - -1. [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Approach for legacy code -2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Follow the process -3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology - -### Path 5: Building Custom Agents - -1. [Core Concepts: Agents](./bmad-core-concepts/agents.md) - Understand Simple vs Expert -2. [Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md) - Build your first agent -3. [Agent Architecture](./modules/bmb-bmad-builder/index) - Deep technical details - -### Path 6: Contributing to BMAD - -1. [CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md) - Contribution guidelines -2. Relevant module README - Understand the area you're contributing to +- [Discord](https://discord.gg/gk8jAdXWmj) — Get help, share ideas +- [GitHub](https://github.com/bmad-code-org/BMAD-METHOD) — Source code, issues +- [YouTube](https://www.youtube.com/@BMadCode) — Video tutorials diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 00000000..39c8e804 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,23 @@ +# Reference + +Information-oriented documentation for looking up facts, specifications, and details. + +## Agents + +Technical reference for all BMAD agents. + +## Workflows + +Technical reference for all BMAD workflows. + +## Configuration + +Configuration options and settings. + +## Glossary + +Definitions of BMAD terminology. + +## FAQ + +Frequently asked questions organized by topic. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 00000000..e92e4d47 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,20 @@ +# Tutorials + +Learning-oriented guides that take you through a series of steps to complete a project. Start here if you're new to BMAD. + +## Getting Started + +- [Quick Start - BMad Method](./getting-started/quick-start-bmm.md) - Get up and running with BMad Method +- [Quick Start - Game Dev](./getting-started/quick-start-bmgd.md) - Get started with BMGD for game development + +## Your First Project + +Step-by-step tutorials for building your first project with BMAD. + +*Coming soon* + +## Advanced Tutorials + +Deep-dive tutorials for experienced users. + +- [Create a Custom Agent](./advanced/create-custom-agent.md) - Build your own specialized agent diff --git a/website/css/custom.css b/website/css/custom.css index 793bfae4..1e876c31 100644 --- a/website/css/custom.css +++ b/website/css/custom.css @@ -1,51 +1,417 @@ /** - * BMAD Documentation Custom Styles + * BMAD Method Documentation - Custom Styles + * Electric Blue theme optimized for dark mode */ +/* ============================================ + COLOR PALETTE - Light Mode + ============================================ */ :root { - --ifm-color-primary: #0d9488; - --ifm-color-primary-dark: #0b847a; - --ifm-color-primary-darker: #0a7d73; - --ifm-color-primary-darkest: #08665f; - --ifm-color-primary-light: #0fa596; - --ifm-color-primary-lighter: #10ac9d; - --ifm-color-primary-lightest: #14c9b8; + --ifm-color-primary: #2563eb; + --ifm-color-primary-dark: #1d4ed8; + --ifm-color-primary-darker: #1e40af; + --ifm-color-primary-darkest: #1e3a8a; + --ifm-color-primary-light: #3b82f6; + --ifm-color-primary-lighter: #60a5fa; + --ifm-color-primary-lightest: #93c5fd; --ifm-code-font-size: 95%; - --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); + --docusaurus-highlighted-code-line-bg: rgba(37, 99, 235, 0.1); } +/* ============================================ + COLOR PALETTE - Dark Mode (Primary Focus) + ============================================ */ [data-theme='dark'] { - --ifm-color-primary: #2dd4bf; - --ifm-color-primary-dark: #1bc4af; - --ifm-color-primary-darker: #1ab9a5; - --ifm-color-primary-darkest: #159888; - --ifm-color-primary-light: #4adcc9; - --ifm-color-primary-lighter: #55dece; - --ifm-color-primary-lightest: #7de7db; - --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); + --ifm-color-primary: #60a5fa; + --ifm-color-primary-dark: #3b82f6; + --ifm-color-primary-darker: #2563eb; + --ifm-color-primary-darkest: #1d4ed8; + --ifm-color-primary-light: #93c5fd; + --ifm-color-primary-lighter: #bfdbfe; + --ifm-color-primary-lightest: #dbeafe; + --docusaurus-highlighted-code-line-bg: rgba(96, 165, 250, 0.15); + + /* Dark mode background refinements */ + --ifm-background-color: #0f172a; + --ifm-background-surface-color: #1e293b; + --ifm-navbar-background-color: #0f172a; + --ifm-footer-background-color: #020617; } -/* Navbar styling */ +/* ============================================ + TYPOGRAPHY + ============================================ */ +:root { + --ifm-font-size-base: 100%; + --ifm-line-height-base: 1.7; + --ifm-heading-font-weight: 600; + --ifm-font-weight-semibold: 600; +} + +.markdown h1 { + margin-bottom: 1.5rem; +} + +.markdown h2 { + margin-top: 2.5rem; + margin-bottom: 1rem; +} + +.markdown h3 { + margin-top: 2rem; + margin-bottom: 0.75rem; +} + +.markdown p { + margin-bottom: 1.25rem; +} + +/* ============================================ + SIDEBAR & NAVIGATION + Clean, React Native-inspired styling + ============================================ */ + +/* Base transition for all sidebar links */ +.menu__link { + transition: background-color 0.15s ease, color 0.15s ease, border-color 0.15s ease; + border-radius: 4px; +} + +/* + * LEVEL 1 - Main Diataxis categories (Tutorials, How-To, Explanation, Reference) + * Bold headers with generous spacing between sections + */ +.theme-doc-sidebar-menu > .menu__list-item { + margin-top: 0.75rem; +} + +.theme-doc-sidebar-menu > .menu__list-item:first-child { + margin-top: 0; +} + +.theme-doc-sidebar-menu > .menu__list-item > .menu__link, +.theme-doc-sidebar-menu > .menu__list-item > .menu__link--sublist-caret { + font-weight: 700; + font-size: 0.9375rem; + color: var(--ifm-font-color-base); + padding: 0.5rem 0.75rem; +} + +.theme-doc-sidebar-menu > .menu__list-item > .menu__link:hover { + background-color: rgba(0, 0, 0, 0.05); +} + +[data-theme='dark'] .theme-doc-sidebar-menu > .menu__list-item > .menu__link:hover { + background-color: rgba(255, 255, 255, 0.05); +} + +/* + * Section index files (first item under each category) + * Should match category header styling - bold, not smaller + */ +.theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item:first-child > .menu__link { + font-weight: 600; + font-size: 0.9375rem; + color: var(--ifm-font-color-base); + padding: 0.5rem 0.75rem; + padding-left: 1.5rem; + border-left: 3px solid transparent; +} + +/* + * LEVEL 2 - Subcategories (Getting Started, Installation, etc.) + * Semi-bold, slightly indented + */ +.theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__link { + font-weight: 500; + font-size: 0.875rem; + color: var(--ifm-color-emphasis-700); + padding: 0.375rem 0.75rem; + padding-left: 1.5rem; + border-left: 3px solid transparent; +} + +.theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__link:hover { + background-color: rgba(0, 0, 0, 0.03); + color: var(--ifm-font-color-base); +} + +[data-theme='dark'] .theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__link { + color: var(--ifm-color-emphasis-500); +} + +[data-theme='dark'] .theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__link:hover { + background-color: rgba(255, 255, 255, 0.03); + color: var(--ifm-color-emphasis-300); +} + +/* + * LEVEL 3+ - Individual docs within subcategories + * Regular weight, more indented + */ +.theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__list .menu__link { + font-weight: 400; + font-size: 0.8125rem; + color: var(--ifm-color-emphasis-600); + padding: 0.3rem 0.75rem; + padding-left: 2.25rem; + border-left: 3px solid transparent; +} + +.theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__list .menu__link:hover { + background-color: rgba(0, 0, 0, 0.03); + color: var(--ifm-color-emphasis-800); +} + +[data-theme='dark'] .theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__list .menu__link { + color: var(--ifm-color-emphasis-600); +} + +[data-theme='dark'] .theme-doc-sidebar-menu > .menu__list-item > .menu__list > .menu__list-item > .menu__list .menu__link:hover { + background-color: rgba(255, 255, 255, 0.03); + color: var(--ifm-color-emphasis-400); +} + +/* + * ACTIVE STATES - Thin left accent bar like React Native docs + */ +.menu__link--active:not(.menu__link--sublist) { + background-color: rgba(37, 99, 235, 0.08) !important; + color: var(--ifm-color-primary) !important; + border-left-color: var(--ifm-color-primary) !important; + font-weight: 600 !important; +} + +[data-theme='dark'] .menu__link--active:not(.menu__link--sublist) { + background-color: rgba(96, 165, 250, 0.1) !important; + color: var(--ifm-color-primary-light) !important; + border-left-color: var(--ifm-color-primary-light) !important; +} + +/* Category headers when expanded - subtle indication */ +.theme-doc-sidebar-menu > .menu__list-item > .menu__link--sublist.menu__link--active { + color: var(--ifm-font-color-base); +} + +[data-theme='dark'] .theme-doc-sidebar-menu > .menu__list-item > .menu__link--sublist.menu__link--active { + color: var(--ifm-color-emphasis-200); +} + +/* ============================================ + NAVBAR + ============================================ */ .navbar { - box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.1); + padding: 0.75rem 1rem; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); } -/* Footer styling */ -.footer { - background-color: var(--ifm-color-primary-darkest); +.navbar__title { + font-weight: 700; } -/* Code block improvements */ -.prism-code { - font-size: 0.9rem; +.navbar__link { + font-weight: 500; + font-size: 0.95rem; + padding: 0.5rem 0.875rem; + margin: 0 0.125rem; + border-radius: 6px; + transition: background-color 0.15s ease, color 0.15s ease; } -/* Table improvements */ +.navbar__link:hover { + color: var(--ifm-color-primary); + background-color: rgba(0, 0, 0, 0.05); +} + +.navbar__link--active { + font-weight: 600; +} + +[data-theme='dark'] .navbar { + box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3); +} + +[data-theme='dark'] .navbar__link:hover { + background-color: rgba(255, 255, 255, 0.05); +} + +/* Social icon links */ +.navbar__link--discord, +.navbar__link--github { + display: flex; + align-items: center; + padding: 0.5rem; +} + +.navbar__link--discord::before, +.navbar__link--github::before { + content: ''; + width: 24px; + height: 24px; + display: block; + background-size: contain; + background-repeat: no-repeat; + background-position: center; +} + +.navbar__link--discord::before { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 127.14 96.36'%3E%3Cpath fill='%2364748b' d='M107.7 8.07A105.15 105.15 0 0 0 81.47 0a72.06 72.06 0 0 0-3.36 6.83 97.68 97.68 0 0 0-29.11 0A72.37 72.37 0 0 0 45.64 0a105.89 105.89 0 0 0-26.25 8.09C2.79 32.65-1.71 56.6.54 80.21a105.73 105.73 0 0 0 32.17 16.15 77.7 77.7 0 0 0 6.89-11.11 68.42 68.42 0 0 1-10.85-5.18c.91-.66 1.8-1.34 2.66-2a75.57 75.57 0 0 0 64.32 0c.87.71 1.76 1.39 2.66 2a68.68 68.68 0 0 1-10.87 5.19 77 77 0 0 0 6.89 11.1 105.25 105.25 0 0 0 32.19-16.14c2.64-27.38-4.51-51.11-18.9-72.15ZM42.45 65.69C36.18 65.69 31 60 31 53s5-12.74 11.43-12.74S54 46 53.89 53s-5.05 12.69-11.44 12.69Zm42.24 0C78.41 65.69 73.25 60 73.25 53s5-12.74 11.44-12.74S96.23 46 96.12 53s-5.04 12.69-11.43 12.69Z'/%3E%3C/svg%3E"); +} + +.navbar__link--github::before { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%2364748b' d='M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z'/%3E%3C/svg%3E"); +} + +.navbar__link--discord:hover::before { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 127.14 96.36'%3E%3Cpath fill='%235865F2' d='M107.7 8.07A105.15 105.15 0 0 0 81.47 0a72.06 72.06 0 0 0-3.36 6.83 97.68 97.68 0 0 0-29.11 0A72.37 72.37 0 0 0 45.64 0a105.89 105.89 0 0 0-26.25 8.09C2.79 32.65-1.71 56.6.54 80.21a105.73 105.73 0 0 0 32.17 16.15 77.7 77.7 0 0 0 6.89-11.11 68.42 68.42 0 0 1-10.85-5.18c.91-.66 1.8-1.34 2.66-2a75.57 75.57 0 0 0 64.32 0c.87.71 1.76 1.39 2.66 2a68.68 68.68 0 0 1-10.87 5.19 77 77 0 0 0 6.89 11.1 105.25 105.25 0 0 0 32.19-16.14c2.64-27.38-4.51-51.11-18.9-72.15ZM42.45 65.69C36.18 65.69 31 60 31 53s5-12.74 11.43-12.74S54 46 53.89 53s-5.05 12.69-11.44 12.69Zm42.24 0C78.41 65.69 73.25 60 73.25 53s5-12.74 11.44-12.74S96.23 46 96.12 53s-5.04 12.69-11.43 12.69Z'/%3E%3C/svg%3E"); +} + +.navbar__link--github:hover::before { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%2360a5fa' d='M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z'/%3E%3C/svg%3E"); +} + +[data-theme='dark'] .navbar__link--discord::before { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 127.14 96.36'%3E%3Cpath fill='%2394a3b8' d='M107.7 8.07A105.15 105.15 0 0 0 81.47 0a72.06 72.06 0 0 0-3.36 6.83 97.68 97.68 0 0 0-29.11 0A72.37 72.37 0 0 0 45.64 0a105.89 105.89 0 0 0-26.25 8.09C2.79 32.65-1.71 56.6.54 80.21a105.73 105.73 0 0 0 32.17 16.15 77.7 77.7 0 0 0 6.89-11.11 68.42 68.42 0 0 1-10.85-5.18c.91-.66 1.8-1.34 2.66-2a75.57 75.57 0 0 0 64.32 0c.87.71 1.76 1.39 2.66 2a68.68 68.68 0 0 1-10.87 5.19 77 77 0 0 0 6.89 11.1 105.25 105.25 0 0 0 32.19-16.14c2.64-27.38-4.51-51.11-18.9-72.15ZM42.45 65.69C36.18 65.69 31 60 31 53s5-12.74 11.43-12.74S54 46 53.89 53s-5.05 12.69-11.44 12.69Zm42.24 0C78.41 65.69 73.25 60 73.25 53s5-12.74 11.44-12.74S96.23 46 96.12 53s-5.04 12.69-11.43 12.69Z'/%3E%3C/svg%3E"); +} + +[data-theme='dark'] .navbar__link--github::before { + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%2394a3b8' d='M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z'/%3E%3C/svg%3E"); +} + +/* ============================================ + CARDS (Welcome page) + ============================================ */ + +/* Equal height cards */ +.row:has(.card) { + display: flex; + flex-wrap: wrap; +} + +.row:has(.card) > [class*="col"] { + display: flex; +} + +.card { + border-radius: 12px; + border: 2px solid var(--ifm-color-emphasis-300); + background-color: var(--ifm-background-color); + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08); + transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease; + display: flex; + flex-direction: column; + width: 100%; +} + +.card__body { + flex: 1; +} + +.card:hover { + transform: translateY(-3px); + border-color: var(--ifm-color-primary); + box-shadow: 0 8px 24px rgba(37, 99, 235, 0.15); +} + +.card__header h3 { + font-size: 1.25rem; + font-weight: 600; + margin: 0; +} + +.card__body { + color: var(--ifm-color-emphasis-700); +} + +.card__footer { + padding-top: 0; +} + +[data-theme='dark'] .card { + background: linear-gradient( + 145deg, + rgba(30, 41, 59, 0.6), + rgba(15, 23, 42, 0.8) + ); + border-color: rgba(96, 165, 250, 0.2); + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3); +} + +[data-theme='dark'] .card:hover { + border-color: rgba(96, 165, 250, 0.5); + box-shadow: + 0 8px 32px rgba(96, 165, 250, 0.2), + 0 0 0 1px rgba(96, 165, 250, 0.1); +} + +[data-theme='dark'] .card__body { + color: var(--ifm-color-emphasis-500); +} + +/* ============================================ + BUTTONS + ============================================ */ +.button--primary { + transition: background-color 0.2s ease, transform 0.1s ease; +} + +.button--primary:hover { + transform: translateY(-1px); +} + +[data-theme='dark'] .button--primary { + background-color: var(--ifm-color-primary-dark); +} + +[data-theme='dark'] .button--primary:hover { + background-color: var(--ifm-color-primary); +} + +/* ============================================ + MISC ENHANCEMENTS + ============================================ */ + +/* Smooth scrolling */ +html { + scroll-behavior: smooth; +} + +/* Better link underlines */ +.markdown a:not(.hash-link) { + text-decoration-thickness: 1px; + text-underline-offset: 2px; +} + +/* Table styling */ table { display: table; width: 100%; } +[data-theme='dark'] table { + border-color: rgba(96, 165, 250, 0.1); +} + +[data-theme='dark'] table th { + background-color: rgba(96, 165, 250, 0.05); +} + +[data-theme='dark'] table tr:nth-child(2n) { + background-color: rgba(96, 165, 250, 0.02); +} + +/* Blockquotes */ +blockquote { + border-left-color: var(--ifm-color-primary); + background-color: rgba(96, 165, 250, 0.05); + border-radius: 0 8px 8px 0; + padding: 1rem 1.25rem; +} + +[data-theme='dark'] blockquote { + background-color: rgba(96, 165, 250, 0.05); +} + /* Admonition improvements */ .admonition { margin-bottom: 1.5rem; diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 64ca192c..446c5447 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -90,7 +90,8 @@ const config = { ({ docs: { sidebarPath: path.resolve(__dirname, 'sidebars.js'), - exclude: ['**/templates/**', '**/reference/**', 'installers-bundlers/**', '**/images/**'], + // Note: removed '**/reference/**' since we now use reference/ for Diataxis structure + exclude: ['**/templates/**', 'installers-bundlers/**', '**/images/**'], }, blog: false, pages: { @@ -114,10 +115,28 @@ const config = { }, items: [ { - type: 'docSidebar', - sidebarId: 'mainSidebar', + type: 'doc', + docId: 'tutorials/index', position: 'left', - label: 'Docs', + label: 'Tutorials', + }, + { + type: 'doc', + docId: 'how-to/index', + position: 'left', + label: 'How-To', + }, + { + type: 'doc', + docId: 'explanation/index', + position: 'left', + label: 'Concepts', + }, + { + type: 'doc', + docId: 'reference/index', + position: 'left', + label: 'Reference', }, { to: '/downloads', @@ -130,9 +149,16 @@ const config = { position: 'right', }, { - href: 'https://github.com/bmad-code-org/BMAD-METHOD', - label: 'GitHub', + href: 'https://discord.gg/gk8jAdXWmj', + 'aria-label': 'Discord', position: 'right', + className: 'navbar__link--discord', + }, + { + href: 'https://github.com/bmad-code-org/BMAD-METHOD', + 'aria-label': 'GitHub', + position: 'right', + className: 'navbar__link--github', }, ], }, @@ -140,36 +166,41 @@ const config = { style: 'dark', links: [ { - title: 'Docs', + title: 'Documentation', items: [ - { label: 'Quick Start', to: '/docs/modules/bmm/quick-start' }, - { label: 'Installation', to: '/docs/getting-started/installation' }, + { label: 'Tutorials', to: '/docs/tutorials' }, + { label: 'How-To Guides', to: '/docs/how-to' }, + { label: 'Concepts', to: '/docs/explanation' }, + { label: 'Reference', to: '/docs/reference' }, ], }, { title: 'Community', - items: [{ label: 'Discord', href: 'https://discord.gg/bmad' }], + items: [ + { label: 'Discord', href: 'https://discord.gg/gk8jAdXWmj' }, + { label: 'GitHub Discussions', href: 'https://github.com/bmad-code-org/BMAD-METHOD/discussions' }, + { label: 'YouTube', href: 'https://www.youtube.com/@BMadCode' }, + ], }, { title: 'More', items: [ - { - label: 'GitHub', - href: 'https://github.com/bmad-code-org/BMAD-METHOD', - }, + { label: 'GitHub', href: 'https://github.com/bmad-code-org/BMAD-METHOD' }, + { label: 'npm', href: 'https://www.npmjs.com/package/bmad-method' }, { label: 'llms.txt', href: 'pathname:///llms.txt' }, { label: 'llms-full.txt', href: 'pathname:///llms-full.txt' }, ], }, ], - copyright: `Copyright © ${new Date().getFullYear()} BMAD Code Organization.`, + copyright: `Copyright © ${new Date().getFullYear()} BMad Code, LLC. Built with Docusaurus.`, }, prism: { theme: prismThemes.github, - darkTheme: prismThemes.dracula, + darkTheme: prismThemes.vsDark, + additionalLanguages: ['bash', 'yaml', 'json'], }, colorMode: { - defaultMode: 'light', + defaultMode: 'dark', disableSwitch: false, respectPrefersColorScheme: true, }, diff --git a/website/sidebars.js b/website/sidebars.js index aa6b183a..9afed797 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -2,131 +2,62 @@ const sidebars = { mainSidebar: [ 'index', + + // ========================================== + // DIATAXIS STRUCTURE (Autogenerated) + // Just drop files in folders - sidebar updates automatically + // Use _category_.json in folders to control labels/order + // Use sidebar_position in frontmatter to order files + // ========================================== + { + type: 'category', + label: 'Tutorials', + collapsed: false, + link: { type: 'doc', id: 'tutorials/index' }, + items: [{ type: 'autogenerated', dirName: 'tutorials' }], + }, + { + type: 'category', + label: 'How-To Guides', + collapsed: false, + link: { type: 'doc', id: 'how-to/index' }, + items: [{ type: 'autogenerated', dirName: 'how-to' }], + }, + { + type: 'category', + label: 'Explanation', + collapsed: false, + link: { type: 'doc', id: 'explanation/index' }, + items: [{ type: 'autogenerated', dirName: 'explanation' }], + }, + { + type: 'category', + label: 'Reference', + collapsed: false, + link: { type: 'doc', id: 'reference/index' }, + items: [{ type: 'autogenerated', dirName: 'reference' }], + }, + + // ========================================== + // LEGACY STRUCTURE (Being Migrated) + // Remove sections as they become empty + // ========================================== + { + type: 'html', + value: + '
Legacy to be migrated
', + }, { type: 'category', label: 'Core Concepts', - items: [ - 'bmad-core-concepts/index', - 'bmad-core-concepts/agents', - 'bmad-core-concepts/workflows', - 'bmad-core-concepts/modules', - { - type: 'category', - label: 'Installing', - collapsed: true, - items: ['bmad-core-concepts/installing/index', 'bmad-core-concepts/installing/upgrading'], - }, - { - type: 'category', - label: 'Customization', - collapsed: true, - items: [ - 'bmad-core-concepts/bmad-customization/index', - 'bmad-core-concepts/bmad-customization/agents', - 'bmad-core-concepts/bmad-customization/workflows', - ], - }, - 'bmad-core-concepts/web-bundles/index', - ], - }, - { - type: 'category', - label: 'BMM - Method', - items: [ - 'modules/bmm-bmad-method/index', - 'modules/bmm-bmad-method/quick-start', - { - type: 'category', - label: 'Quick Flows', - collapsed: true, - items: [ - 'modules/bmm-bmad-method/bmad-quick-flow', - 'modules/bmm-bmad-method/quick-flow-solo-dev', - 'modules/bmm-bmad-method/quick-spec-flow', - ], - }, - { - type: 'category', - label: 'Workflows', - collapsed: true, - items: [ - 'modules/bmm-bmad-method/workflows-planning', - 'modules/bmm-bmad-method/workflows-solutioning', - 'modules/bmm-bmad-method/workflows-analysis', - 'modules/bmm-bmad-method/workflows-implementation', - ], - }, - { - type: 'category', - label: 'Advanced Topics', - collapsed: true, - items: [ - 'modules/bmm-bmad-method/party-mode', - 'modules/bmm-bmad-method/agents-guide', - 'modules/bmm-bmad-method/brownfield-guide', - 'modules/bmm-bmad-method/test-architecture', - ], - }, - { - type: 'category', - label: 'Reference', - collapsed: true, - items: [ - 'modules/bmm-bmad-method/workflow-document-project-reference', - 'modules/bmm-bmad-method/troubleshooting', - 'modules/bmm-bmad-method/faq', - 'modules/bmm-bmad-method/glossary', - ], - }, - ], - }, - { - type: 'category', - label: 'BMB - Builder', collapsed: true, - items: [ - 'modules/bmb-bmad-builder/index', - 'modules/bmb-bmad-builder/agent-creation-guide', - 'modules/bmb-bmad-builder/workflow-vendoring-customization-inheritance', - 'modules/bmb-bmad-builder/custom-content', - 'modules/bmb-bmad-builder/custom-content-installation', - ], + items: [{ type: 'autogenerated', dirName: 'bmad-core-concepts' }], }, { type: 'category', - label: 'BMGD - Game Dev', + label: 'Modules', collapsed: true, - items: [ - 'modules/bmgd-bmad-game-dev/index', - 'modules/bmgd-bmad-game-dev/quick-start', - 'modules/bmgd-bmad-game-dev/quick-flow-guide', - 'modules/bmgd-bmad-game-dev/agents-guide', - 'modules/bmgd-bmad-game-dev/workflows-guide', - 'modules/bmgd-bmad-game-dev/game-types-guide', - 'modules/bmgd-bmad-game-dev/troubleshooting', - 'modules/bmgd-bmad-game-dev/glossary', - ], - }, - { - type: 'category', - label: 'CIS - Creative Intelligence', - collapsed: true, - items: ['modules/cis-creative-intelligence-suite/index'], - }, - { - type: 'category', - label: 'Core Module', - collapsed: true, - items: [ - 'modules/core/index', - 'modules/core/party-mode', - 'modules/core/core-tasks', - 'modules/core/core-workflows', - 'modules/core/advanced-elicitation', - 'modules/core/brainstorming', - 'modules/core/document-sharding-guide', - 'modules/core/global-core-config', - ], + items: [{ type: 'autogenerated', dirName: 'modules' }], }, ], };