diff --git a/site/README.md b/site/README.md index 256ee57..2c6f937 100644 --- a/site/README.md +++ b/site/README.md @@ -115,12 +115,20 @@ That works because every section uses Starlight's **`autogenerate`**, which refl Drop a file into `templates/` → it appears, ordered by its `sidebar.order`. No config change. -The Module 0 and Phase groups work the same way — they just keep a custom label on top of the autogenerated folder: +The Module 0 and Phase groups work the same way — they keep a custom label on top of an autogenerated folder — and they're **nested inside the `Guides` group**, because their content lives under `guides/`: ```js { - label: "Module 0: Sovereignty in the Digital Age", // pretty label we choose - autogenerate: { directory: "docs/guides/module-0" }, // pages come from the folder + label: "Guides", + items: [ + { slug: "docs/guides" }, // the Guides landing page + { slug: "docs/guides/example-guide" }, // contributor reference + { + label: "Module 0: Sovereignty in the Digital Age", // pretty label we choose + autogenerate: { directory: "docs/guides/module-0" }, // pages come from the folder + }, + // ...Phase 1–3 groups follow, same pattern + ], }, ``` @@ -164,21 +172,17 @@ Only for structural changes, not content: Adding, removing, or reordering *pages within an existing section* is always done in frontmatter. -### The one explicit list, and the duplication gotcha +### Why `Guides` uses an explicit list, and the duplication gotcha -`Guides` is the single exception — an explicit two-item list (its landing page + the contributor reference), not an autogenerate: +`Guides` is the one group built from an explicit `items` list instead of a plain `autogenerate`, because it has to mix loose pages (the landing + reference) *with* the nested Module/Phase sub-groups shown above. -```js -{ label: "Guides", items: [ { slug: "docs/guides" }, { slug: "docs/guides/example-guide" } ] }, -``` - -Here's why, and it's the trap that caused the bug this all started with: +The reason it is **not** simply `autogenerate: { directory: "docs/guides" }` is the trap that caused the original bug: -> ⚠️ **`autogenerate` recurses into _every_ subfolder.** `module-0/` and `phase-*/` live *inside* `guides/`. So `autogenerate: { directory: "docs/guides" }` would pull in the entire Module/Phase tree — which is *already* shown by the Module 0 and Phase groups above — listing every one of those pages twice. That's exactly what happened before: a `docs/guides` autogenerate sitting next to hand-maintained Module/Phase groups. +> ⚠️ **`autogenerate` recurses into _every_ subfolder.** `module-0/` and `phase-*/` live *inside* `guides/`. Autogenerating `docs/guides` would pull in the entire Module/Phase tree on its own — and combined with the explicit Module/Phase sub-groups, every one of those pages would appear twice. > -> **Rule of thumb: each directory is owned by exactly one sidebar entry — never autogenerate a folder *and* its parent, and never autogenerate a folder you also list by hand.** +> **Rule of thumb: each directory is owned by exactly one sidebar entry — never autogenerate a folder *and* also list it (or autogenerate one of its subfolders) elsewhere.** -Because `module-0/` and `phase-*/` already have their own groups, `Guides` only needs its two loose top-level pages, so it's listed explicitly rather than autogenerating `docs/guides`. +So `Guides` lists its two loose pages and the curated Module/Phase sub-groups explicitly, and never autogenerates `docs/guides` itself. --- diff --git a/site/astro.config.mjs b/site/astro.config.mjs index ec6899a..71409d0 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -24,54 +24,53 @@ export default defineConfig({ }, sidebar: [ // ------------------------------------------------------------------ - // CURATED LEARNING PATH (Module 0 + Phases) + // GUIDES // - // Each group keeps a hand-written label, but its pages are pulled in - // with `autogenerate` and ordered by each page's `sidebar.order` - // frontmatter. That means adding or reordering a page is done in the - // page's frontmatter -- this config is NOT touched. + // Everything under docs/guides/ is nested inside this single top-level + // "Guides" group: the landing page, the contributor reference, then the + // curated Module 0 and Phase sub-groups. // - // Do NOT switch these back to manual `items: [{ slug }]` lists, and do - // NOT autogenerate their shared parent (docs/guides): either approach - // lists the same pages a second time and duplicates the sidebar. - // ------------------------------------------------------------------ - { - label: "Module 0: Sovereignty in the Digital Age", - autogenerate: { directory: "docs/guides/module-0" }, - }, - { - label: "Phase 1: Pre-Work", - collapsed: true, - autogenerate: { directory: "docs/guides/phase-1" }, - }, - { - label: "Phase 2: Execution", - collapsed: true, - autogenerate: { directory: "docs/guides/phase-2" }, - }, - { - label: "Phase 3: Monitoring and Evaluation", - collapsed: true, - autogenerate: { directory: "docs/guides/phase-3" }, - }, - - // ------------------------------------------------------------------ - // RESOURCE SECTIONS + // Each sub-group keeps a hand-written label but pulls its pages from the + // folder with `autogenerate`, ordered by each page's `sidebar.order` + // frontmatter -- so adding or reordering a page is done in that page's + // frontmatter, NOT here. // - // "Guides" is an explicit landing + reference list, NOT an - // autogenerate of docs/guides -- that directory contains the module-0/ - // and phase-*/ folders above, so autogenerating it would list every - // module and phase page a second time. Templates / Tools / Case - // Studies are flat folders, so they autogenerate cleanly: drop a file - // in and it appears. + // Do NOT autogenerate the parent `docs/guides` directory: it contains + // the module-0/ and phase-*/ folders below, so autogenerating it would + // list every module and phase page a second time and duplicate the nav. + // Rule: each directory is owned by exactly one sidebar entry. // ------------------------------------------------------------------ { label: "Guides", items: [ { slug: "docs/guides" }, // Guides landing (index.md) { slug: "docs/guides/example-guide" }, // Contributor reference page + { + label: "Module 0: Sovereignty in the Digital Age", + autogenerate: { directory: "docs/guides/module-0" }, + }, + { + label: "Phase 1: Pre-Work", + collapsed: true, + autogenerate: { directory: "docs/guides/phase-1" }, + }, + { + label: "Phase 2: Execution", + collapsed: true, + autogenerate: { directory: "docs/guides/phase-2" }, + }, + { + label: "Phase 3: Monitoring and Evaluation", + collapsed: true, + autogenerate: { directory: "docs/guides/phase-3" }, + }, ], }, + + // ------------------------------------------------------------------ + // OTHER RESOURCE SECTIONS + // Flat folders -- autogenerate cleanly: drop a file in and it appears. + // ------------------------------------------------------------------ { label: "Templates", autogenerate: { directory: "docs/templates" } }, { label: "Tools", autogenerate: { directory: "docs/tools" } }, { label: "Case Studies", autogenerate: { directory: "docs/case-studies" } },