fix: de-duplicate sidebar and document site structure - #10
Merged
Conversation
The sidebar in astro.config.mjs listed Guides/Templates/Tools/Case Studies twice, and its "Guides" autogenerate recursed into the module-0/ and phase-*/ subfolders that are also curated by hand — so every module and phase page appeared multiple times in the left nav. Convert "Guides" to an explicit landing + reference list so it no longer recurses into the curated Module/Phase sections, and remove the duplicated resource block. Each section now appears exactly once; the build is clean. Also add site/README.md documenting how the site is structured — including the nested src/content/docs/docs/ folders, the file-to-URL mapping, how to add a page, and how the sidebar is wired (autogenerate vs. explicit, and the duplication trap to avoid). CONTRIBUTING.md now points to it.
The initial fix removed the duplication but kept the Module 0 and Phase
groups as hand-listed `items: [{ slug }]` arrays, which meant adding a page
still required editing astro.config.mjs -- the same friction that led to the
duplicate entries in the first place.
Switch those groups to `autogenerate` with a custom label, so their pages and
ordering come entirely from the folder and each page's sidebar.order
frontmatter. The page slugs already carried correct order values, so the
rendered sidebar is identical (verified: 18 links, no duplicates, original
teaching order preserved) -- but contributors no longer touch this config to
add, remove, or reorder a page within a section.
Update site/README.md's sidebar section to describe the autogenerate-driven
model and when (rarely) the config needs editing.
…rview" Add a "Controlling how a page looks in the sidebar" section to site/README.md covering title vs sidebar.label, sidebar.order (with gap advice), and badges, plus the index-vs-group label pattern. Set sidebar.label: Overview on guides/module-0/index.md so the Module 0 group's first entry reads "Overview" instead of repeating the full module title.
5 tasks
cner-smith
added a commit
that referenced
this pull request
May 24, 2026
…12) After #10 the Module 0 and Phase 1-3 groups sat at the top level of the sidebar, as siblings of "Guides", even though all of that content lives under docs/guides/. Move them inside the Guides group's `items` so the navigation matches the content structure: Guides now expands to the landing page, the example reference, and the Module 0 / Phase sub-groups. No change to page content, slugs, or ordering -- still autogenerate-driven and duplicate-free (verified against the built nav). site/README.md updated to show the nested structure.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this change?
Two related changes to the website:
Fixes duplicated sidebar entries introduced in initial structure upload with placeholders #9, and makes the duplication structurally hard to reintroduce. In
site/astro.config.mjs, theGuides / Templates / Tools / Case Studiesautogenerate blocks were listed twice, and theGuidesautogenerate recursed into themodule-0/andphase-*/subfolders that were also curated by hand — so every module and phase page was emitted multiple times in the left navigation.The fix removes the duplicate block and drives each Module 0 / Phase group from its folder with
autogenerate(keeping a custom label) instead of hand-listed slugs. Ordering now comes from each page's existingsidebar.orderfrontmatter, so the rendered nav is identical (verified: 18 links, no duplicates, original teaching order) — but contributors never edit this config to add, remove, or reorder a page within a section.Guidesstays an explicit landing + reference list so it doesn't re-list the module/phase tree.Adds
site/README.md— a structure-and-authoring reference covering the two page types, the nestedsrc/content/docs/docs/folders, the file→URL mapping, how to add a page, and how the sidebar is configured (autogenerate-driven, plus the overlap that produces duplicates).CONTRIBUTING.mdlinks to it.Why?
The navigation listed the same module and phase pages several times. The root cause was a structural overlap — curated sidebar groups living inside a directory that was also autogenerated. Beyond fixing the symptom, this moves the curated groups onto autogenerate too, so adding content no longer means editing the sidebar config (the step where the overlap was introduced). The new docs explain the layout and the pitfall.
Type of change
Checklist
npm run buildpasses clean (22 pages, no warnings); built sidebar verified to contain 18 links with no duplicatesfix:commitNotes for reviewers
Guidesis intentionally the one explicit list (landing +example-guide): autogeneratingdocs/guideswould recurse into themodule-0/andphase-*/folders and re-list them. The rule is documented insite/README.md: each directory is owned by exactly one sidebar entry.