feat: list the latest blog posts on /blog/

[magnus-madsen]

/blog/ was a stub that linked to blog.flix.dev and nothing else. It now lists the five newest posts — title, date, and summary, each deep-linking to the post — with the link to the full blog kept above and below the list.

Where the data comes from

blog.flix.dev now publishes atom.xml and rss.xml. This uses Atom: the RSS feed inlines every post in full (137 KB against 6.8 KB for the same eight titles) and dates entries in RFC-822, which Date.parse is not obliged to accept.

build-scripts/fetchBlogPosts.mjs downloads the feed into src/data/ before Astro runs, exactly as fetchGrammar.mjs downloads the TextMate grammar into src/grammars/. Both now share fetchOnce.mjs, so they behave identically:

• the download is skipped whenever the file is already present, so each is fetched once and then kept;
• a failure stops the build with a non-zero exit rather than quietly publishing a page that is missing content.

Because the feed is on disk before the build starts, the page reads it synchronously and the render never touches the network.

Two traps worth knowing about

blog.flix.dev answers paths it does not have with its index page and status 200, not a 404. The status therefore cannot distinguish a feed from a web page, so the fetch validates the body and fails loudly if it is not an Atom feed. Without this, a feed that moved or was turned off would parse as HTML and silently yield no posts.

Bumping COMMIT in fetchGrammar.mjs has never been enough on its own — the skip-if-exists check runs before anything looks at the SHA, so a working tree that has already built keeps the old grammar until the file is deleted. Pre-existing behaviour; the comment that claimed otherwise is corrected here and the rule is documented.

Verified

Scenario	Result
Cold build (neither file present)	both written, 10 pages, 5 posts
Warm build	both already exists, skipping fetch
Offline with files cached	succeeds, exit 0
Offline with feed missing	Failed to fetch …: fetch failed, exit 1
Server returns 200 + HTML	… but it is not an Atom feed, exit 1
Feed shape changes (parses to zero entries)	Parsed zero entries out of …, exit 1

npm run check is clean (0 errors, 0 warnings, 0 hints), and every command in the new docs was run verbatim.

Also in here

• npm run fetch runs both fetches, so dev/build/check name one prelude step instead of a growing chain.
• build-scripts/README.md (new) and an External Resources section in README.md document what is downloaded, that it is kept forever, and how to refresh it.
• /blog/ stays noindex and out of the sitemap, since the posts themselves live on blog.flix.dev; the comment in astro.config.mjs justifying that is updated, as it described the page as a stub.

Note for whoever deploys

The feed is fetched once and never refreshed. That is fine for a fresh clone or a CI run, which is how this is expected to build, but if production deploys from a long-lived working directory the post list would freeze at whatever the first build fetched. That case needs rm src/data/blog-atom.xml in the deploy step.

🤖 Generated with Claude Code