docs: design programme course navigation
This commit is contained in:
msa46
parent
84d213a9f6
commit
b8126a5a21
1 changed files with 160 additions and 0 deletions
|
|
@ -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/<course>/`
|
||||
- `/data-science-and-ai/`
|
||||
- `/data-science-and-ai/year-N/`
|
||||
- `/data-science-and-ai/year-N/block-N/<course>/`
|
||||
|
||||
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/)
|
||||
Loading…
Add table
Reference in a new issue