Restructure docs IA

src/components/overrides/Sidebar.astro

@@ -1,18 +1,69 @@
 ---
 /**
  * Custom Sidebar component that mimics MkDocs Material theme's navigation.sections behavior.
+ * Includes an API language switcher (Python/TypeScript) that only appears on API pages.
  */
 import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
 import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
 import SidebarSublist from './SidebarSublist.astro';
+import { pathWithBase } from '../../util/links';
 
-const { sidebar } = Astro.locals.starlightRoute;
+const { sidebar, id: currentSlug } = Astro.locals.starlightRoute;
+const isApiPage = currentSlug.startsWith('docs/api/');
+const isPython = currentSlug.startsWith('docs/api/python');
 ---
 
 <SidebarPersister>
+  {isApiPage && (
+    <div class="api-lang-switcher">
+      <a
+        href={pathWithBase('/docs/api/python/')}
+        class:list={['api-lang-tab', { active: isPython }]}
+      >Python</a>
+      <a
+        href={pathWithBase('/docs/api/typescript/')}
+        class:list={['api-lang-tab', { active: !isPython }]}
+      >TypeScript</a>
+    </div>
+  )}
   <SidebarSublist sublist={sidebar} />
 </SidebarPersister>
 
 <div class="md:sl-hidden">
   <MobileMenuFooter />
 </div>
+
+<style>
+  .api-lang-switcher {
+    display: flex;
+    gap: 0;
+    margin-bottom: 1rem;
+    border: 1px solid var(--sl-color-hairline-light);
+    border-radius: 6px;
+    overflow: hidden;
+  }
+
+  .api-lang-tab {
+    flex: 1;
+    text-align: center;
+    padding: 0.4rem 0.75rem;
+    font-size: var(--sl-text-sm);
+    font-weight: 500;
+    text-decoration: none;
+    color: var(--sl-color-gray-2);
+    background: transparent;
+    transition: all 0.15s ease;
+    border: none;
+  }
+
+  .api-lang-tab:hover {
+    color: var(--sl-color-white);
+    background: var(--sl-color-gray-6);
+  }
+
+  .api-lang-tab.active {
+    color: var(--sl-color-text-invert);
+    background: var(--sl-color-accent);
+    font-weight: 600;
+  }
+</style>

src/config/navbar.ts

@@ -20,6 +20,12 @@ export interface NavLink {
    * Example: href="/user-guide/quickstart/" but basePath="/user-guide/"
    */
   basePath?: string
+  /**
+   * Additional base paths that should also be considered part of this nav section.
+   * Useful when a nav item encompasses multiple top-level sidebar sections.
+   * Example: Community nav item also covers /docs/labs/ and /docs/contribute/
+   */
+  additionalBasePaths?: string[]
   /** Set to true for external links (opens in new tab) */
   external?: boolean
 }
@@ -54,6 +60,7 @@ function transformNavLinks(links: NavLink[]): NavLink[] {
       ...link,
       href: withBase(link.href),
       ...(link.basePath ? { basePath: withBase(link.basePath) } : {}),
+      ...(link.additionalBasePaths ? { additionalBasePaths: link.additionalBasePaths.map(withBase) } : {}),
     }
   })
 }

src/config/navigation.yml

@@ -12,84 +12,71 @@
 navbar:
   - label: Home
     href: /
-  - label: User Guide
-    href: /docs/user-guide/quickstart/overview/
+  - label: Docs
+    href: /docs/user-guide/quickstart/python/
     basePath: /docs/user-guide/
   - label: Examples
     href: /docs/examples/
     basePath: /docs/examples/
   - label: Community
     href: /docs/community/community-packages/
     basePath: /docs/community/
-  - label: Labs
-    href: /docs/labs/
-    basePath: /docs/labs/
-  - label: Blog
-    href: /blog/
-    basePath: /blog/
-  - label: Contribute ❤️
-    href: /docs/contribute/
-    basePath: /docs/contribute/
-  - label: Python API
+    additionalBasePaths:
+      - /docs/labs/
+      - /docs/contribute/
+  - label: API Reference
     href: /docs/api/python/
-    basePath: /docs/api/python/
-  - label: TypeScript API
-    href: /docs/api/typescript/
-    basePath: /docs/api/typescript/
+    basePath: /docs/api/
 
 sidebar:
-  - label: User Guide
+  - label: Docs
     items:
       - docs/index
-      - label: Quickstart
+      - label: Get Started
         items:
           - docs/user-guide/quickstart/overview
-          - docs/user-guide/quickstart/python
-          - docs/user-guide/quickstart/typescript
+          - label: "Quickstart: Python"
+            slug: docs/user-guide/quickstart/python
+          - label: "Quickstart: TypeScript"
+            slug: docs/user-guide/quickstart/typescript
       - docs/user-guide/build-with-ai
