Transition sidebar to astro

[zastrowm]

Overview

Transition the sidebar and navbar configuration from mkdocs.yml to a new Astro-native YAML configuration file. This will complete the migration from MkDocs to Astro/Starlight by removing the legacy dependency on mkdocs.yml.

Background

The repository has transitioned from MkDocs to Astro/Starlight, but the sidebar navigation is still being read from mkdocs.yml via src/sidebar.ts. The top-nav is separately configured in src/config/navbar.ts. This task consolidates both into a single, cleaner YAML configuration.

---

Implementation Requirements

1. Create New Configuration File

File: src/config/navigation.yml

Create a new YAML configuration that combines:

• Navbar links (currently in src/config/navbar.ts)
• Sidebar structure (currently in mkdocs.yml nav section)
• GitHub dropdown sections (currently in src/config/navbar.ts)

Simplified structure (files only need slugs, not labels - labels come from frontmatter):

navbar:
  - label: Home
    href: /
  - label: User Guide
    href: /docs/user-guide/quickstart/overview/
    basePath: /docs/user-guide/
  - label: Examples
    href: /docs/examples/
    basePath: /docs/examples/
  # ... remaining nav items

sidebar:
  - label: User Guide
    items:
      - docs/index  # slug only - label from frontmatter
      - label: Quickstart
        items:
          - docs/user-guide/quickstart/overview
          - docs/user-guide/quickstart/python
          - docs/user-guide/quickstart/typescript
      - label: Concepts
        items:
          - label: Agents
            items:
              - docs/user-guide/concepts/agents/agent-loop
              # ... etc
      # ... etc
  - label: Examples
    items:
      - docs/examples
      # ... etc
  # ... remaining sidebar sections

github:
  sections:
    - title: SDKs
      links:
        - label: sdk-python
          href: https://github.com/strands-agents/sdk-python
          icon: PY
        - label: sdk-typescript  
          href: https://github.com/strands-agents/sdk-typescript
          icon: TS
    - title: Organizations
      links:
        - label: strands-agents
          href: https://github.com/strands-agents
        - label: strands-labs
          href: https://github.com/strands-labs

2. Update Sidebar Loading Logic

File: src/sidebar.ts

• Replace loadSidebarFromMkdocs() with loadSidebarFromConfig() (or similar)
• Read from src/config/navigation.yml instead of mkdocs.yml
• Simplify conversion logic since badges are no longer in config
• Remove getCommunityLabeledFiles() and getSidebarLabels() functions (badges now come from frontmatter only)

3. Update Navbar Configuration

File: src/config/navbar.ts

• Update to read navbar links from navigation.yml
• Update to read GitHub sections from navigation.yml
• Keep TypeScript interfaces (NavLink, GitHubSection, etc.)
• Export processed data for use in Header component

4. Update Astro Config

File: astro.config.mjs

• Update import to use new sidebar loading function
• Remove any mkdocs.yml references

5. Update Tests

File: test/sidebar.test.ts

• Update to test new configuration format
• Update path references from mkdocs.yml to navigation.yml
• Remove tests for getCommunityLabeledFiles and getSidebarLabels if those functions are removed
• Ensure all existing functionality is covered

6. Clean Up Scripts

File: scripts/update-docs.ts

• Remove MKDOCS_VARIABLES constant (no longer needed)
• Remove any references to mkdocs.yml
• Update or remove MKDOCS_PATH constant

7. Delete Legacy File

Delete: mkdocs.yml

Remove the file after all dependencies have been migrated.

8. Update Documentation

Update references to mkdocs.yml in:

• AGENTS.md - Update directory structure and workflow sections
• CONTRIBUTING.md - Update "Writing Docs" section
• README.md - Update "Writing Documentation" section
• SITE-ARCHITECTURE.md - Update sidebar generation section
• CMS-TODO.md - Mark this task as complete
• src/content/docs/community/get-featured.mdx - If applicable

---

Acceptance Criteria

• New src/config/navigation.yml file created with combined navbar, sidebar, and GitHub config
• src/sidebar.ts updated to read from new YAML config
• src/config/navbar.ts updated to read from new YAML config
• astro.config.mjs updated with new imports
• All existing tests pass (npm test)
• Site builds successfully (npm run build)
• Sidebar navigation works correctly in dev server (npm run dev)
• Top-nav/navbar works correctly
• GitHub dropdown works correctly
• mkdocs.yml deleted
• Documentation updated to reflect new configuration approach

---

Technical Notes

Badge Handling

Badges (like "new", "community") should come only from frontmatter in the markdown files, not from the navigation config. The existing system already supports this via the sidebar.badge frontmatter field.

Label Handling

File entries in the sidebar config only need the slug - labels are automatically pulled from the page's frontmatter title. Only directory/group entries need explicit labels.

Extra Variables

The extra: section from mkdocs.yml (containing docs_repo, sdk_pypi, etc.) is no longer used and should not be migrated.

---

Files Summary

Action	File
Create	src/config/navigation.yml
Modify	src/sidebar.ts
Modify	src/config/navbar.ts
Modify	astro.config.mjs
Modify	test/sidebar.test.ts
Modify	scripts/update-docs.ts
Modify	AGENTS.md, CONTRIBUTING.md, README.md, SITE-ARCHITECTURE.md, CMS-TODO.md
Delete	mkdocs.yml

---

Original Request

Right now the sidebar is still configured in yaml from mkdocs even though we've transitioned to astro/starlight.

We should transition to something (yaml or json) more readable and more integrated with astro/starlight.

If possible, consider integrating the top-nav configuration as well, as right now that's a separate file. Once done we should be able to delete the mkdocs.yml file

[zastrowm]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and the current implementation to understand the scope of this task. Here's what I found:

Current State

