A build-time validation gate: catching content errors before deploy

Every content catalog accumulates rot, and the insidious thing about it is that none of it announces itself. An image gets renamed in a refactor and ten old posts now point at a path that returns nothing. A route changes and the internal links that used to reach it quietly dead-end. A post ships with an empty description, a malformed date, or a missing field that does not crash the page but does break the share preview or the structured data. None of these errors throws an exception or takes the site down; the pages still load. They simply degrade, silently, and the only reliable discoverer of that degradation is a reader hitting a broken image or a dead link — which is the worst possible person to find it.

The fix is to stop relying on anyone going looking, and instead make the build itself the thing that looks. A build-time validation gate is an automated set of checks that runs over the entire catalog on every change and refuses to let a deploy through if anything is wrong. It converts a whole class of silent, run-time, reader-discovered problems into loud, build-time, author-discovered ones — caught by the person who caused them, at the moment they caused them, before any of it reaches production. This article is about what such a gate checks, why build time is the right time, and how to keep it useful rather than annoying as the catalog grows.

A useful gate does not try to check everything; it checks the specific, recurring, high-cost errors that a content catalog actually produces. Four classes cover most of the value. Missing assets: every image, illustration, or file a post references should actually exist at the path given, because a broken hero image is both ugly and invisible to the author who has it cached. Broken internal links: every link to another page on the site should resolve to a real route, because internal links are the connective tissue of a content site and a dead one wastes the reader and leaks the SEO value the link was meant to pass.

The other two are about correctness of the data rather than its references. Malformed or missing metadata: every post should have the fields it needs — a title, a valid date, a description of sane length, the keywords and the social metadata — because these are exactly the things that are invisible in normal reading and so ship broken most easily. And structured-data gaps: if the site emits JSON-LD for articles and FAQs, the gate can confirm each post has what that schema requires, so the structured data is correct by construction rather than spot-checked by hand. Each of these is a check that is cheap to write once and pays every time it catches something.

You could check these things at run time — verify links as pages render, warn about missing images in the console — but that is fundamentally the wrong moment, because at run time the error has already shipped. The reader is already looking at the broken thing; the best a run-time check can do is notice the failure as it happens to a real person. Build time is before the error reaches anyone. A check that runs as part of producing the deployable site can refuse to produce it, which means a broken link or a missing image is not a degraded live page but a build that did not happen. The error and its discovery move from production to the author’s own machine or the continuous-integration run, which is exactly where you want them.

This is the same logic as a type checker, extended from code to content, and it depends on the content being checkable in the first place — which is why storing posts as typed code, as described in Content as code: running a 250-post blog without a CMS, is what makes a strong gate possible. When the whole catalog is data the build can iterate over, validating all of it on every change is just code, and the gate can be as thorough as you are willing to make it. The deeper point is about timing: the cost of an error scales with how late it is caught, and build time is the earliest practical moment to catch a content error, which makes it the cheapest.

A validation gate is only as good as the failures it produces, and a gate that fails with a vague “validation error” is almost worse than none, because it blocks the deploy without telling anyone how to unblock it, and people quickly come to resent and route around it. The discipline is to make every failure specific: name the post, name the field or the link or the asset, say exactly what is wrong, and ideally say what was expected. “Post ‘code-splitting-a-large-web-app’ references image /blog/missing.svg which does not exist” is a failure someone can fix in thirty seconds. “Validation failed” is a failure someone has to investigate, and an investigation is exactly the friction the gate was supposed to remove.

Speed matters alongside specificity, because a gate that takes several minutes to run will be skipped under deadline pressure, and a skipped gate protects nothing. The checks should be fast enough to run on every change without anyone resenting the wait — and most content checks are inherently cheap, since they are reading data and confirming references rather than doing heavy computation. The combination of fast and specific is what makes a gate something people trust and lean on rather than fight: it tells them precisely what is wrong, immediately, so fixing it is a quick correction rather than a chore. A gate that is pleasant to satisfy gets satisfied; a gate that is painful gets disabled.

A gate needs to run in the right places to actually protect anything, and there are two that matter. The first is locally, as part of the normal build, so an author working on content sees a problem the moment they introduce it rather than later — the tightest possible feedback loop, where the person who broke something is told immediately while the change is still fresh in their mind. The second is in continuous integration, on every proposed change before it can merge, as the backstop: even if someone skips the local check or works in a way that bypasses it, the gate runs in CI and a change that fails cannot reach production. The two together mean a content error has to get past both the author and the automation to ship, which it essentially never does.

This placement is why the gate composes so well with everything else in a content-as-code setup. It runs through the same build that compiles the app, on the same changes reviewed in the same pull requests, with the same all-or-nothing deploy semantics. There is no separate content-validation service to run and keep in sync, because the validation is just part of producing the site. It also automates a meaningful chunk of the launch checks described in A go-live runbook for a serverless browser app — the “every page has metadata, every route is in the sitemap” class of check stops being something a human verifies on launch day and becomes something the gate enforces continuously, which is a far more reliable arrangement than a list worked from memory.