+      - label: Build
+        items:
+          - label: "Adding Tools"
+            slug: docs/user-guide/concepts/tools
+          - label: "Creating Custom Tools"
+            slug: docs/user-guide/concepts/tools/custom-tools
+          - label: "Using MCP Tools"
+            slug: docs/user-guide/concepts/tools/mcp-tools
+          - label: "Multi-Agent Systems"
+            slug: docs/user-guide/concepts/multi-agent/multi-agent-patterns
+          - label: "Structured Output"
+            slug: docs/user-guide/concepts/agents/structured-output
+          - label: "Streaming Responses"
+            slug: docs/user-guide/concepts/streaming
+          - label: "Voice & Realtime"
+            slug: docs/user-guide/concepts/bidirectional-streaming/quickstart
       - label: Concepts
         items:
-          - label: Agents
-            items:
-              - docs/user-guide/concepts/agents/agent-loop
-              - docs/user-guide/concepts/agents/state
-              - docs/user-guide/concepts/agents/session-management
-              - docs/user-guide/concepts/agents/prompts
-              - docs/user-guide/concepts/agents/retry-strategies
-              - docs/user-guide/concepts/agents/hooks
-              - docs/user-guide/concepts/agents/structured-output
-              - docs/user-guide/concepts/agents/conversation-management
+          - docs/user-guide/concepts/agents/agent-loop
+          - docs/user-guide/concepts/agents/state
+          - docs/user-guide/concepts/agents/session-management
+          - docs/user-guide/concepts/agents/prompts
+          - docs/user-guide/concepts/agents/hooks
+          - docs/user-guide/concepts/agents/conversation-management
+          - docs/user-guide/concepts/agents/retry-strategies
+          - docs/user-guide/concepts/interrupts
           - label: Tools
             items:
-              - docs/user-guide/concepts/tools
-              - docs/user-guide/concepts/tools/custom-tools
-              - docs/user-guide/concepts/tools/mcp-tools
               - docs/user-guide/concepts/tools/executors
               - docs/user-guide/concepts/tools/community-tools-package
           - label: Plugins
             items:
               - docs/user-guide/concepts/plugins
               - docs/user-guide/concepts/plugins/skills
               - docs/user-guide/concepts/plugins/steering
-          - label: Model Providers
-            items:
-              - docs/user-guide/concepts/model-providers
-              - docs/user-guide/concepts/model-providers/amazon-bedrock
-              - docs/user-guide/concepts/model-providers/amazon-nova
-              - docs/user-guide/concepts/model-providers/anthropic
-              - docs/user-guide/concepts/model-providers/gemini
-              - docs/user-guide/concepts/model-providers/litellm
-              - docs/user-guide/concepts/model-providers/llamacpp
-              - docs/user-guide/concepts/model-providers/llamaapi
-              - docs/user-guide/concepts/model-providers/mistral
-              - docs/user-guide/concepts/model-providers/ollama
-              - docs/user-guide/concepts/model-providers/openai
-              - docs/user-guide/concepts/model-providers/sagemaker
-              - docs/user-guide/concepts/model-providers/writer
-              - docs/user-guide/concepts/model-providers/custom_model_provider
           - label: Streaming
             items:
-              - docs/user-guide/concepts/streaming
               - docs/user-guide/concepts/streaming/async-iterators
               - docs/user-guide/concepts/streaming/callback-handlers
           - label: Multi-agent
@@ -99,11 +86,8 @@ sidebar:
               - docs/user-guide/concepts/multi-agent/swarm
               - docs/user-guide/concepts/multi-agent/graph
               - docs/user-guide/concepts/multi-agent/workflow
-              - docs/user-guide/concepts/multi-agent/multi-agent-patterns
-          - docs/user-guide/concepts/interrupts
           - label: Bidirectional Streaming
             items:
-              - docs/user-guide/concepts/bidirectional-streaming/quickstart
               - docs/user-guide/concepts/bidirectional-streaming/agent
               - label: Models
                 items:
@@ -118,6 +102,47 @@ sidebar:
           - label: Experimental
             items:
               - docs/user-guide/concepts/experimental/agent-config
