Nepal Dev VerseGitHub

ADR-0025 — The overview has the same sidebar as its tracks

An entry's overview shows the sidebar of its default track, and every track lists Overview as its first item.

Context

The owner reported on 2026-11-01 that the sidebar changes shape between an entry's overview and its pages. On the overview, Maintain opens as a folder in the sidebar; clicking one of its pages shows a different sidebar, which is confusing.

What the code does today:

  • Fumadocs shows the sidebar of the deepest root folder on the current page's path (TreeContextProvider in fumadocs-ui/contexts/tree). Its path search checks a folder's index before its children.
  • The catalogue plugin marks the entry folder root: true, each track root: 'track' and each version line root: 'line' (src/lib/catalog-plugin.ts). The overview is the entry folder's index, so its path ends at the entry folder: the sidebar shows the whole entry, with Use and Maintain as stations that open in place.
  • A track page's path reaches its track or line, so its sidebar shows only that track's stations, as top-level cards. The same sections are nested on the overview and top-level on a page.
  • The planet row (src/components/docs/track-switch.tsx) marks the current side from the URL; on the overview it marks neither.

The owner chose that the overview shows exactly the sidebar of a track page.

Decision

  1. The overview shows its default track's sidebar. The default track is Use when the entry has one (its latest line, or dev when nothing is released), otherwise Maintain. The sidebar on the overview is that track's: its stations as top-level cards, one open at a time (ADR-0023). When the entry has both tracks, the planet row marks the default track's side as current: the sun for Use, the moon for Maintain. The other side's button opens that track, as today.
  2. Every track's sidebar starts with the overview. An Overview item, linking to /<slug>, is the first item of each Use line, of an unversioned Use and of Maintain, on the top-level arc above the stations. On the overview it is the current page. From any page the reader returns to the overview from the same place.
  3. Built in the page tree. The catalogue plugin's root hook detaches the entry folder's index and puts an Overview item for the same page first in each line, unversioned Use and Maintain, with Use before Maintain among the entry's children, so Fumadocs resolves the overview into the default track. The catalogue's own reads (an entry's URL, the Use, Maintain and line links) skip the Overview item. No change to Fumadocs, no new dependency.
  4. The moon picker on the overview lists the lines as on any Use page. Choosing another line keeps the reader on the overview with that line's sidebar, as Fumadocs does for a page that every line holds.
  5. Unchanged: the overview page itself (the planet header and the entry's index.mdx), its URL, its Markdown, search records and llms.txt. This site's overview, /docs, has only Maintain, so it shows Maintain's stations under Overview.

Options considered

ConcernOptionProsConsVerdict
Overview sidebarA — the default track's sidebarOne sidebar everywhere; nothing changes shape when the reader clicks into a pageThe overview looks like part of Use (or Maintain)Chosen (owner)
Overview sidebarB — the planet row and two links, Use → and Maintain →Simple; nothing expandsA third sidebar shape, shown only on the overviewRejected (owner)
Overview sidebarC — the whole entry on every pageOne shape everywhereLong sidebars; undoes ADR-0013's scoped navigationRejected (owner)
BuildA — the page tree's root hookOne place; Fumadocs resolves it like any pageThe overview item appears in several places of the tree, so tree readers skip itChosen
BuildB — a separate tree passed for the overviewNo duplicate itemsDocsLayout is in the shared layout and takes one tree; a second layout for overviews onlyRejected
Back to the overviewA — an Overview item first in every trackSame place on every page; the reader sees where they areOne more row in each sidebarChosen
Back to the overviewB — only the planet chipNo extra rowThe chip is easy to miss as a linkRejected

Consequences

Positive

  • The sidebar keeps its shape from the overview into any page of the default track, and the sun and moon switch between the two tracks' sidebars everywhere.
  • The overview is one click away from every page, in the same place.

Negative / accepted trade-offs

  • On the overview, the sidebar shows Use's stations (or Maintain's), not both tracks; Maintain is the moon button away.
  • Each track's sidebar gains one row.
  • Fumadocs' previous and next links on the first page of a track now point back to the overview.

Content invariants

None touched: pages, URLs, Markdown, search records and llms.txt stay as they are.

Security considerations

None — this change touches no data, no endpoint and no secret. It rearranges the sidebar's page tree, which holds only public pages.

Implementation notes

  • src/lib/catalog-plugin.ts: the root hook (decision 3), as overviewInTracks(), tested on its own. The overview is the entry folder's index, or a child page when the entry's meta.json lists "index" in pages (this site's does); both move the same way. withoutOverviewItems() gives llms.txt the tree as written (src/lib/source.ts).
  • src/lib/catalog.ts: an entry's URL is its overview page's; the Use, Maintain and line links, and the home page's track previews, skip the Overview item.
  • src/components/docs/track-switch.tsx: on the overview, the default track's side is current (decision 1), through currentSide() in src/lib/overview-sidebar.ts.
  • The moon picker: Fumadocs links each line to its folder's first page, which is now the Overview item, so the layout's tab transform (src/app/(site)/layout.tsx) links each line to its first page after it (folderUrls() and lineLink()).
  • Decision 4 is not met as written. From the overview, choosing another line cannot keep the reader on the overview with that line's sidebar: the overview is one URL, and Fumadocs resolves it to the first line on its path, the latest. Choosing another line from the overview opens that line's first page. From any other page the picker keeps the reader on the same page, as before. Superseded by ADR-0026, which keeps this behaviour.
  • Tests (ADR-0007): the tree (Overview first in each line, unversioned Use and Maintain; Use before Maintain; the entry folder without its index; an overview listed in pages; an entry without an overview; folders outside the catalogue; this site's Maintain-only entry; the tree restored for llms.txt), the current side and the line links as pure functions (src/lib/overview-tree.test.ts, src/lib/overview-sidebar.test.ts). The catalogue links are read from the built site, not unit-tested: catalog.ts reads the loaded source.
  • Checked in Chrome on localhost at desktop width, with a temporary invented package (content/lodestar/, a latest and a dev line, two Maintain pages; deleted afterwards) and /docs: the overview shows the v0.1 sidebar with Overview current and the sun current; a Use page and a Maintain page start with Overview; the moon picker links each line to its own first page; the hero and planet row link to the first Use and Maintain pages; /docs shows Maintain's stations under Overview; use/latest and a removed line still redirect; llms.txt lists each overview once, under its entry. Phone width (the drawer) was not seen.
  • bun run test, bun run types:check and bunx next build pass; bun run lint is reported while it stays blocked.

Docs to update on implementation

ADR-0024 — A project can span several repositories

A project made of several repositories lists them in its catalogue, with one primary, and gives each its own folder in each track.

ADR-0026 — The moon picker on an overview opens a line's first page

On an overview, choosing a version line in the moon picker opens that line's first page, since the overview itself has one copy.

On this page

7 min read
  1. Context
  2. Decision
  3. Options considered
  4. Consequences
  5. Content invariants
  6. Security considerations
  7. Implementation notes
  8. Docs to update on implementation