A validation gate is not a thing you build once and forget; it is a thing you grow as you learn what actually breaks. The right way to expand it is reactively and specifically: every time a content error does slip through to production — and some will, especially early — the fix is not only to correct that one error but to add the check that would have caught it, so that class of mistake can never ship again. Over time this ratchets the catalog toward reliability, because each real failure permanently closes the door behind it. The gate becomes a record of every kind of content mistake the team has ever made and resolved never to repeat, which is a genuinely powerful thing to accumulate.

The discipline is to keep the checks aligned with real failures rather than imagined ones, because a gate stuffed with speculative rules that have never caught anything is just friction that slows everyone down and tempts people to bypass it. Every check should earn its place by corresponding to a mistake that actually happens, which keeps the gate lean, fast, and trusted. Done this way, a build-time validation gate is one of the highest-leverage pieces of automation a content site can have: a small, growing set of cheap checks that quietly guarantees the whole catalog stays coherent, so that a few hundred posts — and then a few thousand — never quietly rot, because the build will not let them. The reader only ever sees the posts that passed.

Not every problem a gate can detect deserves to block a deploy, and treating them all as equally fatal is how a gate becomes hated. There is a real difference between breakage and imperfection. A missing image, a broken internal link, a malformed date — these are genuine defects that will degrade a live page, and they should be hard failures that stop the deploy cold. But a description that is a little shorter than ideal, a post missing an optional field, a keyword list that is thin — these are quality signals worth surfacing, not reasons to refuse to ship. Conflating the two means either real breakage slips through because everything is a soft warning, or trivial nitpicks block releases until people start bypassing the gate entirely.

The useful structure is two tiers: a blocking tier for things that are actually broken, and a warning tier for things that are merely suboptimal. The blocking checks are the gate proper — fail them and the deploy does not happen. The warnings are advisory — they print, they nudge, they keep a running sense of catalog health, but they do not hold up a release. This separation keeps the gate both safe and tolerable: it is uncompromising about correctness, where being strict protects readers, and merely informative about quality, where being strict would just be annoying. A gate that distinguishes “this is broken” from “this could be better” earns the trust that a gate which cries wolf on everything quickly loses.

The most valuable checks are often the ones that look across the whole catalog rather than at one post in isolation, because a content catalog is a graph, not a pile, and graphs develop problems no single-post check can see. Two posts accidentally sharing a slug is invisible when you validate each alone and obvious when you check for uniqueness across the set. A post that nothing links to — an orphan with no path in from the rest of the site — is fine in isolation and a quiet SEO and discoverability problem in aggregate. A related-posts link that points at a slug which no longer exists passes a per-field check and fails a cross-catalog one. These relational errors are exactly the kind that accumulate silently as a catalog grows and changes.

A gate that understands the catalog as a connected whole can catch all of these: confirm every slug is unique, every cross-link and related-post reference resolves to a real post, and ideally that the connective tissue is healthy — no orphans, no dangling references, no asymmetries where A links to B in a way that was meant to be reciprocal. This is where content-as-code pays off most, as covered in Content as code: running a 250-post blog without a CMS, because the entire catalog is in memory as typed data at build time, so checking relationships across hundreds of posts is just iterating a structure you already hold. The single-post checks keep each article correct; the relational checks keep the catalog coherent, and it is catalog-level incoherence that does the slow, invisible damage.

A validation gate quietly doubles as documentation of what a valid post actually is, and that is worth using deliberately. When the rules for a correct post live as executable checks, a new author — or a returning one who has forgotten the conventions — does not have to find and read a style document that may be out of date; they write a post, run the build, and the gate tells them precisely what is missing or wrong. The checks are the spec, and unlike a written spec they cannot drift out of sync with reality, because they are the thing that is actually enforced. The fastest way to learn the content contract is to violate it and read the specific, friendly failure that comes back.

This makes the gate a genuine onboarding tool, not just a safety net. Someone contributing their first post is guided to correctness by the same mechanism that protects the catalog, which means the knowledge of “what a good post needs” is encoded in the system rather than trapped in the head of whoever set the conventions. It also means the contract evolves cleanly: when the team decides every post should have some new field or meet some new standard, that decision is expressed as a check, applied uniformly to the whole catalog, and taught automatically to everyone thereafter. The gate stops being merely a wall that rejects bad content and becomes the living, enforced definition of what good content is — which is a far more durable thing than a wiki page nobody reads.

A build-time gate catches the rot you introduce, but a content catalog also rots from the outside in ways no change of yours will trigger. An external link you included in a post can go dead months later because the page on the other end moved or vanished, and nothing in your repository changed to flag it — the build is green, the post is untouched, and the link is quietly broken. Build-time checks only run when something changes, so they will never notice decay that happens entirely on someone else’s server while your content sits still. Relying on the build alone leaves a whole class of slow, external rot completely invisible.

The complement is to run the catalog-wide checks on a schedule as well as on every change — a periodic job that re-validates everything, including the things that depend on the outside world, and reports what has decayed since last time. External links are the obvious target, but the same scheduled pass can re-confirm anything that could drift independently of your commits. The two cadences cover different failure modes: the build gate stops you from shipping new breakage, and the scheduled run surfaces old content quietly breaking on its own. Together they keep a catalog coherent against both the rot you cause and the rot that simply happens to it, which is the only way a few hundred posts stay genuinely healthy over years rather than just at the moment they were last edited.