+      - label: Model Providers
+        items:
+          - docs/user-guide/concepts/model-providers
+          - docs/user-guide/concepts/model-providers/amazon-bedrock
+          - docs/user-guide/concepts/model-providers/amazon-nova
+          - docs/user-guide/concepts/model-providers/anthropic
+          - docs/user-guide/concepts/model-providers/gemini
+          - docs/user-guide/concepts/model-providers/litellm
+          - docs/user-guide/concepts/model-providers/llamacpp
+          - docs/user-guide/concepts/model-providers/llamaapi
+          - docs/user-guide/concepts/model-providers/mistral
+          - docs/user-guide/concepts/model-providers/ollama
+          - docs/user-guide/concepts/model-providers/openai
+          - docs/user-guide/concepts/model-providers/sagemaker
+          - docs/user-guide/concepts/model-providers/writer
+          - docs/user-guide/concepts/model-providers/custom_model_provider
+          - docs/user-guide/concepts/model-providers/cohere
+          - docs/user-guide/concepts/model-providers/clova-studio
+          - docs/user-guide/concepts/model-providers/fireworksai
+          - docs/user-guide/concepts/model-providers/nebius-token-factory
+          - docs/user-guide/concepts/model-providers/xai
+      - label: Deploy
+        items:
+          - docs/user-guide/deploy/operating-agents-in-production
+          - label: Amazon Bedrock AgentCore
+            items:
+              - docs/user-guide/deploy/deploy_to_bedrock_agentcore
+              - docs/user-guide/deploy/deploy_to_bedrock_agentcore/python
+              - docs/user-guide/deploy/deploy_to_bedrock_agentcore/typescript
+          - docs/user-guide/deploy/deploy_to_aws_lambda
+          - docs/user-guide/deploy/deploy_to_aws_fargate
+          - docs/user-guide/deploy/deploy_to_aws_apprunner
+          - docs/user-guide/deploy/deploy_to_amazon_eks
+          - docs/user-guide/deploy/deploy_to_amazon_ec2
+          - label: Docker
+            items:
+              - docs/user-guide/deploy/deploy_to_docker
+              - docs/user-guide/deploy/deploy_to_docker/python
+              - docs/user-guide/deploy/deploy_to_docker/typescript
+          - docs/user-guide/deploy/deploy_to_kubernetes
+          - docs/user-guide/deploy/deploy_to_terraform
       - label: Safety & Security
         items:
           - docs/user-guide/safety-security/responsible-ai
@@ -155,26 +180,6 @@ sidebar:
             items:
               - docs/user-guide/evals-sdk/how-to/experiment_management
               - docs/user-guide/evals-sdk/how-to/serialization
-      - label: Deploy
-        items:
-          - docs/user-guide/deploy/operating-agents-in-production
-          - label: Amazon Bedrock AgentCore
-            items:
-              - docs/user-guide/deploy/deploy_to_bedrock_agentcore
-              - docs/user-guide/deploy/deploy_to_bedrock_agentcore/python
-              - docs/user-guide/deploy/deploy_to_bedrock_agentcore/typescript
-          - docs/user-guide/deploy/deploy_to_aws_lambda
-          - docs/user-guide/deploy/deploy_to_aws_fargate
-          - docs/user-guide/deploy/deploy_to_aws_apprunner
-          - docs/user-guide/deploy/deploy_to_amazon_eks
-          - docs/user-guide/deploy/deploy_to_amazon_ec2
-          - label: Docker
-            items:
-              - docs/user-guide/deploy/deploy_to_docker
-              - docs/user-guide/deploy/deploy_to_docker/python
-              - docs/user-guide/deploy/deploy_to_docker/typescript
-          - docs/user-guide/deploy/deploy_to_kubernetes
-          - docs/user-guide/deploy/deploy_to_terraform
       - docs/user-guide/versioning-and-support
 
   - label: Examples
@@ -229,25 +234,23 @@ sidebar:
           - docs/community/tools/strands-teams
           - docs/community/tools/strands-telegram
           - docs/community/tools/strands-telegram-listener
-
-  - label: Labs
-    items:
-      - docs/labs
-      - label: Projects
+      - label: Labs
         items:
-          - docs/labs/robots
-          - docs/labs/robots-sim
-          - docs/labs/ai-functions
-
-  - label: Contribute ❤️
-    items:
-      - docs/contribute
-      - label: Contribution Types
+          - docs/labs
+          - label: Projects
+            items:
+              - docs/labs/robots
+              - docs/labs/robots-sim
+              - docs/labs/ai-functions
+      - label: Contribute
         items:
-          - docs/contribute/contributing/core-sdk
-          - docs/contribute/contributing/documentation
-          - docs/contribute/contributing/feature-proposals
-          - docs/contribute/contributing/extensions
+          - docs/contribute
+          - label: Contribution Types
+            items:
+              - docs/contribute/contributing/core-sdk
+              - docs/contribute/contributing/documentation
+              - docs/contribute/contributing/feature-proposals
+              - docs/contribute/contributing/extensions
 
 github:
   sections:

src/pages/index.astro

@@ -80,7 +80,7 @@ const testimonials = await Promise.all(
           <span class="hero-highlight">in a few lines of code</span>
         </h1>
         <div class="hero-cta">
-          <a href={withBase('/docs/user-guide/quickstart/overview/')} class="cta-button primary">Get Started</a>
+          <a href={withBase('/docs/user-guide/quickstart/python/')} class="cta-button primary">Get Started</a>
         </div>
       </div>
     </section>

src/pages/llms.txt.ts

@@ -6,7 +6,7 @@ import { loadSidebarFromConfig, type StarlightSidebarItem } from '../sidebar'
 import path from 'node:path'
 
 // Sections to pull from sidebar (with their nav labels)
-const SIDEBAR_SECTIONS = ['User Guide', 'Examples', 'Community']
+const SIDEBAR_SECTIONS = ['Docs', 'Examples', 'Community']
 
 /**
  * Recursively extract links from sidebar items