Sidebar Configuration

The sidebar is currently generated from mkdocs.yml via src/sidebar.ts:

• loadSidebarFromMkdocs() - Reads YAML nav structure, converts to Starlight format
• getSidebarLabels() - Extracts labels and badges from <sup> tags
• getCommunityLabeledFiles() - Identifies community-contributed content

Top-Nav Configuration

The top-nav is separately configured in src/config/navbar.ts:

• Defines NavLink[] interface with label, href, basePath, external properties
• Also contains githubSections for the GitHub dropdown

Other mkdocs.yml Dependencies

• scripts/update-docs.ts - Has hardcoded MKDOCS_VARIABLES (repo links, etc.)
• test/sidebar.test.ts - Tests sidebar generation from mkdocs.yml
• Multiple documentation files reference mkdocs.yml

This task is already noted in CMS-TODO.md as an "After Launch" item: "Migrate sidebar from mkdocs.yml to something astro specific (and combine with the navbar?)"

Implementation Approaches

I've identified several possible approaches:

Approach	Format	Pros	Cons
A	Single YAML file (navigation.yml)	Familiar syntax, easy for content authors	Still requires YAML parsing
B	TypeScript config (navigation.config.ts)	Type-safe, IDE support, comments	Less accessible for non-developers
C	JSON file (navigation.json)	Native JS parsing, schema validation	No comments, less readable
D	Inline in astro.config.mjs	Native Starlight integration	Config file becomes very large

---

Clarifying Questions

Configuration Format

1. What format would you prefer for the new configuration? (YAML, JSON, TypeScript, or directly in astro.config.mjs)

Structure

2. Should the navbar and sidebar be combined into a single configuration file?

   • Currently navbar is in src/config/navbar.ts and sidebar comes from mkdocs.yml
   • The CMS-TODO.md mentions "and combine with the navbar?" - is that the desired direction?

3. How should badges be represented in the new format?

   • Currently: AWS Lambda<sup> new</sup>: user-guide/deploy/deploy_to_aws_lambda.md
   • Proposed: { label: "AWS Lambda", path: "...", badge: { text: "new", variant: "note" } }
   • Or should frontmatter be the only source of badge info?

Variables & Metadata

4. What should happen to the extra: variables in mkdocs.yml? (e.g., docs_repo, sdk_pypi, sdk_repo URLs)
   • Move to a separate config file?
   • Move to environment variables?
   • Hardcode where needed?

Migration Strategy

5. Is a gradual migration acceptable?

   • Phase 1: Create new config, update sidebar.ts to read from it
   • Phase 2: Move extra variables
   • Phase 3: Delete mkdocs.yml

   Or should everything be migrated in one PR?

Scope

6. Are there any other parts of mkdocs.yml that need to be preserved?
   • The llmstxt plugin config?
   • Any other metadata?

---

Once I have your answers, I'll update the issue with detailed implementation requirements.

[zastrowm]

/strands

Top-Nav Configuration

The top-nav is separately configured in src/config/navbar.ts:

• Defines NavLink[] interface with label, href, basePath, external properties
• Also contains githubSections for the GitHub dropdown

Other mkdocs.yml Dependencies

• scripts/update-docs.ts - Has hardcoded MKDOCS_VARIABLES (repo links, etc.)
• test/sidebar.test.ts - Tests sidebar generation from mkdocs.yml
• Multiple documentation files reference mkdocs.yml

This task is already noted in CMS-TODO.md as an "After Launch" item: "Migrate sidebar from mkdocs.yml to something astro specific (and combine with the navbar?)"

Implementation Approaches

I've identified several possible approaches:

Approach Format Pros Cons
A Single YAML file (navigation.yml) Familiar syntax, easy for content authors Still requires YAML parsing
B TypeScript config (navigation.config.ts) Type-safe, IDE support, comments Less accessible for non-developers
C JSON file (navigation.json) Native JS parsing, schema validation No comments, less readable
D Inline in astro.config.mjs Native Starlight integration Config file becomes very large

Clarifying Questions

Configuration Format

1. What format would you prefer for the new configuration? (YAML, JSON, TypeScript, or directly in astro.config.mjs)

Let's go with YAML

Structure

2. Should the navbar and sidebar be combined into a single configuration file?

   • Currently navbar is in src/config/navbar.ts and sidebar comes from mkdocs.yml
   • The CMS-TODO.md mentions "and combine with the navbar?" - is that the desired direction?

Yeah, let's combine

3. How should badges be represented in the new format?

   • Currently: AWS Lambda<sup> new</sup>: user-guide/deploy/deploy_to_aws_lambda.md
   • Proposed: { label: "AWS Lambda", path: "...", badge: { text: "new", variant: "note" } }

frontmatter be the only source of badge info; we've already transitioned so we just need to reference the slugs of the files we want in there - when referencing the files, we don't even need labels since they're pulled from files too. Only directories need labels

Variables & Metadata

4. What should happen to the extra: variables in mkdocs.yml? (e.g., docs_repo, sdk_pypi, sdk_repo URLs)

   • Move to a separate config file?
   • Move to environment variables?
   • Hardcode where needed?

Get rid of them; we're not using them

Migration Strategy

5. Is a gradual migration acceptable?

   • Phase 1: Create new config, update sidebar.ts to read from it
   • Phase 2: Move extra variables
   • Phase 3: Delete mkdocs.yml

   Or should everything be migrated in one PR?

Do everything

Scope

6. Are there any other parts of mkdocs.yml that need to be preserved?

   • The llmstxt plugin config?
   • Any other metadata?

Nope; just make sure existing tests keep passing. update-docs.ts does not need to be preserved either

Once I have your answers, I'll update the issue with detailed implementation requirements.

[zastrowm]

/strands implement