The docs TOC aside

How the docs table of contents uses Goatboat’s stored headings in a sticky desktop aside and a compact mobile layout, with active-section highlighting.

The problem

The site already had a page aside intended for supplementary navigation, and Goatboat already stores a toc for Markdown pages. But the TOC wasn't being rendered in that aside. The layout also needed to support three placements: a sticky right rail on desktop, and a TOC between the site navigation and article on smaller screens.

What the first slice does

The catch-all content route passes the current row's stored toc into the existing aside. Pages without TOC entries don't render an empty aside.

The shared PageLayout owns placement:

  • At desktop widths (64rem and wider), the site navigation and article occupy the left column; the aside occupies the right column and sticks 1.5rem from the top. It has a viewport-bounded height and scrolls independently when long.
  • From 40rem to 64rem, navigation, aside, and article stack in that order.
  • Below 40rem, the desktop navigation is hidden because the site header has its own mobile menu; the aside appears first, immediately below the header and before the article.

The desktop grid has no row gap. The article already has its own top padding, and adding a grid row gap caused an unwanted extra margin between navigation and article.

One TOC component

TableOfContents receives Goatboat's { depth, text, id }[]. It renders the links in the initial HTML, so the TOC is present in the server response. Markdown headings already render matching IDs using the same slugging rules as Goatboat's stored TOC.

The component uses IntersectionObserver in the browser to highlight the section currently crossing the reading position. That active marker is a progressive enhancement; navigation links and heading IDs exist before hydration.

The data boundary today

Markdown documents already have toc values generated from their bodies. Code-backed TSX pages currently don't have synchronized heading data, so they won't get a TOC unless their row has entries. The aside and TOC component are format-agnostic; the remaining work is populating the same toc field for TSX routes.

Extending it to /tests

The same PageLayout aside works for test pages. A test page that has a stored TOC can pass it to the same TableOfContents; there should not be a second tests-specific TOC implementation. Later, the route-sync action can extract TSX headings into the existing toc contract, enabling code-backed docs and tests to use the same rendered aside.

Files involved

  • src/components/site/page-layout.tsx and page-layout.module.css: placement and sticky behavior.
  • src/components/site/table-of-contents.tsx and table-of-contents.module.css: links and active-section state.
  • src/app/[...path]/page.tsx: supplies the row's stored TOC to the aside.
  • src/components/markdown/MarkdownRenderer.tsx: heading IDs for Markdown match the stored TOC IDs.
  • Layouts with route groups

    The plan to give each kind of page its own layout with Next.js route groups: (site), (notes) with a left notes aside, (bare), and (artifacts) for self-contained HTML files.

  • Highlight

    The Highlight text component: a faint blue tint with square corners, whose side padding repeats on every line it wraps across.

  • UI stress test

    Nested components stacked inside each other, like bold and code inside links and tables inside lists, to find where the styles break.

  • Route groups

    An interactive explainer of Next.js route groups: how folders in parentheses leave the URL, share layouts, opt pages in and out, and isolate loading and error states.