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.

Branch: route-groups, from main. Part A is done and committed there (4d97b3b, 43e8915), not yet merged. The code block work is on code-block-expand.

  • Part A, the move: done. Route groups and folders only; every page looks as it did.
  • Part B, the notes layout: next. A small sticky top bar on notes pages instead of the site header.

The groups

text
src/app/
  layout.tsx            root: <html>, <body>, fonts, metadata, providers. Nothing visual.
  (site)/layout.tsx     the site: header, frame, footer. Most pages.
  (notes)/layout.tsx    project notes pages. Same chrome as (site) for now; its own top bar in Part B.
  (bare)/               later: a page draws everything itself (the contact card).
  (artifacts)/          later: self-contained HTML files, served as they are.
  • One root layout, so moving between groups is a normal client navigation. Two root layouts would force a full page reload.
  • URLs don't change. Route groups add nothing to the URL, and the route sync ignores (group) folders, so every page kept its URL and its goatboat ID.

Part A: what changed

text
src/app/
  layout.tsx                    root: html, body, fonts, metadata, TooltipProvider, MobileMenuProvider
  layout.module.css             only .body
  globals.css  fonts.ts  fonts/

  (site)/
    layout.tsx                  <SiteChrome>
    not-found.tsx               the 404, inside the site chrome
    page.tsx                    home
    [...path]/page.tsx          markdown pages: renders <ContentPage path=…>
    about/  contact/  links/  my-stack/  new/  notes/  resume/
    projects/
      page.tsx                  /projects
      [slug]/page.tsx           a project's home page

  (notes)/
    layout.tsx                  <SiteChrome>, for now
    not-found.tsx               re-exports the (site) 404
    projects/
      [slug]/notes/
        page.tsx                a project's notes front page
        [...path]/page.tsx      NEW: markdown notes, renders <ContentPage path=…>
      goatboat/notes/**         goatboat's code notes
      jaygriff-v4/notes/**      this site's code notes

src/components/site/
  site-chrome.tsx (+ .module.css)    NEW: header, .shell frame, footer; shared by both layouts
  content-page.tsx (+ .module.css)   the markdown page renderer, moved out of the catch-all and shared by both
  • Slice 1 (4d97b3b): root layout stripped to nothing visual; every route moved into (site). Pure moves, plus one more ../ on 46 CSS @reference paths.
  • Slice 2 (43e8915): the notes routes moved from (site) to (notes) (same depth, so no path changes). Chrome and the markdown renderer became shared components, so the two groups can't drift. A notes catch-all was added, so markdown notes are in (notes) too.
  • The 404: every URL matches a catch-all, so a missing page calls notFound() from inside a group and gets that group's 404, with the chrome. No root not-found needed.
  • A fix on the way: getCurrentRow in page-meta.ts called headers() inside a try. During the build, headers() throws on purpose to mark a page dynamic; the catch logged that as "Dynamic server usage" errors. The path is now read before the try, so only goatboat failures are caught.
  • Checked: the same 38 pages with the same goatboat IDs (route sync dry run against the last commit). Pages in both groups, a markdown note, a code note, a deep catch-all path, and missing pages in each group all render with the chrome. next build passes.
  • Still there on purpose: the :has([data-notes-aside]) frame widening and --notes-offset header shift (now in site-chrome.module.css and header.module.css). They go in Part B, when notes pages stop using the site header.

Part B: the notes top bar

Decided:

  • A small sticky top bar on notes pages, not very tall, in place of the site header (no site name, no site nav).
  • Left: the breadcrumbs, unchanged for now. Then the notes and contents buttons, to the right of the breadcrumbs.
  • Right: the hamburger menu, which is how you reach the rest of the site.
  • All of it sticks to the top while scrolling.
  • The footer stays on notes pages.
  • The (notes) layout stops using SiteChrome and renders this bar instead. The :has and --notes-offset CSS is removed.

To decide:

  • Desktop asides: with the notes and contents buttons in the bar, does the left notes column (from 80rem) and the right "On this page" column (from 56rem) stay as well, or do the buttons replace them at every width?
  • Long trails: when the breadcrumbs, the two buttons and the hamburger don't fit on a phone, what gives first: the breadcrumbs truncate from the left, or the buttons become icons?
  • The page jump on heading links: the bar's height replaces today's phone header offset (scroll-padding-top: 4rem), at every width on notes pages.

Later

  • (bare): when the contact card needs it.
  • (artifacts): single HTML files with their own styles and scripts (mockups, demos), served untouched by a route handler with a Content-Security-Policy: sandbox allow-scripts header, or shown in a sandboxed iframe. Their scripts would otherwise run as the site. Open questions:
    • Where do the files live: in this repo, or in goatboat?
    • Do they fill the whole tab, or sit framed in a site page?
    • What are their URLs?
    • Do they belong in goatboat's tree at all?
  • 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.

  • Tabs

    PageTabs: several views of one topic on a page, linkable by URL hash and fully readable by crawlers.

  • Text colors

    Every text color token with its value and where it's used, plus before-and-after comparisons for consolidating them.