Codex URL structure and category navigation

[reakaleek]

Summary

Adds a new URL structure and navigation model for the documentation codex:

• Stable repository URLs (/r/{repo-name}) that do not change when category membership changes
• Category landing pages (/g/{category}) that group related documentation sets
• Shared navigation for repositories in the same category (same sidebar on group landing and all member repo pages)
• Isolated navigation for ungrouped repositories (sidebar shows only that repo’s tree)
• Optional site prefix so the codex can be hosted at the domain root (e.g. codex.elastic.dev)

Motivation

Previously, repository URLs could be tied to category structure, so changing a repo’s category could break links. We also lacked a way to show a single navigation tree for a set of related docs.

This change separates URL shape from organisation:

• URLs are stable and predictable: /r/apm-agent always targets the APM Agent docs
• Categories are for navigation only: any page in the “observability” category shows the same sidebar (group landing + all observability repos)
• Ungrouped repos use their own navigation root so the sidebar stays focused on that repo

Implementation

URL patterns

Pattern	Purpose	Example
/r/{repo-name}	Stable repo URL	/r/apm-agent, /r/uptime-docs
/g/{category}	Category landing	/g/observability, /g/tooling
/ or /{site_prefix}	Codex landing	/, /internal-docs

Architecture

• GroupNavigation – New navigation root type per category. It is the NavigationRoot for all repos in that category, holds the category landing page and member repos as top-level items, and ensures the same sidebar on the category landing and every member repo page.
• Ungrouped repos – Their DocumentationSetNavigation is their own NavigationRoot, so the sidebar shows only that repo’s tree.
• IsolatedBuildNavigationHtmlWriter – Uses SelectNavigationRoot() so when a different root is requested (e.g. GroupNavigation), that root is used for rendering instead of the site root. TopLevelItems come from the selected navigation, so the sidebar reflects the correct tree.

Key changes

New

• GroupNavigation.cs – Category navigation root and related types (GroupIndexLeaf, GroupLinkLeaf, etc.)
• GroupLandingView.cshtml – Razor view for category landing pages
• GroupLandingViewModel.cs – View model for category landing pages

Navigation behaviour

Repo type	Sidebar shows	NavigationRoot
In a category	Category landing + all category members	GroupNavigation
No category	Only that repo’s tree	DocumentationSetNavigation

Configuration

documentation_sets:
  # Ungrouped – sidebar shows only this repo
  - name: docs-eng-team
    repo_name: ci-guide
    display_name: "CI Developer Guide"

  # In a category – shared sidebar with other observability repos
  - name: docs-eng-team
    category: observability
    repo_name: apm-agent-docs
    display_name: "APM Agent"

# Optional – omit or set to "/" for root hosting
site_prefix: /

Manual verification

• Build codex with mixed grouped/ungrouped repos
  • dotnet run --project src/tooling/docs-builder -- codex clone config/codex.example.yml
  • dotnet run --project src/tooling/docs-builder -- codex build config/codex.example.yml
  • dotnet run --project src/tooling/docs-builder -- codex serve
• Confirm /r/{repo} works for all repos regardless of category
• Confirm /g/{category} shows only that category’s members
• Confirm grouped repo pages show shared category sidebar
• Confirm ungrouped repo pages show only that repo’s sidebar
• Confirm display_name from config appears in the sidebar
• Confirm codex works with no site_prefix and with a prefix
• Confirm HTMX attributes on category landing work as expected

Recording

cursorful-video-1770203225778.mp4