Skip to main content

ADR-0002: Navigation Governance via Autogenerated Sidebars and _category_.json

Purpose​

Record the decision to govern navigation using autogenerated sidebars plus _category_.json in each navigable folder, rather than manually curated sidebars.

Scope​

Use when​

  • scaling documentation IA across domains and project dossiers
  • defining how new sections are added without sidebar maintenance overhead

Do not use when​

  • deciding the content of a specific section (handled by that section’s index and templates)

Prereqs / Inputs​

  • Decision owner(s): Portfolio maintainer
  • Date: 2026-01-06
  • Status: Accepted
  • Related risks:
    • nav drift and inconsistent ordering
    • broken links from prematurely linked pages
    • contributor friction when sidebar changes become a bottleneck

Decision Record​

Title​

ADR-0002: Navigation Governance via Autogenerated Sidebars and _category_.json

Context​

The documentation system is intended to grow to enterprise-level scope. Manually maintaining navigation structures creates:

  • brittle sidebars and merge conflicts
  • high contributor friction
  • inconsistent ordering and discoverability
  • increased risk of navigation entropy as content expands

We require an approach where:

  • structure is derived from the filesystem (source of truth)
  • categories have explicit metadata (labels, ordering, landing behavior)
  • top-level domains present curated entrypoints
  • internal scaffolding remains non-public (docs/_meta/)

Decision​

Adopt the following navigation governance model:

  • sidebars.ts uses autogenerated with dirName: '.' (filesystem-driven navigation).
  • Every navigable folder must contain _category_.json (or .yml) defining:
    • label
    • position
    • link (generated-index for most subsections; doc link for curated hubs)
  • Top-level domains (00-…70-…) must use:
    • _category_.json linking to a curated index.md hub via link.type: "doc"
  • Keep docs/_meta/ underscore-prefixed and internal-only (not public, not in sidebar).

Alternatives considered​

  1. Manually curated sidebars (explicit lists)

    • Pros:
      • total control over ordering and grouping
    • Cons:
      • high maintenance cost
      • frequent merge conflicts as docs scale
      • friction for AI agents and contributors adding content
    • Why not chosen:
      • does not scale; encourages “sidebar churn” and slows delivery.

  2. Autogenerated sidebars without category metadata

    • Pros:
      • minimal setup
    • Cons:
      • ordering becomes implicit and inconsistent
      • labels leak filesystem naming (including numeric prefixes)
      • no consistent section landing behavior
    • Why not chosen:
      • lacks governance; undermines enterprise UX.

  3. Generated index everywhere (no curated hubs)

    • Pros:
      • rapid bootstrapping
    • Cons:
      • weak narrative and reviewer journey for top-level sections
      • less “enterprise documentation product” feel
    • Why not chosen:
      • top-level domains require curated entrypoints to guide reviewers.

Consequences​

  • Positive consequences:

    • New content can be added by filesystem conventions without sidebar edits
    • Consistent ordering and labeling across the entire repo
    • Top-level domains behave like “products/chapters” with curated landing pages
    • Reduced friction for iterative docs-driven planning

  • Negative consequences / tradeoffs:

    • Requires discipline: _category_.json is mandatory for navigable folders
    • Contributors must learn the category/link model (doc vs generated-index)
    • Autogenerated ordering rules must be understood and enforced via positions

  • Operational impact:

    • Navigation breakage becomes a CI-blocking issue (by design)
    • Reorganizations must be handled carefully to avoid broken references

  • Security impact:

    • Keeping _meta internal reduces accidental exposure of scaffolding and authoring mechanics
    • Still must enforce “no secrets” and safe-publication discipline

Implementation notes (high-level)​

  • Ensure top-level folders contain:
    • _category_.json
    • index.md (curated hub)
  • Enforce:
    • no links to pages that do not exist yet
    • use path references (plain text) until targets exist
  • Add contributor documentation explaining:
    • how to add sections
    • how to choose doc vs generated-index
    • validation expectations (pnpm build)

Validation / Expected outcomes​

  • Adding a new section requires:
    • creating folder
    • adding _category_.json
    • adding at least one doc (or curated index.md if top-level)
  • Navigation renders coherently in pnpm start
  • pnpm build fails deterministically if:
    • doc IDs referenced in category links do not exist
    • internal links are broken
    • invalid front matter or structure occurs

Failure modes / Troubleshooting​

  • Missing _category_.json leads to poor labeling/ordering:
    • mitigation: enforce rule via review checklist and (optionally) lint tooling.
  • Over-linking to future work causes broken builds:
    • mitigation: avoid premature links; use path references until created.
  • Large reorg causes link breakage:
    • mitigation: refactor in small PRs; update references; maintain stable slugs where appropriate.

References​

  • Docs landing: docs/index.md
  • Portfolio domain hub example: docs/00-portfolio/index.md
  • Category metadata examples: docs/00-portfolio/_category_.json, docs/60-projects/
  • Internal scaffolding (non-public): docs/_meta/