A static-site QA and build checklist

The two habits first

Individual checks age. Habits compound. The first habit: QA runs inside the build, not after it. One script renders every page, copies the assets, and then turns on its own output. Any error exits non-zero and the upload folder is never produced, so there is no state of the world where a known-bad build exists and a human has to remember not to deploy it. The second: warnings and errors are different species. Errors are for what is never acceptable and they stop the line. Warnings print and ship, because a gate that fails builds over fine things is a gate people learn to override.

Structure and metadata, per page

The boring checks, which is exactly why they are automated: exactly one h1 per page, a title with actual length to it, a meta description of at least real-sentence size, Open Graph tags present, a lang attribute on the document. None of these is hard to get right once. All of them are easy to get wrong on page forty, at midnight, in the page nobody looks at, and the gate does not care which page it is.

Links resolve against the output, not against intentions

Every internal link is checked against the files the build just wrote: a link to a route must find that route's file on disk, or the build fails. The distinction matters. A link checker that crawls the live site tells you about the deploy you already shipped. A link check inside the build refuses to create the broken deploy at all. Asset links get the softer treatment, a warning, because a placeholder image is survivable in a way a dead page is not.

Images carry alt text, mechanically

An image without alt text is a defect, so the build treats it as one: any img tag missing the attribute is an error, not a code-review note. Accessibility rules enforced by review last until the reviewer is busy. Enforced by the pipeline, they last.

The scrub gate, over every file

This site publishes rebuilt versions of confidential systems, so its most important check is a list of terms that must never reach the output, run against every text file, raw, before anything ships. That gate was wrong twice, scanning narrower than the output while reporting clean, and its full failure history is published on the colophon, because the lesson generalizes: whatever your build's most important promise is, the gate that keeps it deserves the widest scope and the most suspicion. Test it by planting a violation and watching the build die.

No unresolved anything survives

Template tokens, mustache braces, a stray undefined or a NaN sitting in the rendered text: all fatal. These are the fingerprints of a render that half-worked, and a half-worked render is precisely the failure a human skims past, because the page mostly looks right. The machine does not skim. One wrinkle worth knowing: the gate hunts for those words flush against markup, the shape a broken interpolation actually produces, so ordinary prose about the failure mode, like this paragraph, does not trip it.

Quoted code is verified, not asserted

This site quotes real source code from real repositories, so a separate script opens each source file and confirms every published line still exists in it, character for character, with every trim declared as a visible gap. A quotation is only worth something if it is exact. That script deliberately does not run inside the build: the source repositories are not always present on the machine building the site, and a build that fails when they are missing would teach me to ignore a failing build, which is the most expensive lesson a pipeline can teach.

Tripwires for the person who forgets

The launch-mode gate refuses to build while a draft testimonial remains, because invented words in a real person's mouth are the one defect here that could hurt somebody else. But that gate only fires if someone remembers to run launch mode, and the documented deploy step is a drag and drop. So the plain build leaves a file named DO-NOT-DEPLOY in the very folder that gets dragged, listing exactly what is still wrong. A control that depends on remembering it is not a control, and the second lane exists for the person who forgot the first one.

The checklist, in one place

Render everything through one shell so the chrome cannot drift. Run QA inside the build and exit non-zero on error. One h1, real title, real description, OG tags, lang attribute. Every internal link resolves against the files just written. Every image has alt text. No template token, undefined, or NaN in the output. A scrub list over every file, raw, negative-tested. Quoted code verified against its source, trims declared. Errors reserved for the never-acceptable, warnings for everything else. And a tripwire in the artifact itself for every gate that depends on a human remembering to run it.

None of this is sophisticated, and that is the argument for it. The same pattern now runs in four independent builds, because it is the fourth build in a row where the house rules ended up as executable gates, and every one of those gates exists because something shipped wrong once and the fix became structure.