From b8126a5a2145ad069bd1d3fb4dc1e282d15710c6 Mon Sep 17 00:00:00 2001 From: msa46 Date: Sat, 15 Aug 2026 20:41:56 +0200 Subject: [PATCH] docs: design programme course navigation --- ...e-sidebar-and-course-integration-design.md | 160 ++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-15-programme-sidebar-and-course-integration-design.md diff --git a/docs/superpowers/specs/2026-08-15-programme-sidebar-and-course-integration-design.md b/docs/superpowers/specs/2026-08-15-programme-sidebar-and-course-integration-design.md new file mode 100644 index 0000000..c2b1cf1 --- /dev/null +++ b/docs/superpowers/specs/2026-08-15-programme-sidebar-and-course-integration-design.md @@ -0,0 +1,160 @@ +# Programme Sidebar and Course Integration Design + +## Goal + +Publish the substantive Computer Science course material from `origin/isaacs-changes` without merging that branch's broken file moves, empty placeholders, malformed description, content duplication, or archive deletion. Reorganize bachelor navigation so readers can switch between Computer Science and Data Science & AI while global wiki resources remain available. + +## Source and scope + +The source branch is `origin/isaacs-changes` at commit `d5d6730`. It diverged from `main` at `c590f77` and must not be merged or cherry-picked wholesale. + +Publish these five substantive Computer Science pages from the branch after normalizing them to current repository conventions: + +- Introduction to Computer Science +- Computer Architecture +- Algorithmic Design +- Databases +- Statistics + +Also expose these seven courses in both bachelor programmes: + +- Discrete Mathematics +- Procedural Programming +- Calculus +- Logic +- Objects in Programming +- Data Structures and Algorithms +- Linear Algebra + +The branch's copies of those seven pages are byte-identical. Their common body content therefore has one source, while each programme receives its own public route and frontmatter wrapper. + +Do not publish: + +- `computer-science/course-description.md`, which lacks frontmatter and contains duplicate `#Hello` headings; +- any of the 30 Computer Science Year 2 and Year 3 `Empty Page` placeholders; +- duplicate full copies of identical shared-course bodies; or +- the branch deletion of `previous-exams-and-documents.md`. + +No other `origin/isaacs-changes` change is in scope. + +## Public route model + +Use programme-specific routes: + +- `/computer-science/` +- `/computer-science/year-1/` +- `/computer-science/year-1/period-N//` +- `/data-science-and-ai/` +- `/data-science-and-ai/year-N/` +- `/data-science-and-ai/year-N/block-N//` + +The period/block naming follows each source programme's existing terminology. Do not rewrite course URLs to imply the two curricula have identical structures. + +Move the current DSAI pages from `/bachelor/...` to `/data-science-and-ai/...`. Preserve every previous `/bachelor/...` URL with a permanent redirect to its exact DSAI replacement, including overview, year, project, honours, thesis, study-abroad, and course routes. Internal wiki links and the sidebar should use the new canonical URLs after migration. + +The five newly recovered Computer Science pages live only under Computer Science routes. Empty later-year Computer Science routes are not created. + +## Shared-course content model + +Store the common body of each of the seven identical courses as a non-published MDX partial outside the `docs` collection. Create a thin MDX page at each programme-specific route with: + +- programme-appropriate title and description frontmatter; +- the standard historical-information caution; +- an import of the shared body partial; and +- an optional programme-specific notes section when verified differences exist. + +The shared partial contains no page-level frontmatter, H1 heading, or historical caution. This prevents duplicate rendered titles and notices. + +If a shared course later diverges, keep both public routes stable. Replace or extend only that programme wrapper; the other programme continues using the shared partial. Do not encode programme identity in the shared source. + +## Programme overview pages + +Create a clean Computer Science overview and Year 1 overview using only verified descriptions and links. Do not reuse or repair the malformed branch course-description text by inference. + +Retitle and relocate the existing bachelor overview pages as Data Science & AI. Preserve their historical warning and current external Maastricht University guidance. + +## Sidebar interaction + +Add a small route-aware programme switch above the course-navigation portion of Starlight's global sidebar: + +- **Computer Science** +- **Data Science & AI** + +The switch uses ordinary links, works without client JavaScript, is keyboard accessible, and marks the active programme with `aria-current`. It renders inside the existing Starlight sidebar on desktop and in the existing mobile navigation. + +Use Starlight's supported `Sidebar` component override to prepend the switch while reusing the default `Sidebar` component. Use Starlight route-data middleware to filter the detailed bachelor course tree to the active programme. + +Programme selection is derived from the current route and is never stored in cookies or local storage: + +- Computer Science routes activate Computer Science navigation. +- Data Science & AI routes and redirected legacy bachelor routes activate DSAI navigation. +- Global pages show neither option as active and show compact links to both programme overviews instead of a detailed bachelor tree. + +When a reader uses the switch from one of the seven shared-course routes, link to the paired route in the other programme. From a programme-specific course without an equivalent, link to the other programme's Year 1 overview. From other programme pages, link to the other programme overview. + +The rest of the global navigation remains available in both programme contexts: + +- Home +- About Incognito +- Previous exams and documents +- Master AI +- Master DSDM +- Useful Information and all its current child pages + +The programme switch changes only the detailed bachelor-course portion. It must not hide the master programmes or Useful Information. + +## Navigation data boundaries + +Keep navigation definitions as focused data structures: + +- one Computer Science course tree; +- one Data Science & AI course tree; +- one global navigation section; +- one explicit map of paired shared-course routes; and +- one pure function that selects the active programme and switch destinations from a route ID. + +The route middleware consumes those structures and assigns the final Starlight sidebar. The component override only renders the switch and delegates the link tree to Starlight's default component; it does not duplicate sidebar filtering logic. + +## Migration records and provenance + +Update the migration manifest, migration report, supplemental-content registry, and sidebar tests in lockstep with the route moves and new pages. + +- Existing DSAI content retains its existing source provenance while its destination changes. +- The five new Computer Science pages record their `wiki.msvincognito.nl` source URLs and `2026-08-02` capture provenance. +- Shared programme wrappers record which source page supplied the common body. +- Redirects are documented as compatibility routes, not duplicate published content. + +The audit must continue to reject undeclared published Markdown/MDX files and any reintroduction of the excluded placeholder or malformed pages. + +## Accessibility and responsive behavior + +- Use a labelled navigation region for the programme switch. +- Expose the current programme with both visual styling and `aria-current="page"`. +- Keep touch targets at least as large as existing Starlight sidebar links. +- Preserve Starlight's default sidebar persistence, focus behavior, and mobile menu footer by wrapping rather than copying the default component. +- Ensure long programme labels wrap without horizontal scrolling at narrow widths. + +## Testing and verification + +Add focused automated coverage for: + +- exact inclusion of the five substantive Computer Science pages; +- exclusion of the malformed description and all empty placeholders; +- one shared source body for each identical course and two programme-specific public routes; +- programme-specific content overrides remaining possible; +- complete old `/bachelor/...` to new DSAI redirect coverage; +- route-to-programme detection and paired-course switch destinations; +- route middleware retaining global navigation and showing only the active detailed bachelor tree; +- accessible programme switch markup and active state; +- sidebar visibility on Computer Science, DSAI, master, and Useful Information pages; +- updated manifest, report, and supplemental registry consistency; and +- absence of duplicate H1 headings, broken internal links, and unpublished-source leakage. + +Run focused red/green tests first, then the full `npm run verify` workflow. Build once at `/` and once with a non-root `BASE` to cover canonical links, redirects, the sidebar override, and mobile-compatible output. + +## References + +- [Starlight Sidebar override](https://starlight.astro.build/reference/overrides/#sidebar) +- [Starlight component overrides](https://starlight.astro.build/guides/overriding-components/) +- [Starlight route-data middleware](https://starlight.astro.build/guides/route-data/#customizing-route-data) +- [Starlight sidebar configuration](https://starlight.astro.build/guides/sidebar/)