fix(docs): extract SECTION_CATEGORIES to sidebar.config.ts for Astro hoisting

[jonathanperis]

Problem

Deploy fails with SECTION_ORDER is not defined during static route generation.

Root Cause

Astro hoists getStaticPaths() to module scope — it runs BEFORE frontmatter code executes. SECTION_ORDER defined in frontmatter is invisible to getStaticPaths. Only imports survive hoisting.

Fix

• Extract SECTION_CATEGORIES + SECTION_ORDER to sidebar.config.ts
• Import in [...slug].astro — import survives hoisting
• getStaticPaths now references imported SECTION_ORDER — works correctly
• Build-time assertion stays in frontmatter (runs at render time, not hoisted)

Files

• docs/src/pages/docs/sidebar.config.ts (new)
• docs/src/pages/docs/[...slug].astro (import + remove inline def)

Summary by CodeRabbit

• Documentation

  • Wiki content is now automatically discovered and validated at build time, ensuring all documented sections have corresponding files.

• Bug Fixes

  • Improved search functionality to properly restore navigation visibility when clearing the search query.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors the documentation pages to auto-discover wiki markdown files at build time using import.meta.glob, validates that all section categories have corresponding wiki files, and updates the page rendering logic to use the discovered and ordered sections instead of hardcoded filenames.

Changes

Wiki Auto-Discovery and Page Rendering

Layer / File(s)	Summary
Configuration docs/src/pages/docs/sidebar.config.ts	Introduces SECTION_CATEGORIES (typed array mapping labels to page ids) and derives SECTION_ORDER by flattening all ids.
Wiki Auto-Discovery & Build Validation docs/src/pages/docs/[...slug].astro (lines 4–35)	Discovers wiki markdown files via import.meta.glob, builds pagesBySlug map keyed by filename, and asserts at build time that all SECTION_CATEGORIES ids exist in the discovered set; throws an error if any are missing.
Section Selection & Rendering docs/src/pages/docs/[...slug].astro (lines 36–48, 128–131)	Computes isRoot, requestedSlug, and sectionsToRender using SECTION_ORDER and the discovered pagesBySlug map; updates JSX to iterate over { slug, page } pairs instead of constructing filenames.
Static Path Generation docs/src/pages/docs/[...slug].astro (lines 49–53)	Changes getStaticPaths() to derive slug params from SECTION_ORDER (excluding home) rather than a local constant.
Search/Navigation UX docs/src/pages/docs/[...slug].astro (lines 241–252)	Expands the search clear behavior to reset nav visibility, category group display, and each group's .sidebar-category label visibility when query is empty.

Sequence Diagram

sequenceDiagram
    participant Build as Build System
    participant Wiki as Wiki .md Files
    participant Config as SECTION_CATEGORIES
    participant Discover as Page Template
    participant Cache as pagesBySlug Map
    
    Build->>Wiki: Glob discover *.md
    Wiki-->>Build: File paths
    Build->>Discover: Create pagesBySlug map
    Discover->>Config: Load SECTION_ORDER
    Config-->>Discover: Ordered ids
    Discover->>Discover: Validate all ids exist in discovered files
    Note over Discover: Build-time assertion<br/>throws if missing
    Discover->>Cache: Cache pages by slug
    
    Note over Build,Cache: —— Build Time Complete ——
    
    participant Request as Request /docs/:slug
    participant Render as Page Renderer
    
    Request->>Render: Route with slug param
    Render->>Cache: Lookup sections by SECTION_ORDER
    Cache-->>Render: Matching page objects
    Render->>Render: Render sections + JSX
    Render-->>Request: HTML response

Loading

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly Related PRs

• PR #54: Makes identical code-level changes to docs/src/pages/docs/[...slug].astro and sidebar.config.ts—deriving SECTION_ORDER from SECTION_CATEGORIES, building pagesBySlug from wiki glob, adding build-time validation, and updating section/path rendering logic.
• PR #50: Introduces the overall architecture shift from React/MDX to pure-Astro documentation by adding the catch-all docs/[...slug].astro template and wiki-based page structure.
• PR #53: Modifies sidebar category display CSS (display: block enforcement) to work in tandem with the dynamic category visibility reset logic introduced in this PR's search-clear functionality.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: extracting SECTION_CATEGORIES to a new config file to resolve Astro hoisting issues.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/docs-sidebar-config-hoisting

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch fix/docs-sidebar-config-hoisting

---

_{Review rate limit: 1/10 review remaining, refill in 53 minutes and 4 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/src/pages/docs/[...slug].astro (1)

24-34: ⚡ Quick win

Add duplicate-id guard in build-time validation.

The validation currently checks existence only. A duplicate id across categories can still slip through and cause duplicated sections/route params. Add a uniqueness check in the same assertion block.

Suggested patch

 const availableSlugs = new Set(Object.keys(pagesBySlug));
+const seenIds = new Set<string>();
 for (const cat of SECTION_CATEGORIES) {
   for (const id of cat.ids) {
+    if (seenIds.has(id)) {
+      throw new Error(`Duplicate SECTION_CATEGORIES id detected: "${id}"`);
+    }
+    seenIds.add(id);
+
     if (!availableSlugs.has(id)) {
       const catName = cat.label || 'root';
       throw new Error(
         `SECTION_CATEGORIES references id "${id}" (category: "${catName}") but no matching wiki/${id}.md was found. Available slugs: ${Array.from(availableSlugs).join(', ')}`
       );
     }
   }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/src/pages/docs/`[...slug].astro around lines 24 - 34, The current
validation only checks that each id in SECTION_CATEGORIES exists in
availableSlugs; add a uniqueness guard that detects duplicate ids across
categories by building a frequency map (or a seen Set) while iterating
SECTION_CATEGORIES -> cat.ids and throwing an Error if any id appears more than
once; include the duplicated id(s) and the associated category labels (use
cat.label or 'root') in the error message so the thrown Error from this block
(which references availableSlugs, SECTION_CATEGORIES, cat.ids, and cat.label)
clearly identifies the duplicates and their categories.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/src/pages/docs/`[...slug].astro:
- Around line 24-34: The current validation only checks that each id in
SECTION_CATEGORIES exists in availableSlugs; add a uniqueness guard that detects
duplicate ids across categories by building a frequency map (or a seen Set)
while iterating SECTION_CATEGORIES -> cat.ids and throwing an Error if any id
appears more than once; include the duplicated id(s) and the associated category
labels (use cat.label or 'root') in the error message so the thrown Error from
this block (which references availableSlugs, SECTION_CATEGORIES, cat.ids, and
cat.label) clearly identifies the duplicates and their categories.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7248bac1-c7e8-4446-94b0-5d04b5f9afb7

📥 Commits

Reviewing files that changed from the base of the PR and between dfc7cd9 and d19e9bb.

📒 Files selected for processing (2)

• docs/src/pages/docs/[...slug].astro
• docs/src/pages/docs/sidebar.config.ts