@beatzball/create-litro 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # create-litro
 
+## 0.2.0
+
+### Minor Changes
+
+- 78fdaf6: Add `starlight` recipe — Astro Starlight-inspired docs + blog site scaffolded as Lit web components with full SSG support.
+
+  `npm create @beatzball/litro my-docs -- --recipe starlight` scaffolds a static docs + blog site with:
+
+  - **Layout components**: `<starlight-page>`, `<starlight-header>`, `<starlight-sidebar>`, `<starlight-toc>`
+  - **UI components**: `<sl-card>`, `<sl-card-grid>`, `<sl-badge>`, `<sl-aside>`, `<sl-tabs>`, `<sl-tab-item>`
+  - **Pages**: `/` (splash), `/docs/:slug`, `/blog`, `/blog/:slug`, `/blog/tags/:tag` — all SSG-prerendered
+  - **`--sl-*` CSS token layer** with dark/light mode toggle and no flash of unstyled content
+  - **`server/starlight.config.js`** — site title, nav links, sidebar groups
+  - SSG-only (no `--mode` flag needed)
+
+## 0.1.4
+
+### Patch Changes
+
+- 76d3bc7: fix: client-side navigation links do not work on first load
+
+  `<litro-link>` clicks were silently no-ops in scaffolded apps because of
+  three compounding bugs.
+
+  ***
+
+  **Bug 1 — Empty route table on init** (`LitroOutlet`, `app.ts`)
+
+  `app.ts` set `outlet.routes` inside a `DOMContentLoaded` callback (a
+  macrotask). By that point Lit's first-update microtask had already fired,
+  so `firstUpdated()` ran with `routes = []` and the router was initialised
+  with no routes.
+
+  _Fix — `LitroOutlet`_: Replace `@property({ type: Array }) routes` with a
+  plain getter/setter. The setter calls `router.setRoutes()` directly when
+  the router is already initialised, without going through Lit's render cycle
+  (which would crash with "ChildPart has no parentNode" because
+  `firstUpdated()` removes Lit's internal marker nodes to give the router
+  ownership of the outlet's subtree).
+
+  _Fix — `app.ts`_ (fullstack recipe template + playground): Set
+  `outlet.routes` synchronously after imports rather than inside a
+  `DOMContentLoaded` callback. Module scripts are deferred by the browser;
+  by the time they execute the DOM is fully parsed and `<litro-outlet>` is
+  present.
+
+  ***
+
+  **Bug 2 — Click handler never attached on SSR'd pages** (`LitroLink`)
+
+  `@lit-labs/ssr` adds `defer-hydration` to custom elements inside shadow
+  DOM. `@lit-labs/ssr-client` patches `LitElement.prototype.connectedCallback`
+  to block Lit's update cycle when this attribute is present. A `@click`
+  binding on the shadow `<a>` is a Lit binding — it is never attached until
+  `defer-hydration` is removed, which only happens when the parent component
+  hydrates. For page components that are never hydrated client-side (because
+  the router replaces the SSR content before they load), `<litro-link>`
+  elements inside them never receive a click handler.
+
+  This is why the playground appeared to work: its home page has no
+  `<litro-link>` elements. The fullstack generator template does, so clicks
+  on the SSR'd page were silently ignored.
+
+  _Fix_: Move the click handler from a `@click` binding on the shadow `<a>`
+  to the HOST element via `addEventListener('click', ...)` registered in
+  `connectedCallback()` (before `super.connectedCallback()`). The host
+  listener runs in `LitroLink`'s own `connectedCallback` override, which
+  executes before the `@lit-labs/ssr-client` patch checks for
+  `defer-hydration`. This ensures the handler is active immediately after the
+  element connects to the DOM, even for SSR'd elements on first load.
+
+  The shadow `<a>` is kept without a `@click` binding — it exists for
+  progressive enhancement (no-JS navigation) and accessibility (cursor,
+  focus, keyboard navigation).
+
+  ***
+
+  **Bug 3 — `_resolve()` race condition** (`LitroRouter`)
+
+  `setRoutes()` calls `_resolve()` immediately for the current URL. If the
+  user clicks a link before that initial `_resolve()` completes (e.g. while
+  the page action's dynamic import is in flight), a second `_resolve()` call
+  starts concurrently. If the first call (for `/`) completes after the second
+  (for `/blog`), it overwrites the blog page with the home page.
+
+  _Fix_: Add a `_resolveToken` monotonic counter. Each `_resolve()` call
+  captures its own token at the start and checks it after every `await`. If
+  the token has advanced, a newer navigation superseded this one and the call
+  returns without touching the DOM.
+
+  ***
+
+  **Bug 4 — `@property()` decorators silently dropped by esbuild TC39 transform** (`LitroLink`)
+
+  esbuild 0.21+ uses the TC39 Stage 3 decorator transform. In that mode,
+  Lit's `@property()` decorator only handles `accessor` fields; applied to a
+  plain field (`href = ''`) it is silently not applied. As a result `href`,
+  `target`, and `rel` were absent from `observedAttributes`, so
+  `attributeChangedCallback` was never called during element upgrade, leaving
+  `this.href = ''` forever regardless of what the HTML attribute said.
+
+  _Fix_: Replace the three `@property()` field decorators with a
+  `static override properties = { href, target, rel }` declaration. Lit reads
+  this static field at class-finalization time via `finalize()`, which runs
+  before the element is defined in `customElements`, ensuring the properties
+  are correctly registered in `observedAttributes`.
+
+  ***
+
+  Adds a new `LitroOutlet.test.ts` test file (6 tests) covering the
+  synchronous and late-assignment code paths, the setter guard, SSR child
+  clearing, and the `LitroRouter` constructor call.
+
+  Updates `LitroLink.test.ts` (12 tests) to dispatch real `MouseEvent`s on
+  the host element (exercising the `addEventListener` path) rather than
+  calling the private handler directly by name.
+
+  ***
+
+  **Template fix — `@state() declare serverData` incompatible with jiti/SSG**
+
+  The fullstack recipe template used `@state() declare serverData: T | null` to
+  narrow the `serverData: unknown` type inherited from `LitroPage`. The `declare`
+  modifier emits no runtime code, but jiti's oxc-transform (used in SSG mode to
+  load page files) throws "Fields with the 'declare' modifier cannot be
+  initialized here" under TC39 Stage 3 decorator mode.
+
+  _Fix_: Remove `@state() declare serverData` from both page templates. Use a
+  local type cast in `render()` instead: `const data = this.serverData as T | null`.
+  The property is already reactive (declared as `@state() serverData = null` in
+  `LitroPage`). Updated `LitroPage.ts` JSDoc and `DECISIONS.md` to document this
+  pattern and warn against `declare` fields in subclasses.
+
 ## 0.1.3
 
 ### Patch Changes

package/dist/recipes/fullstack/template/app.ts

@@ -10,11 +10,14 @@ import '@beatzball/litro/runtime/LitroLink.js';
 // emptyOutDir does not delete it between builds.
 import { routes } from './routes.generated.js';
 
-document.addEventListener('DOMContentLoaded', () => {
-  const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
-  if (outlet) {
-    outlet.routes = routes;
-  } else {
-    console.warn('[litro] <litro-outlet> not found — router will not start.');
-  }
-});
+// Set routes synchronously. By the time this module-script executes (all
+// module scripts are deferred), the HTML is fully parsed and <litro-outlet>
+// is already in the DOM. Setting outlet.routes here — before Lit's first
+// update microtask fires — ensures firstUpdated() sees the real route table
+// rather than the empty default, so the router starts correctly.
+const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
+if (outlet) {
+  outlet.routes = routes;
+} else {
+  console.warn('[litro] <litro-outlet> not found — router will not start.');
+}

package/dist/recipes/fullstack/template/pages/blog/[slug].ts

@@ -1,5 +1,5 @@
 import { html } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
+import { customElement } from 'lit/decorators.js';
 import { LitroPage } from '@beatzball/litro/runtime';
 import { definePageData } from '@beatzball/litro';
 import type { LitroLocation } from '@beatzball/litro-router';
@@ -27,8 +27,6 @@ export async function generateRoutes(): Promise<string[]> {
 
 @customElement('page-blog-slug')
 export class BlogPostPage extends LitroPage {
-  @state() declare serverData: PostData | null;
-
   // Called by LitroRouter on client-side navigation to fetch data for the new slug.
   override async fetchData(location: LitroLocation): Promise<PostData> {
     const slug = location.params['slug'] ?? '';
@@ -40,10 +38,11 @@ export class BlogPostPage extends LitroPage {
   }
 
   render() {
+    const data = this.serverData as PostData | null;
     return html`
       <article>
-        <h1>${this.serverData?.title ?? 'Loading…'}</h1>
-        <p>${this.serverData?.content ?? ''}</p>
+        <h1>${data?.title ?? 'Loading…'}</h1>
+        <p>${data?.content ?? ''}</p>
         <litro-link href="/blog">← Back to Blog</litro-link>
         &nbsp;|&nbsp;
         <litro-link href="/">← Home</litro-link>

package/dist/recipes/fullstack/template/pages/index.ts

@@ -1,5 +1,5 @@
 import { html } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
+import { customElement } from 'lit/decorators.js';
 import { LitroPage } from '@beatzball/litro/runtime';
 import { definePageData } from '@beatzball/litro';
 
@@ -18,8 +18,6 @@ export const pageData = definePageData(async (_event) => {
 
 @customElement('page-home')
 export class HomePage extends LitroPage {
-  @state() declare serverData: HomeData | null;
-
   // Called on client-side navigation (not on the initial SSR load).
   override async fetchData() {
     const res = await fetch('/api/hello');
@@ -27,11 +25,12 @@ export class HomePage extends LitroPage {
   }
 
   render() {
+    const data = this.serverData as HomeData | null;
     if (this.loading) return html`<p>Loading…</p>`;
     return html`
       <main>
-        <h1>${this.serverData?.message ?? 'Welcome to {{projectName}}'}</h1>
-        <p><small>Rendered at: ${this.serverData?.timestamp ?? '—'}</small></p>
+        <h1>${data?.message ?? 'Welcome to {{projectName}}'}</h1>
+        <p><small>Rendered at: ${data?.timestamp ?? '—'}</small></p>
         <nav>
           <litro-link href="/blog">Go to Blog →</litro-link>
         </nav>

package/dist/recipes/starlight/recipe.config.d.ts

@@ -0,0 +1,4 @@
+import type { LitroRecipe } from '../../src/types.js';
+declare const recipe: LitroRecipe;
+export default recipe;
+//# sourceMappingURL=recipe.config.d.ts.map

package/dist/recipes/starlight/recipe.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe.config.d.ts","sourceRoot":"","sources":["../../../recipes/starlight/recipe.config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,QAAA,MAAM,MAAM,EAAE,WAMb,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/recipes/starlight/recipe.config.js

@@ -0,0 +1,9 @@
+const recipe = {
+    name: 'starlight',
+    displayName: 'Starlight (docs + blog)',
+    description: 'Astro Starlight-inspired docs and blog site with Lit web components',
+    mode: 'ssg',
+    contentLayer: 'content',
+};
+export default recipe;
+//# sourceMappingURL=recipe.config.js.map

package/dist/recipes/starlight/recipe.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe.config.js","sourceRoot":"","sources":["../../../recipes/starlight/recipe.config.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAgB;IAC1B,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,yBAAyB;IACtC,WAAW,EAAE,qEAAqE;IAClF,IAAI,EAAE,KAAK;IACX,YAAY,EAAE,SAAS;CACxB,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/recipes/starlight/recipe.config.ts

@@ -0,0 +1,11 @@
+import type { LitroRecipe } from '../../src/types.js';
+
+const recipe: LitroRecipe = {
+  name: 'starlight',
+  displayName: 'Starlight (docs + blog)',
+  description: 'Astro Starlight-inspired docs and blog site with Lit web components',
+  mode: 'ssg',
+  contentLayer: 'content',
+};
+
+export default recipe;

package/dist/recipes/starlight/template/_data/metadata.js

@@ -0,0 +1,10 @@
+export default {
+  title: '{{projectName}}',
+  url: 'https://example.com',
+  language: 'en',
+  description: 'Documentation and blog powered by Litro',
+  author: {
+    name: 'Your Name',
+    email: 'your@email.com',
+  },
+};

package/dist/recipes/starlight/template/app.ts

@@ -0,0 +1,18 @@
+// CRITICAL: must be first — patches LitElement before any component is loaded.
+import '@lit-labs/ssr-client/lit-element-hydrate-support.js';
+
+// Client runtime: router outlet and link custom elements.
+import '@beatzball/litro/runtime/LitroOutlet.js';
+import '@beatzball/litro/runtime/LitroLink.js';
+
+// Routes generated by the page scanner before each vite build.
+import { routes } from './routes.generated.js';
+
+document.addEventListener('DOMContentLoaded', () => {
+  const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
+  if (outlet) {
+    outlet.routes = routes;
+  } else {
+    console.warn('[litro] <litro-outlet> not found — router will not start.');
+  }
+});

package/dist/recipes/starlight/template/content/blog/.11tydata.json

@@ -0,0 +1 @@
+{ "tags": ["posts"] }

package/dist/recipes/starlight/template/content/blog/release-notes.md

@@ -0,0 +1,44 @@
+---
+title: Release Notes
+date: 2026-01-10
+description: What's new in this version of the Starlight recipe for Litro.
+tags:
+  - posts
+  - release
+---
+
+## Starlight Recipe 0.1.0
+
+The first release of the Starlight recipe for Litro. This scaffolds a fully static docs and blog site with Starlight's design system, implemented entirely as Lit web components.
+
+### What's New
+
+**Layout components**
+
+- `<starlight-page>` — three-column grid layout (sidebar | content | TOC)
+- `<starlight-header>` — top navigation with dark/light mode toggle
+- `<starlight-sidebar>` — grouped navigation with active-item highlighting
+- `<starlight-toc>` — table of contents extracted from headings
+
+**UI components**
+
+- `<sl-card>` and `<sl-card-grid>` — feature cards for the splash page
+- `<sl-badge>` — inline color-coded chips (note, tip, caution, danger)
+- `<sl-aside>` — callout boxes with icons and colored borders
+- `<sl-tabs>` and `<sl-tab-item>` — tabbed content sections
+
+**CSS design system**
+
+All colors, fonts, and spacing are defined as `--sl-*` custom properties in `public/styles/starlight.css`. Override any token to customize the theme.
+
+**Dark mode**
+
+A FOUC-free theme toggle that reads/writes `localStorage` and sets `data-theme` on `<html>`. Implemented as a synchronous inline script in `<head>`.
+
+**Content layer**
+
+Docs and blog content live under `content/`. The Litro content layer scans Markdown files, parses frontmatter, renders HTML, and exposes everything via the `litro:content` virtual module.
+
+### Breaking Changes
+
+None — this is the initial release.

package/dist/recipes/starlight/template/content/blog/welcome.md

@@ -0,0 +1,44 @@
+---
+title: Welcome to {{projectName}}
+date: 2026-01-15
+description: Introducing the {{projectName}} docs and blog site, built with Litro and Starlight-inspired components.
+tags:
+  - posts
+  - welcome
+---
+
+## Hello, World!
+
+Welcome to **{{projectName}}** — a docs and blog site scaffolded with Litro's Starlight recipe.
+
+This blog is powered by Litro's content layer. Each `.md` file in `content/blog/` becomes a post, available at `/blog/<slug>`. Write in plain Markdown; the framework handles rendering, tag indexing, and static generation.
+
+## What's Included
+
+- **Docs site** at `/docs/` — structured documentation with a sidebar, table of contents, and prev/next navigation
+- **Blog** at `/blog/` — a chronological listing of posts with tag filtering
+- **Dark mode** — a theme toggle in the header that persists to `localStorage`
+- **CSS design tokens** — all colors, fonts, and spacing via `--sl-*` custom properties
+
+## Writing Posts
+
+Create a new `.md` file in `content/blog/`:
+
+```markdown
+---
+title: My Post Title
+date: 2026-02-01
+description: A short summary.
+tags:
+  - posts
+  - my-tag
+---
+
+Post body here.
+```
+
+Every post in `content/blog/` inherits the `posts` tag via `blog.11tydata.json`. List any additional tags in the post frontmatter — tag pages are generated automatically at `/blog/tags/<tag>`.
+
+## Building
+
+Run `pnpm build` to generate the static HTML for every route, then `pnpm preview` to serve it locally.

package/dist/recipes/starlight/template/content/docs/.11tydata.json

@@ -0,0 +1 @@
+{ "section": "docs" }

package/dist/recipes/starlight/template/content/docs/configuration.md

@@ -0,0 +1,77 @@
+---
+title: Configuration
+description: Configure your Starlight site — title, navigation, sidebar, and theme.
+sidebar:
+  order: 3
+---
+
+## Site Config
+
+All site-wide settings live in `server/starlight.config.js`:
+
+```js
+export const siteConfig = {
+  title: 'My Docs',
+  description: 'Documentation and blog powered by Litro',
+  logo: null,
+  editUrlBase: null,
+  nav: [...],
+  sidebar: [...],
+};
+```
+
+### `title`
+
+The site title shown in the header and used in `<title>` tags.
+
+### `description`
+
+A short description used in meta tags.
+
+### `editUrlBase`
+
+If set (e.g. `'https://github.com/you/repo/edit/main'`), each doc page shows an "Edit this page" link pointing to the source file on GitHub.
+
+### `nav`
+
+Top-level navigation links shown in the header:
+
+```js
+nav: [
+  { label: 'Docs', href: '/docs/getting-started' },
+  { label: 'Blog', href: '/blog' },
+],
+```
+
+### `sidebar`
+
+Sidebar groups, each with a label and array of items. Each item has a `label` and a `slug` (the filename without `.md` under `content/docs/`):
+
+```js
+sidebar: [
+  {
+    label: 'Start Here',
+    items: [
+      { label: 'Getting Started', slug: 'getting-started' },
+      { label: 'Installation',    slug: 'installation' },
+    ],
+  },
+],
+```
+
+## CSS Design Tokens
+
+The visual theme is controlled by CSS custom properties in `public/styles/starlight.css`. Override any `--sl-*` variable to customize colors, fonts, and spacing:
+
+```css
+:root {
+  --sl-color-accent: #7c3aed;    /* primary accent color */
+  --sl-font-sans: ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Dark mode tokens are under `[data-theme='dark'] { ... }`.
+
+## Dark / Light Mode
+
+The theme toggle button in the header reads and writes `localStorage.getItem('sl-theme')`. A FOUC-prevention inline script (injected via `routeMeta.head`) sets `data-theme` on `<html>` before first paint.

package/dist/recipes/starlight/template/content/docs/getting-started.md

@@ -0,0 +1,53 @@
+---
+title: Getting Started
+description: Learn how to set up and run your Litro Starlight docs site.
+sidebar:
+  order: 1
+---
+
+## Welcome
+
+You've just scaffolded a docs and blog site powered by **Litro** — a fullstack web framework that combines Lit web components with Nitro's server engine.
+
+This site is a **static site** (SSG mode). Run `pnpm build` to pre-render every page to HTML, then `pnpm preview` to serve the output locally.
+
+## Prerequisites
+
+You'll need **Node.js 20+** and a package manager (`pnpm`, `npm`, or `yarn`).
+
+## Install Dependencies
+
+```bash
+pnpm install
+```
+
+## Start the Dev Server
+
+```bash
+pnpm dev
+```
+
+The dev server starts on `http://localhost:3030`. Changes to Lit components and Markdown content are reflected immediately.
+
+## Project Structure
+
+```
+my-docs/
+  pages/          Lit page components (filename = route)
+  src/
+    components/   Starlight layout and UI components
+  content/
+    docs/         Documentation Markdown files
+    blog/         Blog post Markdown files
+  server/
+    starlight.config.js   Site title, nav, and sidebar config
+  public/
+    styles/       CSS design tokens (--sl-* variables)
+```
+
+## Next Steps
+
+- Edit `server/starlight.config.js` to update the site title, nav links, and sidebar groups.
+- Add new docs pages to `content/docs/` — each `.md` file becomes a route under `/docs/`.
+- Write blog posts in `content/blog/`.
+- Run `pnpm build` to generate the static site.

package/dist/recipes/starlight/template/content/docs/guides-deploying.md

@@ -0,0 +1,79 @@
+---
+title: Deploying
+description: Deploy your Litro Starlight docs site to any CDN or static hosting platform.
+sidebar:
+  order: 5
+---
+
+## Build
+
+Generate the static HTML output:
+
+```bash
+pnpm build
+```
+
+This runs `litro build` under the hood, which:
+
+1. Scans `pages/` to discover all routes
+2. Calls `generateRoutes()` on each dynamic page to enumerate all paths
+3. Pre-renders every path to a `.html` file in `.output/public/`
+
+## Output
+
+After a successful build, the static site is in `.output/public/`. You can serve this directory from any web server or CDN.
+
+## Platforms
+
+### Vercel
+
+```bash
+# vercel.json
+{
+  "outputDirectory": ".output/public"
+}
+```
+
+Or connect the repository in the Vercel dashboard — Vercel detects the static output automatically.
+
+### Netlify
+
+```toml
+# netlify.toml
+[build]
+  command = "pnpm build"
+  publish = ".output/public"
+```
+
+### Cloudflare Pages
+
+Set the build output directory to `.output/public` in the Cloudflare Pages dashboard.
+
+### GitHub Pages
+
+Add a GitHub Actions workflow:
+
+```yaml
+- name: Build
+  run: pnpm build
+
+- name: Deploy
+  uses: peaceiris/actions-gh-pages@v3
+  with:
+    github_token: GITHUB_TOKEN  # set via repository secrets
+    publish_dir: .output/public
+```
+
+## Custom Domain
+
+Configure the custom domain in your hosting provider's dashboard. No Litro-specific changes are needed — the static output is plain HTML, CSS, and JS.
+
+## Preview Locally
+
+Before deploying, preview the production build locally:
+
+```bash
+pnpm preview
+```
+
+This serves the `.output/` directory using Nitro's static preset server on `http://localhost:3030`.

package/dist/recipes/starlight/template/content/docs/guides-first-page.md

@@ -0,0 +1,64 @@
+---
+title: Your First Page
+description: Create a new docs page and add it to the sidebar navigation.
+sidebar:
+  order: 4
+---
+
+## Create a Markdown File
+
+Add a new `.md` file to `content/docs/`. The filename (without extension) becomes the URL slug.
+
+For example, create `content/docs/my-topic.md`:
+
+```markdown
+---
+title: My Topic
+description: A brief description for SEO and the sidebar.
+---
+
+## Introduction
+
+Write your documentation here using standard Markdown.
+```
+
+## Add It to the Sidebar
+
+Open `server/starlight.config.js` and add an entry to the appropriate sidebar group:
+
+```js
+sidebar: [
+  {
+    label: 'My Section',
+    items: [
+      { label: 'My Topic', slug: 'my-topic' },
+    ],
+  },
+],
+```
+
+The `slug` must match the filename (without `.md`). The page will be available at `/docs/my-topic`.
+
+## Frontmatter Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | Yes | Page title (shown in sidebar and `<title>`) |
+| `description` | `string` | No | Short summary for SEO |
+| `sidebar.order` | `number` | No | Controls sort order within the sidebar group |
+| `sidebar.label` | `string` | No | Override the label shown in the sidebar |
+
+## Markdown Features
+
+This site supports **GitHub Flavored Markdown (GFM)**, including:
+
+- Tables (like the one above)
+- Fenced code blocks with syntax highlighting
+- Task lists: `- [ ] Todo`
+- Strikethrough: `~~text~~`
+
+Headings (`##`, `###`, `####`) are automatically extracted to build the table of contents shown on the right side of each docs page.
+
+## After Adding a Page
+
+Run `pnpm build` to regenerate the static HTML for all routes, then `pnpm preview` to verify the new page appears in the sidebar and TOC.