Use the GA4 measurement ID Search Console expects and allow Google Tag Manager/Analytics in the CSP so gtag is not blocked. Add 301s from the old /posts, /writings, /tags, /archive, /about and /index.xml URLs to their current routes to clear the Search Console 404s.
- Fresh structure: Next.js App Router + Tailwind v4 at the repo root, exported
as static files (output: export) and served by static-web-server
- Remove the Strapi CMS, Astro app, Pagefind search, comments, old scripts,
Lighthouse config and compose files; content in content/ is now plain
markdown with YAML frontmatter
- Pages: About, Writing, Reading (3D bookshelf) and Portfolio, styled after
adammaj.com
- SEO: metadata and canonicals, JSON-LD, generated OG images, sitemap, robots,
RSS and JSON feeds, llms.txt
- Umami via PUBLIC_UMAMI_SCRIPT_URL / PUBLIC_UMAMI_WEBSITE_ID (build args)
- Dockerfile builds the export and serves it with sws.toml (security headers,
clean URLs, .well-known, OG image content type, immutable asset caching)
- Prettier and cspell for content with a husky/lint-staged pre-commit hook
- Old redirect list dropped to start from a clean slate
Nav bar & layout consistency
- Base.astro's `wide` layout now defaults on for every page (was opt-in),
fixing the nav bar wrapping differently depending on page width
- Icon buttons for search and theme toggle (magnifying glass, sun/moon),
replacing the plain "Search" text link and the "◐" glyph
- Search is now a Cmd/Ctrl+K modal over Pagefind (lazy-loaded on first
open) instead of a separate /search/ page, matching the old site
- Fixed the article page's TOC sitting with unwanted left padding relative
to the header (grid was center-justified instead of start-justified)
Smooth navigation
- Added Astro's ClientRouter for animated page transitions
- Every page-local script that only ran once at module load (three.js
hero, minimap, comments, book-spine carousel, scroll-to-top, reading
progress, theme toggle, Pagefind init) now re-initializes via
astro:page-load, with AbortController-based cleanup so window/document
listeners don't accumulate across client-side navigations
Restored from the legacy Zola site
- Reading progress bar (article pages) and scroll-to-top button
- Share buttons (X, Bluesky, LinkedIn, Reddit, HN, email) on writings
- Prev/next post navigation with the old label/title layout
- Utterances comments, wired to andwati/andwati.com with dark/light
theme sync
- YouTube embeds: any plain <iframe src="...youtube-nocookie.com...">
is now auto-wrapped in a responsive 16:9 container, gets
loading="lazy", and emits VideoObject JSON-LD — no shortcode needed
- LaTeX: $inline$ and $$block$$ math renders to static HTML via KaTeX at
build time (no client-side JS shipped for it)
- Tags page redesigned as a centered, alphabetical tag cloud
Removed the related-posts section per request.
Accessibility & contrast
- --accent (#d1502f) measured 4.0:1 on the light background, just under
WCAG AA's 4.5:1 for normal text — darkened to #a84025 (5.7:1), plus
matching light-mode-only fixes for the two hljs syntax colors and the
tip/warning callout colors that had the same problem in light mode
- Fixed heading-order violations (h1 straight to h3 with nothing at h2)
across the homepage, writings/portfolio/bookshelf/blogs lists, and tag
pages — introduced a shared .entry-title class for the h2 list titles
- Fixed inconsistent title-link underline colors: a plain <a> carries its
own default underline (in its own text color) instead of matching its
parent heading's accent-colored one — h1/h2/h3 anchors now explicitly
inherit the heading's decoration
- Bookshelf spine colors are generated per-title from a hash; the
lightness-based text-color heuristic could still produce sub-4.5:1
contrast for some hues (e.g. green) — now computes real WCAG contrast
and adjusts
Performance
- The three.js homepage hero was the single largest main-thread cost
site-wide (dragging that page's Lighthouse performance score to the low
80s while every other page scored 95+): three.js is now dynamically
imported only once the browser is idle (WebGL-support check split into
its own tiny module so unsupported browsers never fetch it at all), the
render loop is capped to ~30fps, and hover raycasting only runs on an
actual pointer move instead of every frame
SEO & structured data
- Self-referential canonical links site-wide (with override support for
posts first published elsewhere)
- Sitewide WebSite/Person JSON-LD, plus per-article BlogPosting,
BreadcrumbList, and (when applicable) VideoObject JSON-LD
- robots.txt explicitly welcomes AI/LLM crawlers (GPTBot, ClaudeBot,
PerplexityBot, Google-Extended, CCBot, etc.) and points at llms.txt
- Added an Atom feed (RSS and JSON Feed already existed)
- Sitemap now sets <lastmod> per entry from its own date/updated
frontmatter instead of leaving every URL at build time
Analytics & comments infra
- Self-hosted Umami wiring via PUBLIC_UMAMI_SCRIPT_URL/WEBSITE_ID
(apps/site/.env.example), no-ops until both are set
- sws.toml's CSP updated to allow utteranc.es and analytics.andwati.com —
without this both were silently blocked in production
Lighthouse CI
- @lhci/cli wired up against the built site (mobile + desktop configs),
`pnpm run lighthouse`, and a GitHub Actions workflow to run it on every
push/PR — reporting only for now, no failing thresholds
The Astro app in apps/site is now the production build (root Dockerfile
already builds it, not `zola build`), so the old Zola templates, Sass,
static assets, and build tooling are dead weight:
- templates/, sass/, static/, themes/, zola.toml, Makefile, bin/update-zola
- content/posts/ (fully migrated to content/writings/) and the legacy
content/archive, content/about.md, content/_index.md pages
- legacy OG-image/llms.txt generation scripts (superseded by the
*.astro-site.mjs versions apps/site's build already uses)
- unrelated stray files (manimations/, build.sh)
Also drops apps/site/src/pages/search.astro, replaced by the search modal,
and swaps in the real favicon.ico.
- Added a Docker entrypoint script to manage content repository cloning and updates.
- Updated server configuration to include public URL and proxy settings.
- Enhanced content file utilities to return file paths for written entries.
- Introduced GitPublisher class for handling Git operations and deployments.
- Added tests for Git publishing functionality.
- Updated Dockerfile and docker-compose for production setup.
- Added new public PGP key and security.txt for contact information.
- Created new About and Archive pages in the site.
- Updated site configuration to include new navigation links.
Writings detail pages now show the table of contents as a sticky
sidebar once there's room (>=74rem viewport), sharing its markup with
the existing inline TOC via a new TocList.astro so neither copy drifts.
Below that breakpoint it falls back to the original inline list.
Bumped .container--wide 64rem -> 76rem (home, bookshelf, and now
writings detail) so big monitors use more of the screen. The prose
column itself stays capped at 42rem for readability; the extra room is
what makes space for the TOC gutter. Verified at 390/900/1180/1920px.
Shiki pulls in a WASM oniguruma engine and bundled theme/grammar JSON
for two full themes; highlight.js's core build plus only the 11
languages content actually uses is much thinner for the same job here.
Token colors now come straight from the design tokens (--accent,
--text-muted, ...) instead of shiki's dual-theme CSS vars, so they
already switch with the site's theme with no extra [data-theme] rules.
Converts the note/tip/warning/danger `{% <tag> %}...{% </tag> %}` blocks
the posts→writings migration script left untranslated into styled
.callout markup (toml-content-loader.ts's renderCallouts(), styled in
global.css to match the new design system).
Also wires shiki into the same markdown pipeline for fenced code block
highlighting (github-light/github-dark, switched by the same
[data-theme]/prefers-color-scheme pattern tokens.css already uses).
Also records the Three.js centerpiece's perf budget check in TODO.md:
scene is trivially light (well under 10k triangles, 100+fps uncapped);
the ~130KB gzip payload is three.js core itself, not a tree-shaking gap
(verified named imports change nothing - sideEffects:false already lets
Rollup shake fully), and the script is a deferred module that doesn't
block first paint. No code changes needed there.
Replaces the legacy Zola script, which was hard-coded to the retired
"CASE FILE" branding, with scripts/generate-og-images.astro-site.mjs
built on the new design system's dark palette + Fraunces/JetBrains Mono.
Base.astro now renders og:image/twitter:image from a per-page ogImage
prop, wired into the writings and bookshelf detail pages.
Uses static-weight Fraunces/Newsreader font packages rather than the
variable fonts the site ships elsewhere, since satori's opentype.js
parser throws on their fvar table.
The enrichment guard was `if (entry.cover_image) return entry;` —
meaning once *any* cover_image was set, including a raw external URL
you pasted into Strapi by hand, it was treated as "already done" and
never downloaded. The site's coverExists() check only looks for local
/covers/... files, so a remote URL silently never rendered.
- content-sync.ts: enrichBookshelfEntry now branches on whether
cover_image is an http(s) URL (cache it via the new
cacheRemoteImage) vs. unset (existing ISBN/DOI lookup) vs. already
a local path (left alone).
- bookshelf-covers.ts: cacheRemoteImage() downloads and caches any
image URL. Also fixes a real bug caught while testing this against
the actual O'Reilly cover URL from the reported entry: their CDN
labels WebP responses as Content-Type: image/jpeg, so trusting the
header would've cached it with the wrong extension. Now sniffs the
real file signature (RIFF/WEBP, PNG, JPEG, GIF magic bytes) instead
of trusting either the header or the URL.
Verified the download+sniff logic directly against the real cover URL
from the reported entry (Designing Data-Intensive Applications) —
correctly detects and saves as .webp. Didn't touch the running dev
Strapi/DB while testing.
toml-content-loader.ts only read content/ once in load(), so a new
entry created through Strapi (or any hand-edit) sat on disk correctly
but never appeared on the site until astro dev was restarted. Astro's
content layer only auto-refreshes for loaders that wire up the
watcher it hands them.
Refactored the read into a loadAll() function called both on initial
load and on every add/change/unlink event from Astro's dev-mode
watcher, scoped to the content directory. Verified live: created a
file mid-session, it appeared within ~2s with no restart; deleting it
disappeared just as fast.
Production builds were never affected (astro build only calls load()
once anyway, and always sees the current state of content/).
pnpm dev was failing with "App keys are required" for anyone whose
apps/cms/.env didn't already exist (it's gitignored, so this hits
every fresh clone, not just a one-off). predev/predevelop now copy
.env.example to .env automatically when it's absent, so `pnpm dev`
and `pnpm --filter cms develop` both just work without a manual setup
step.
Interaction/layout pattern is my own implementation, inspired by
observing (not copying source from) adammaj.com/reading: a horizontal
scrollable shelf of book "spines" above a list, click-through to a
per-book detail page where the shelf re-renders with that book's
spine expanded into a cover.
- src/lib/spine-color.ts: deterministic per-title color + width hash,
so every book gets a distinct-looking spine without needing a
manually-set color field.
- src/lib/cover-exists.ts: checks the referenced cover_image file
actually exists under public/ before rendering an <img> — the ISBN/
DOI cover lookup only runs on live Strapi create/update, so
hand-seeded content (like our two placeholder books) has a
cover_image path with no cached file yet. Falls back to the
colored spine block instead of a broken image.
- src/components/BookSpines.astro: the shelf itself, reused on both
the index and detail pages; a scroll button, hover-lift, and the
active book's spine widens into its cover/fallback.
- Bookshelf index now renders full reviews inline (was previously
just a bare metadata list) with cover thumbnails.
- New src/pages/bookshelf/[...slug].astro: first individual page
route for bookshelf entries (portfolio still only has a list page).
Verified in-browser: shelf renders, hover/click navigation works,
active-book expansion on the detail page, and the cover-exists
fallback correctly avoids broken <img> tags for our two seed books.
Data model: nodes are real content entries (writings, portfolio,
bookshelf), edges are shared-tag connections — the same relationship
"related posts" already uses, drawn instead of listed. No decorative
or fake data.
- src/lib/constellation-data.ts: builds the node/edge graph from the
actual collections at build time.
- src/lib/constellation-scene.ts: vanilla Three.js scene (no
framework) — fibonacci-sphere layout, auto-rotation, pointer
raycasting with a title tooltip, click-through to the entry's page.
Honors prefers-reduced-motion (skips rotation and the spring-eased
entrance, which reuses src/lib/spring.ts) and checks WebGL support,
falling back to a plain count for browsers/settings that lack it.
- src/components/Constellation.astro: wires it up, serializing the
graph as inline JSON for the client script to consume.
- Homepage rebuilt around it: hero constellation above a 3-column
dashboard (latest writings/portfolio/bookshelf), using a new `wide`
layout variant on Base.astro (dashboard needs more than the 42rem
article width).
Also: removes "life and beliefs" from all site copy (site.config.ts,
the llms.txt generator + its output) per request — description is
now "Computer science and mathematics."
Verified in-browser: real WebGL scene renders with correctly
positioned/colored nodes and edges, hover shows the right title via
raycasting, layout holds at the new wide container width.
Root "dev" script uses concurrently to run both apps with labeled,
color-coded output ([site]/[cms]) instead of needing two terminals.
The per-app dev:site/dev:cms scripts stay for when you only want one.
References: pixperk.tech (dark, warm off-white text, serif-italic +
mono mixed typography, personal dashboard modules) and mcyoung.xyz
(meta line with reading time, subtle accent underline on titles).
- src/styles/tokens.css: dark-first color palette with a warm-paper
light mode (data-theme override + prefers-color-scheme, toggle wins
either direction), fluid clamp() type scale, spacing/radius scale.
- Fonts: Fraunces (display/headings, italic), Newsreader (body,
long-form readability), JetBrains Mono (nav/meta/code) — all
self-hosted via @fontsource, continuing the mono choice already
used in the legacy OG-image pipeline.
- Base.astro rewritten: real header/nav with active-link state, a
theme toggle (persisted to localStorage, no-flash inline script),
footer with social links (ported from zola.toml), replacing the
scaffold placeholder.
- Reading time: toml-content-loader.ts computes wordCount/
readingMinutes from the raw body at load time, surfaced in the
writings list and detail meta line.
- Bug fix: the marked heading renderer was using raw token.text for
both the visible heading and the TOC, so a heading like
"**Registers**" rendered literal asterisks instead of bold — now
renders inline tokens properly and strips markdown for the
plain-text TOC label/slug.
Verified in-browser (light + dark) across home, a migrated writing
with TOC/headings, bookshelf, and 404.
"subresource integrity", "task scheduler", and "conventional commits"
had spaces, producing broken-looking /tags/<tag>/ URLs. Also fixes a
silent bug: site.config.ts's tagDescriptions already keyed
"subresource-integrity" with a hyphen, so the per-tag description
never actually matched the un-normalized tag.
Added normalizeTag() to migrate-posts-to-writings.mjs so re-running
the migration script doesn't reintroduce the spaces from the
untouched content/posts/ originals.
scripts/generate-llms.astro-site.mjs covers writings, portfolio,
bookshelf, and blogs (unblocked now that site.config.ts exists from
the feeds/meta work), wired into apps/site's build script.
Also fixes .gitignore: the bare `public` pattern (meant to ignore the
Zola build's root-level output directory) was matching at any depth,
so apps/site/public/ and apps/cms/public/ were being silently
excluded from every commit despite `git add` reporting them as
staged for directory adds (the ignore-file warning only surfaces for
an explicitly named path, not a recursive directory add — easy to
miss). Scoped to `/public` so only the root output dir is ignored.
Picks up robots.txt, the Astro scaffold's favicon, llms.txt, and
Strapi's own public/robots.txt, none of which were actually tracked
until now.
404: "Page Fault" — a SIGSEGV/memory-fault framing distinct from the
retired terminal easter egg, still fitting the CS-flavored identity.
Plain/unstyled for now like the rest of the placeholder layout;
restyle once the design system lands.
src/lib/spring.ts: a small CSS+Web Animations API spring utility
(damped harmonic oscillator -> keyframe progress values), per the
locked "no animation library" decision. Not wired into any component
yet — this is the foundational primitive the design system's motion
work will build on, kept free of any visual/component opinions.
scripts/migrate-posts-to-writings.mjs converts all 20 posts under
content/posts/ into the new writings schema — normalizes dates to
bare TOML local-dates, converts the one unambiguous Zola shortcode in
use (youtube embeds) to a plain <iframe>, and strips the now-meaningless
{% raw %}/{% endraw %} escape tags. content/posts/ itself is untouched;
this only adds content/writings/*.
Also generates 301 redirects from the old /posts/<slug>/ URLs to the
new /writings/<slug>/ ones into sws.toml, inside marker comments so
re-running the script regenerates that block idempotently instead of
duplicating it.
Two posts (from-c-to-machine-code, self-hosting-gitea-and-mirroring-github)
use note/tip/warning/danger callout shortcodes that have no Astro
equivalent yet — flagged by the script rather than guessed at, since
that needs a real component once the design system exists.
Verified: astro check clean, full site builds (80 pages, all real
migrated posts render), redirect generation confirmed idempotent
across repeated runs.
- src/site.config.ts: minimal site metadata (title, description,
base URL, nav, tag descriptions) ported from the legacy zola.toml
as a placeholder pending real design/copy.
- RSS (@astrojs/rss) and JSON Feed endpoints, sitemap
(@astrojs/sitemap), robots.txt.
- Base.astro: meta description (site-wide default or per-page
override via llms_description/description), RSS/JSON feed
<link rel=alternate>, and a webmention endpoint link (plumbing
only — needs the domain registered on webmention.io to do
anything).
- toml-content-loader.ts: marked renderer now assigns heading ids
and collects them into rendered.metadata.headings, so
render(entry) exposes headings the same way a built-in Markdown
loader would.
- Writing detail page: table of contents, prev/next navigation,
series-nav (uses the existing extra.series/series_index fields),
and tag-overlap related posts.
- Tags index + per-tag pages, tag links wired in from writing cards.
- Pagefind: indexes the build output as part of `pnpm build`
(astro build && pagefind --site dist), plus a /search/ page using
Pagefind's default UI.
Verified: astro check clean, full build succeeds (feeds/sitemap/
pagefind all generate correctly), and manually exercised /search/
(real query, highlighted results) and /tags/ in a browser against
the built site.
apps/cms/src/utils/bookshelf-covers.ts fetches book covers from Open
Library by ISBN (real image, cached into apps/site/public/covers/)
and backfills missing title/authors for papers from Semantic Scholar
by DOI/arXiv id. Wired into the sync middleware in content-sync.ts:
runs once per entry (cover_image already set means "done"), and only
on live create/update through Strapi, not during the boot-time
import (so a restart doesn't hammer external APIs).
Also renames the bookshelf `status` field to `read_status`
everywhere (schema, content/README.md, seed content, Astro zod
schema, bookshelf page, sync mapping). Strapi's content-manager API
treats a top-level `status` key as its own reserved draft/publish
parameter even with draftAndPublish disabled, so an attribute
literally named `status` silently rejected every write — caught this
while testing the enrichment hook.
Verified end-to-end: created a book by ISBN with no cover_image,
confirmed a real cover image was downloaded and cached, cover_image
was set on the entry and written to the file, and the cover/file were
both removed on delete.
Adds slug (uid) fields to all four content types so Strapi documents
can be matched to files deterministically, plus:
- apps/cms/src/utils/content-file.ts: read/write/delete the +++ TOML
frontmatter files, using smol-toml's TomlDate so dates round-trip as
bare local dates (matching the legacy Zola format), not quoted
datetime strings.
- apps/cms/src/utils/content-sync.ts: per-type frontmatter <-> Strapi
field mappings, a boot-time importer that upserts every content/
file into Strapi by slug, and a Document Service middleware that
writes any create/update/delete made through Strapi straight back
to the same files.
Strapi's SQLite DB is now genuinely a disposable cache: content/
stays buildable and readable with Strapi entirely absent, and
restarting Strapi rebuilds its DB from content/ with no duplicates
(matched by slug).
Verified end-to-end: fresh boot imports all seed files once; a second
boot re-imports idempotently (0 created, all matched by slug); create/
update/delete through the content-manager API all correctly write to
and remove the corresponding file on disk.
apps/cms/Dockerfile.dev + root docker-compose.yml give a one-command
way to run the CMS in a container for testing (docker compose up
cms), with the shared content/ directory mounted so it matches the
host dev setup. apps/cms/Dockerfile is a production multi-stage build
for later Dokploy deployment. Uses node:24-bookworm-slim to match the
local Node version and get glibc prebuilt binaries for better-sqlite3
without needing a native build toolchain in the final image.
Verified: both images build, the dev container boots Strapi
successfully, admin panel and API routes are reachable, and the
mounted content/ volume resolves at the same relative path the future
sync provider will expect.
Adds writing, portfolio-entry, bookshelf-entry, and curated-blog
collection types with attributes mirroring the TOML frontmatter
fields in content/README.md exactly, so the future sync provider has
a direct field mapping. draftAndPublish is disabled on all four since
our own `draft` boolean (synced to the file) is the source of publish
state, not Strapi's built-in workflow. Verified Strapi boots and
registers all four REST routes (api/writings, api/portfolio-entries,
api/bookshelf-entries, api/curated-blogs).
Adds a custom Astro loader that reads the Zola-style TOML frontmatter
(+++ ... +++) directly, so content/ stays the single source of truth
with no YAML conversion step. Defines writings/portfolio/bookshelf/
blogs collections and basic list/detail pages for each, rendering the
seed entries end-to-end (verified in-browser via `pnpm --filter site
dev`). This is the first runnable MVP: home, writings list + post
detail, portfolio, bookshelf (books and papers), and curated blogs
all render from real content/ files.
andwatiandGitHub
andwati.com CMS