Skip to content

Normalise session archive routes: mixed slug and folder-path URLs, duplicate session 14 #375

Open

Description

@IanoNjuguna

Page or section

website/docs/working-group/sessions/** (the working group session archive) and anything that links into it.

Issue description

The session archive serves two different URL shapes depending on whether a notes page carries a slug in frontmatter, and two folders claim the same session number.

There are 23 session-notes pages in the tree. 14 carry a slug and are served at:

/docs/working-group/<quarter>/sessions/<NN-slug>/session-notes/

The other 9 have none, so Docusaurus falls back to the folder path, which strips the numeric prefix and keeps the literal sessions segment:

/docs/working-group/sessions/<quarter>/<slug>/session-notes/

The 9 without a slug, measured on main at 973801b:

Quarter Folder Status
q1-2026 09-community-builder-story slugged in #411
q1-2026 11-open-source-docs slugged in #411
q1-2026 12-cardano-developer-pathway slugged in #411
q4-2025 01-kickoff-orientation slugged in #411
q4-2025 02-dev-opportunities slugged in #411
q4-2025 03-dev-environment-setup slugged in #411
q4-2025 04-essential-links slugged in #411
q4-2025 06-repo-walkthrough slugged in #411
q1-2026 10-wallet-integration/Session-1 open: needs a route decision

That last one cannot be slugged in isolation. Its Session-2 sibling already holds the clean route for the session (/working-group/q1-2026/sessions/10-wallet-integration/session-notes), so giving Session-1 a slug means deciding the shape for both, which belongs with the folder normalisation below.

Two facts this table corrects from the original version of this issue: 06-repo-walkthrough was missing (it is slug-less, and it is the folder the sesion-notes spelling fix landed on), and 10-wallet-integration is not simply slug-less, it is split across two sub-sessions with one slugged and one not. q4-2025/05-developer-story-1 also has no slug, but its page is a bare readme.md at the session root with no session-notes folder, so it is a folder-shape question rather than a slug one.

Three more inconsistencies in the same tree:

  1. Number 14 is used twice. q1-2026/14-CIP-68 NFT-Standard and q2-2026/14-sdk-repo-walkthrough both claim session 14, and both are live pages.
  2. Two slugs point at the wrong quarter. q1-2026/07-contributing-intersect and q1-2026/08-open-clinic-1 have slugs under /working-group/q1-2025/..., so their URLs say Q1 2025 while their folders say Q1 2026.
  3. Folder names break their own convention. 14-CIP-68 NFT-Standard is capitalised and contains a space, Session-1 / Session-2 / Recording are capitalised, and the quarter directory named q1-2026 holds documents whose URLs say q1-2025.

Impact: any tool that derives archive links from the filesystem has to replicate Docusaurus's slug and number-prefix rules exactly. The scripts/generate-sessions.js generator that feeds the new session carousel on the landing page does exactly that, and its first version got one of the 8 fallbacks wrong; the build's broken-link check is the only thing that caught it, because a wrong route in the generated JSON fails the build rather than 404ing silently in production. Search results, cross-links between sessions, and any future redirect map inherit the same problem.

Nothing is broken for a reader today. Every existing route resolves.

Proposed change

Normalise the archive so a session's URL is a function of its quarter and number, and so a tool never has to guess:

  • Add slug: /working-group/<quarter>/sessions/<NN-slug>/session-notes to the notes pages that lack one. Eight of the nine are done in feat(docs): slug the last eight session notes pages, and redirect their old routes #411, stacked on fix(website): rename the sesion-notes folder, and keep its URL working #410; 10-wallet-integration/Session-1 waits on the route decision above.
  • Renumber one of the two 14s. The CIP-68 session predates the SDK walkthrough, so it likely needs a new number or a move into the quarter it actually belongs to.
  • Fix the 07 and 08 slugs to q1-2026, or move those folders into a q1-2025 directory, whichever matches when the sessions actually ran.
  • Rename 14-CIP-68 NFT-Standard to 14-cip-68-nft-standard, and lowercase Session-1, Session-2 and Recording for consistency with the rest of the tree.
  • Add the old URLs to @docusaurus/plugin-client-redirects so inbound links and search results do not break when routes move.
  • Note the convention in CONTRIBUTING.md so new sessions land in the right shape.

Once every session carries a slug, scripts/generate-sessions.js can drop its path-derivation fallback and simply read the slug, which removes the class of bug entirely.

Checks

  • I searched existing issues and discussions
  • This is about documentation (not a feature request or bug)

Activity

  1. IanoNjuguna commented on Nov 22, 2026

    @IanoNjuguna
    ContributorAuthor

    Status of every bullet in this issue, all of it in one stack on top of #410:

    Bullet Where
    slug on the pages that lacked one #411 (8 of 9) and #413 (10-wallet-integration/Session-1)
    fix the 07 and 08 slugs that said q1-2025 #412
    rename 14-CIP-68 NFT-Standard and lowercase Session-1, Session-2, Recording #413
    add the old URLs to the redirect array each of #411, #412, #413, #417
    note the convention in CONTRIBUTING.md #414
    drop the generator's path fallback #414
    renumber one of the two 14s #417, decided as option A in #416

    That is seven of the eight bullets; the eighth, the duplicate 14, was split out to #416 because it needed a decision rather than an edit, and #417 closes it.

    Two things this issue did not cover and still are not done: q4-2025/05-developer-story-1 has a bare readme.md with no session-notes folder and no slug, and q1-2026/12-cardano-developer-pathway has a session-level readme.md alongside its notes page, also unblessed. Neither is a session, so the generator ignores them; both are folder-shape questions.

    Once the stack merges this issue can close with every bullet accounted for.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions