Working notes for Claude

Quick reference for editing this site. README.md covers user-facing setup; this file covers things that help with code changes.

Stack

• Lume 3 (Deno static site generator) with SSX as the JSX runtime (lume/jsx-runtime).
• TypeScript everywhere. No React, no Node, no npm install step.
• Deployed to GitHub Pages: a push to main runs .github/workflows/deploy.yml (setup-deno → deno task build → publish _site/). Custom domain cbusby.dev is set in repo Settings → Pages and pinned by the root CNAME file (added via site.add("/CNAME")). www redirects to apex via a CNAME www → cdbusby.github.io DNS record.
• No custom response headers: GitHub Pages ignores _headers-style files, so caching/security headers fall back to GitHub's defaults.

Verify a change

deno task build    # full build to _site/ — fast (sub-second), run this after any change

Built HTML lives in _site/<route>/index.html. Use grep against those files to confirm rendered output rather than starting the dev server.

File conventions

Lume scans for files automatically — no manifest to update when adding a new .md or .tsx.

JSX / SSX gotchas

• Use class, not className. for instead of htmlFor (SSX still maps both, but match the codebase style).
• Fragments work (<>...</>).
• To render raw HTML (e.g. the markdown body in a layout), just emit {children} — when a JSX layout receives string content, Lume wraps it as {__html: ...} and SSX's escape function passes __html through unescaped.
• No hooks, no state, no useEffect. SSX is render-only. Browser-side JS goes in _includes/layout.vto <script> block.
• For attributes with hyphens (like transform-images), write them literally — SSX passes unknown props through.

Lume data API

Pages/layouts can be a function (data: Lume.Data) => JSX. Useful members:

• data.search.pages(query, sort) — query pages. Examples:
  • pages("url^=/training/ url!=/training/", "date=desc") — all training logs, newest first.
  • pages("url^=/reading/ url!=/reading/") — all book reviews.
• data.url, data.title, data.date, plus any frontmatter fields.
• children (layouts only) — the rendered body of the page using this layout.

Filters defined in _config.ts

Available in .vto templates as value |> filterName. In .tsx, prefer inline JS (the training-log.tsx layout duplicates formatDuration / activityTotals for this reason — keeps the file self-contained and typed).

• formatDuration(seconds) → "Xh Ym" or "Ym"
• activityTotals(days) → { run: {distance, seconds, count}, ... }
• groupByDate(items, "month"|"year", dateField)

Image pipeline

• Drop sources into images/<section>/. Reference via /images/... paths.
• Add transform-images="webp jpg <width1> <width2> ..." to <img> to generate responsive variants.
• The preprocessor in _config.ts auto-fills width / height from sharp metadata for hero, cover, and books[].cover frontmatter fields. No need to specify dimensions manually.
• Add class="fade-in" for the load-in animation (data-loaded set by JS in layout.vto).
• One LCP image per page should get loading="eager" fetchpriority="high"; the rest loading="lazy".

Training logs

• Day blocks with empty activities: [] render as "Rest" rows.
• activity.type of "run" shows full columns; "strength" collapses workout/distance/time/pace/HR into one cell-summary cell holding the notes.
• The layout (_includes/training-log.tsx) computes hasTotals and hasNotes and hides those sections entirely when empty (e.g. a full rest week).
• Prev/next pager at the bottom auto-links to adjacent logs by date.

Books

• Single source of truth: _data/books.yml. Books index reads this; the home page picks wip + latest reviewed entries from it.
• review: <slug> links a book to reading/<slug>.md. A preprocessor strips review: if the target review has draft: true (set LUME_DRAFTS=true env to keep drafts visible locally).

CSS

• Single styles.css at the root. Lightning CSS plugin handles minification.
• CSS custom properties defined at :root (colors, fonts, --measure for content width).
• Cache-busted with ?v={{ buildTime }} (set to Date.now() in _config.ts).
• Add new component styles at the bottom in a /* --- Section --- */ block.

Things to not do

• Don't add React, npm packages, or a bundler.
• Don't manually set width/height on <img> for hero/cover fields — the preprocessor does it.
• Don't write to _site/ — it's the build output, gitignored, blown away each build.
• Don't add new layouts without checking the existing pattern in _includes/ — book reviews use .vto, training logs use .tsx, both work fine.