Static site, actually

The definition that matters

At request time, nobody runs your application code to produce the page. A CDN or a dumb file server returns bytes that already exist. Those bytes may have been written by hand, or emitted last Tuesday by Astro, Eleventy, Hugo, or a Makefile. The compiler is not the site. The files are the site.

This site is static. The questionnaire is several HTML files. The result page is one HTML file that contains every recipe; a 40-line script features the match. If that script fails, you still have a catalog. That is the architecture, and it is also the lesson.

Three simplicity scores

These do not move together. Pretending they do is how people get performative.

• Runtime — concepts in the browser, bytes, failure modes. Winner: HTML files + CSS. Multi-page. No hydration.
• Author — shared headers, Markdown, drafts, a nav that does not rot. Winner: a real SSG, once you have more than a handful of pages.
• Agent — will the editor add a page without inventing Vite + React + Tailwind. Winner: Astro, then Eleventy, then you argue with the tool.

“No build step” optimizes the first and taxes the other two the moment you have a shared header, twenty essays, and a tree. A build that emits HTML is still Tier 1. The performative version is pretending includes/ is bourgeois.

Astro is an LLM default that is also actually simple

Astro earned the gravity well. Zero JavaScript unless you opt in, Markdown/MDX, content collections, one island for the one interactive thing. Agents know the file shapes. For a content site it is a legitimate answer, not a fashion — the “simple site” well the way Next.js is the “web app” well, with the difference that Astro’s well matches the problem.

The failure mode is accretion: Astro + React islands + Tailwind + a CMS + a view-layer router until you have rebuilt Next and called it minimal. Delete the island you do not have.

HTMX is the other default, and usually the wrong primitive here

HTMX is the gravity well for “I heard SPAs are immoral.” It is a good tool when a server returns HTML: forms, delete buttons, pagination. For a brochure, a docs site, or this questionnaire, it does almost nothing a link does not do. Fetching static fragments with hx-get is usually worse than another page — especially now that cross-document view transitions are a CSS opt-in:

@view-transition { navigation: auto; }

Astro + HTMX together is a common amateur mashup. They solve different tiers. Astro is a compiler. HTMX is a hypermedia client. Glue them when there is a real process behind the site, not because both showed up in the same genre.

The rest of the low-complexity map

Compilers that emit HTML

• Astro — highest agent fluency. Can accrete into Next-lite.
• Eleventy — folders of Markdown in, HTML out. No UI framework. The compiler disappears.
• Hugo — fastest, one binary, templates are the tax. Great at 10k pages, fussy at 20.
• Zola — Hugo-shaped, Rust, smaller ecosystem. Agents hallucinate Hugo APIs.
• Jekyll — undead GitHub Pages default. Ruby. Immortal.
• Lume / Bridgetown — 11ty-like on Deno; modern Jekyll. Fine if you already live there.
• Starlight, VitePress, mdBook, Quartz — docs-shaped. Use if the site is mostly a textbook.

Hypermedia (Tier 2 — you have a server)

HTMX, Hotwire (Turbo + Stimulus), Unpoly, Datastar, Enhance, Kitten, and the tiny cousins (fixi, htmz). Put these on the “one process, forms, HTML over the wire” card, not on this one.

Sprinkles

Vanilla under ~150 lines. Alpine if you must and already know it. Petite-Vue, Stimulus, WebC. For one flowchart, vanilla wins. This site’s sprinkle is js/ask.js and js/result.js.

CSS that is a framework in the good sense

Pico, Simple.css, Water.css, new.css, mvp.css — they style tags. Open Props for tokens. CUBE CSS and Every Layout for philosophy. Tailwind is the other pole: highest agent fluency, lowest semantic HTML. Fine as an implementation detail. Bad as the thing you teach people to think in.

CSS over JS is real, and newly less theatrical

A lot of “I guess we need a UI library” is now the platform: details, dialog, popover and invokers, :has(), container queries, anchor positioning, scroll-driven animations, view transitions. Branching state (this tree) and sliders are still JS. Shipping Alpine + HTMX + a store for six questions is the performative version of complexity.

A surprising amount of a teaching site can be multi-page HTML. One question per URL. Options are links. The result is /result/?…. That is not aesthetic poverty. That is the flowchart as a site.

The agent-fluency tax

Going against LLM intuition is not a vibe. It is maintenance. Pick Zola or raw HTML or Pico-without-Tailwind and every agent session starts by proposing React. If the audience is amateur vibe coders, say this on the stack page: pick something your agent already knows, or budget time to correct it. That sentence is more useful than bundle size.

The semi-performative path — more CSS, fewer packages, a Makefile — is worth it when the site is the exhibit, or when you personally like HTML and will be the one touching it, or when the interactive surface is small. It is a weak general recommendation to beginners whose editor is the compiler.

What this site chose, and when it should graduate

v0 is hand HTML + one stylesheet + two scripts. Runtime score: high. Author score: fine until the nav duplication hurts. Agent score: medium; they will try to add Vite.

Graduate to Eleventy or Astro when the header is a chore, when we want Markdown as the writing format (we will), or when the questionnaire should be generated from docs/questionnaire.md. Do not graduate to a server, a database, or HTMX until there is a form that needs a process.

The sentence we are willing to be wrong about: Astro is simple because it deletes the client. Handmade HTML is simple because it deletes the toolchain. HTMX is simple because it deletes the JSON API. Using all three at once is how simple sites get a stack.

Still an outline

A later pass should add: a dated cost table for Pages vs a $5 VPS, a worked “same essay in Next vs Astro vs 11ty vs hand HTML” with byte counts, and a short autopsy of an Astro site that accreted React. The definition at the top should not change.

← Where the code runs · This site’s worksheet