ApiaryActiveLive
Try: pause · settings · learn · wipe
← Community / Reading Room
WA
craft · 25 min read

Write a Route Contract Before You Move an Article Archive to Static HTML

A small workshop library wants to move its how-to articles from a dynamic renderer to static HTML. The team builds the pages, uploads a preview, and opens a…

AI disclosure: Drafted with AI assistance for Apiary. The archive, page names, and rollout in this guide are fictional. Verify platform and framework behavior in your target environment before using it as a release gate.

A small workshop library wants to move its how-to articles from a dynamic renderer to static HTML. The team builds the pages, uploads a preview, and opens a handful of links. Everything looks faster. A week later a member uses an old bookmark and gets a second copy of an article instead of a redirect. A guide the editors removed months ago is back online. The search page still exists, but tapping its results sometimes produces a white screen because the app asked for a framework-specific navigation payload and got a document instead.

The migration passed a demonstration and failed a contract. Those are different jobs. A demo shows a happy path; a route contract describes what the site promises about every class of request. It includes negative cases and does not confuse an HTTP success with proof that the desired handler produced it. This guide gives you a way to make that contract small enough to run in every release and broad enough to catch the failures that screenshots cannot.

Four route classes, one explicit decision per URL

Assume the fictional Lantern Workshop Library has a reading archive plus a live seat reservation service. Its article URLs look like /read/bench-dog-spacing. Readers share links on a community forum. Old editorial aliases point at newer article names. Some guides were retired because their instructions were misleading; editors do not want copies resurfacing under a different slash style. Seat availability, search, and account state need separate handling.

Write down the answer you want before you decide where a file should live.

Request pathClassExpected response
/read/bench-dog-spacingCanonical article200 HTML, article identity marker and matching canonical link
/read/clamp-hole-spacingEditorial alias301 to /read/bench-dog-spacing, no second article copy
/read/old-tool-listRetired404 in this site's policy, with Cache-Control: no-store
/api/seatsDynamic service200 JSON containing the expected response shape
/read/not-a-real-titleUnknown404; not the homepage masquerading as a success

These statuses are not universal prescriptions. An editor can choose 410 for a deliberate permanent removal, or choose a different cache policy after considering its deployment. The point is to declare an expectation and measure it. RFC 9110 defines the HTTP status semantics; Google's redirect documentation describes permanent redirects as a canonicalization signal. Neither tells you whether your own preview is currently obeying the rule.

Keep an owner and a reason with exceptions. If a former URL is reserved as an alias, a later author should not be able to create a page at the same name through the ordinary article workflow. A retired title should require a conscious editorial state change rather than falling back into a manifest because a Markdown file was restored from an old branch.

A static file can outrank the handler you thought was in charge

Static asset hosting and a dynamic handler can serve the same host. Their order matters. On one platform, existing files can bypass the Worker by default; on another, the framework router may intercept the request first. An innocent-looking read/old-tool-list/index.html could shadow the dynamic retirement check. A redirect handler that still passes its unit tests cannot help if the host never calls it.

Cloudflare's static asset routing documentation describes how an assets binding and Worker-first routing interact. Review the actual host configuration and the generated asset directory together. Copying rules from another hosting product or another project is not a substitute for that inspection. If routing precedence changes depending on additional headers or settings, include those modes in the preview cases rather than extrapolating from a single browser refresh.

The simplest policy is usually to keep every noncanonical article path out of the HTML export unless the platform manifest is deliberately using it for a redirect implementation. Then separately verify the actual deployment behavior. A crude collision guard for the library's deliberately restricted lowercase-ASCII flat slugs might look like this:

from pathlib import Path
import re
from collections import defaultdict

SLUG = r"[a-z0-9]+(?:-[a-z0-9]+)*"

def html_article_candidates(root: Path, files):
    out = defaultdict(list)
    for filename in files:
        parts = Path(filename).relative_to(root).parts
        slug = None
        if len(parts) == 2 and parts[0] == "read":
            if parts[1].endswith(".html"):
                slug = parts[1][:-5]
        elif len(parts) == 3 and parts[0] == "read":
            if parts[2] == "index.html":
                slug = parts[1]
        if slug is not None:
            if not re.fullmatch(SLUG, slug):
                raise ValueError(f"unexpected exported slug: {slug!r}")
            out[slug].append(str(filename))
    return out

root = Path("stage")
files = [root / "read/bench-dog-spacing/index.html",
         root / "read/bench-dog-spacing.html",
         root / "read/old-tool-list/index.html"]
candidates = html_article_candidates(root, files)
reserved = {"old-tool-list", "clamp-hole-spacing"}

assert sorted(reserved & candidates.keys()) == ["old-tool-list"]
assert sorted(k for k, paths in candidates.items() if len(paths) > 1) == [
    "bench-dog-spacing"
]

The test intentionally finds two problems in a synthetic upload. A release would fail on either one. Do not copy the simplistic filename mapping into a host that has different rewrites or permits Unicode slug forms. Paths have subtleties around case sensitivity, escaping, slash handling, query strings, and host redirects. Draw your real mapping from the platform's documented rules, tighten any house restrictions in the build, and confirm variations with HTTP tests. Keep query behavior explicit: some links should retain harmless attribution parameters, while an application route may require particular parameters to stay intact.

Prove the preview has the right behavior

Start with a machine-readable fixture. The exact format matters less than making expected outcomes reviewable in Git. A page with a 301 rule and one with a 404 rule should not both show up in a “migrated article count.” A representative fixture can be written without any production names:

[
  {
    "request": "/read/bench-dog-spacing",
    "status": 200,
    "type": "text/html",
    "canonicalPath": "/read/bench-dog-spacing",
    "marker": "lantern-article:bench-dog-spacing"
  },
  {
    "request": "/read/clamp-hole-spacing",
    "status": 301,
    "locationPath": "/read/bench-dog-spacing"
  },
  {
    "request": "/read/old-tool-list",
    "status": 404,
    "cacheControlHas": "no-store",
    "mustNotContain": "lantern-article:old-tool-list"
  }
]

The first request tests more than status. A generic homepage can return 200. A branded error page can accidentally return 200. A page whose article vanished under a loading skeleton can return 200. Assert a reliable article identity marker and a canonical designation that represents the chosen policy. For example, a private preview might deliberately emit the public canonical domain. In that case check for the public hostname and expected path, not the preview hostname guessed from the request. At the same time, prevent crawl exposure according to your organization's staging setup. A canonical link alone is not an access control.

For redirects, disable automatic redirect following on the first request. Verify the exact status and destination. Then follow it deliberately and verify the final article, including the canonical. Tests that follow every redirect by default can mark a permanent redirect as good even if it points to a generic search page. They can also count a six-hop chain as a success while an old bookmark becomes perceptibly slow.

For retirement cases, assert the expected status, confirm the article marker is absent, and test both warm and cold reads when practical. A cached old 200 can defeat a correct new retirement handler. Depending on your hosting policy, deal with stale objects explicitly rather than assuming a new upload removes every old response from edge caches. RFC 9111 is the primary source for HTTP caching directives. A no-store response is distinct from a command to erase any copies a third party saved previously.

For the dynamic API, verify more than “it returned JSON.” A 200 with fixture-shaped but stale static JSON can still be wrong. Define a safe input pair that should yield different values or establish a trace showing the intended environment handled the request. Do not modify a live reservation just to make a health check pass. An isolated preview with synthetic state makes it possible to test the difference without affecting users.

The brownout case: direct link works, click fails

If the site uses a framework with client-side navigation, test two separate entrances. First, open the article directly in a fresh browser. Second, begin on the archive and tap the real card. Repeat with and without prefetch when your framework supports it. A static document is an understandable response to a full browser navigation. It may be unsuitable for a client router expecting a framework-specific payload.

Next.js documentation on linking and navigating explains why prefetch and client transitions are not interchangeable with a document reload. In one straightforward migration design, rendering a normal anchor for document-only article routes is easier to reason about than persuading the app router to hydrate a page it doesn't own. That is an option, not a requirement: if you export both document and the payload the framework expects, test both.

A browser run should cover the most common path in both directions. Archive to article, browser back, category link to next story, and a deep link on an ordinary phone viewport all exercise different parts of the stack. Expect the article body to remain visible with scripting disabled if that is one of the goals. If the generation pipeline deploys images and CSS with separate cache identities, check those on the same preview instead of declaring victory after seeing the right headline.

Do not equate static rendering with no server invocation. A dynamic handler can render HTML without sending much script to the browser. To establish that article requests bypass a Worker, use environment-appropriate invocation evidence, a trusted diagnostic header emitted only by the expected layer, or an isolated route test where the handler is deliberately instrumented. Record the proof separately from latency. A fast request does not tell you which code handled it.

Size the complete upload, not the source tree

Static generation changes the arithmetic. A source bundle could carry a few large shards with many article bodies. A one-file-per-article export turns each body into another upload entry. Asset counting rules can apply after filtering, and a large single image or shard can be a separate bottleneck even when the total count is within allowance. Cloudflare's Workers limits documents both file-count and individual-file constraints; verify the plan and toolchain applicable to the actual deployment before acting on a generic tier number.

Measure the staged upload with the same ignore rules and target root as production. Count HTML documents, script chunks, images, and other eligible assets. Report the largest eligible file and the number of known reserved URL collisions. A count from the Git repository cannot answer what a generated build will send. An ignore file that removes source Markdown does not automatically remove HTML generated from that Markdown.

Avoid “solve the limit” changes that silently alter URL ownership. Routing part of the archive through a second host could affect canonicals, cookies, performance, and operations. Splitting storage behind the same public routes is a design decision, not an excuse to break bookmarks. If you keep dynamic fallback for unconverted articles, declare that mixed mode and test both categories.

Keep an exception ledger that can survive a staff change

An old route is easy to recognize while the editor who made the change is still around. A year later, all anyone sees is a removed file and an unfamiliar alias. Record a short reason code, the decision date, the approver or owning team, and the intended treatment of the path. Do not put sensitive details about why a page was withdrawn into a public response. The ledger can hold a private reference while exposing only a plain error to readers.

Make its precedence explicit. If the same slug appears in the approved page list and in the retirement list, fail the build and show both references. Do not let the order of two array spreads decide which is right. Similarly, check for redirect cycles, missing targets, and single-hop violations unless an approved exception explains them. This validation operates on the proposed release manifest before a deployment needs to exist.

Here's an example release failure: the guide clamp-hole-spacing is on the alias ledger, but an imported folder contains a page under the same string. An editor compares the two titles and recognizes the duplicate as the same guide under its old name. The new build discards the duplicate page and retains the redirect. If the titles had covered genuinely different material, the new article would need another slug or an explicit editorial replacement decision. In neither case should the developer quietly drop the existing alias to make an automated check green.

When possible, count each route class independently. An export that moves from 2 to 200 canonical articles can still retain 35 aliases, 12 retired jobs, and 6 dynamic exceptions. Those counts answer different questions. Retain one or two invariant negative checks as sentinels in the release pipeline even if the preview already tested the full exception manifest. That gives operators a fast signal if a later hosting upgrade changes precedence after an otherwise routine deploy.

Set up a miniature archive with a release story

Consider the fictional Lantern Archive, a site with hundreds of teaching pages and a tiny live reading-list service. It recently consolidated a collection of lamp restoration exhibits into one canonical guide. A second page was removed after its rights changed, and the old public path purposely shows no article. A hand-maintained live list changes independently of the guides. Until now an application server has interpreted each route. The proposed release gives two articles static documents, but leaves the list and everything else on their existing path. The test suite should communicate that story directly instead of presenting a pile of URLs whose statuses must be rediscovered each week.

Choose one document with simple content and another with a characteristic that might expose render divergence. In the invented archive, the simple document has an exhibit headline and date. The second has a table with two columns, a mail-free downloadable fixture, and citations. Authenticity can be verified through visible facts and a version note, not a complete byte match between framework shells. The release may intentionally change the document structure when moving to HTML. In that case the route contract checks the preserved bits of meaning: identity, link ownership, document type, intended canonical, and critical content. A separate visual review can decide whether the layout remains familiar.

Give the exhibits plausible neighbors. The old guide path redirects once to the consolidation target. The one withdrawn exhibit returns a deliberately chosen missing status and does not render a stale title. The live list returns data from the current fixture revision. An unrelated unknown slug gets the documented generic missing behavior. None of those neighboring routes has to share one cache policy or body format. Their juxtaposition is deliberate. A broad wildcard route that sends every unknown address to the homepage can make a smoke run report success while breaking every distinction the editor made.

In practice the contract can be built as a small fixture array with an address, route class, required status, expected destination if any, required body markers, prohibited markers, content type if relevant, and the intended policy for a few headers. Add an optional case selector for background prefetch or ordinary document navigation if the app treats those separately. Keep request method in the case key if a path services more than one supported method. Never include write methods to production merely to exercise a migration. The evidence here is about known reader-facing behavior. Use read-only calls and reserve adverse simulations for a controlled preview.

A useful run names what environment it sees. For the public baseline, record HTTP observations made while signed out where practical. For preview, record build identity and mark where expected hostnames legitimately differ. Don't silently strip every origin from results to get a match. It may be appropriate for preview's Location header to point at the preview host, and likewise appropriate for a page canonical to name the planned public host. Write that distinction in the fixture. A preview linking to a private or stale build is an easy thing to miss if normalization erases every hostname before comparing.

Test the parts of a redirect that people actually notice

A common test follows redirects immediately and checks the final page. That is useful but incomplete. The old route might still exist as a successful duplicate page, have a redirect chain, or pass through a different host before returning to the expected article. Record its first response without following, and record the resolved destination as a separate observation. A meaningful result can report that the old path returned the expected permanent status, direct Location destination, and no unintended intermediate hop. If a policy intentionally has multiple hops, say why and set a clear ceiling. Do not infer the initial status from the final status.

In the synthetic Lantern Archive, an old card is linked with a query used to show citation formatting. Should that recognized query survive consolidation? A developer might expect to preserve all queries, while an editor decides that only the recognized citation flag retains meaning and older view settings are retired. The test should explicitly encode which local examples are meaningful, and whether the destination preserves, translates, or drops them. Never use actual customer referral values or private email addresses as fixture parameters. A deliberately invented parameter exercises routing without making a trace a source of personal information.

Anchors need a separate check. A link ending with a fragment names an in-document target, but it isn't simply another path passed through the server. The HTTP trace can verify the redirect and its Location; a browser can show whether the final content contains and scrolls to the intended section. In the miniature archive, give the old guide an anchor named materials and the target a corresponding heading ID. If the new export changes the section identifier, decide whether to preserve an alias anchor or intentionally update referring links. A query assertion is not evidence for in-document navigation, and a screenshot taken after scrolling manually is not evidence that the original link lands in the right place.

Test relative and absolute Location forms according to the host application's contract, not aesthetic preference. Parse the final navigation result in the correct base environment. A comparison that uses simple string concatenation may consider two equivalent destinations different or hide an erroneous path. Distinguish canonical host redirects intentionally configured for all routes from the redirect for one document. An HTTP-to-HTTPS hop or a recognized alternate host policy might be normal before the article redirect; if included, scope the measurements so a new accidental chain doesn't get normalized away along with intended infrastructure behavior.

It is reasonable to keep some path variations out of the actual live test set if they aren't supported and would add unnecessary requests. But when two link forms appear in known public history, put them in the ledger. Real candidates include a trailing slash used in older templates or an explicitly recorded alternative encoding used by known links. Reject the tempting solution of lowercasing every path or collapsing every escape in your own comparator. That could make two distinct routes look identical exactly when you need to see a difference. Always use synthetic controlled data for tests that probe how an exporter interprets unusual local filenames, rather than guessing unsupported routes on someone else's server.

Measure retirement without preparing a substitute article

Withdrawing an exhibit is not the same as temporarily removing it from the reading list. A deliberate retirement can have its own status and cache contract, but a person following an old link shouldn't find a new static document carrying the removed title. For a controlled rehearsal, add a fixture body that contains a unique fake title and two distinctive phrases. Verify that none appears in the retired path response or unintended forward destination. The test does not need to reproduce removed copyrighted or personal material. Synthetic markers test whether prohibited content is still being served without circulating it again.

Check that multiple changes didn't accidentally create a loophole. The old application might set a no-store policy for the deliberately retired document page, while JSON backing data was migrated separately. If the public interface has a documented companion read-only API, add its narrow expected case. Also test the present-day search listing and the sitemap, where an old title might be discoverable even though a direct request now fails. Each check measures something different. An absent sitemap row doesn't establish that the page no longer serves; a missing page doesn't prove the title is absent from the index. Make the handoff state which surfaces were examined rather than signing off on a vague global deletion.

A useful retirement drill takes place only in preview. Seed a test response for the fake document, warm it, then stage the release that marks it retired. Observe the ordinary expected request and a clean-context request. Do not send bypass headers to production just because a read doesn't match. If the platform offers authorized preview tracing, it can establish whether the test encountered a static object, a cache, or the worker. If it doesn't, say which attribution remains uncertain. Comparing cold and warm observations is enough to notice some problems without claiming it proves that every edge everywhere now agrees.

A published retirement policy can include a humane explanation or links to genuinely related material. It shouldn't pretend that a replacement page is the withdrawn article just to preserve a traffic figure. For the miniature archive the withdrawn exhibit becomes a plain unavailable document, while an independently consolidated guide still has a permanent redirect. Treat those as two editorial statuses with separate reasons. If the two cases repeatedly come out the same in status, target, and copy, examine whether a framework fallback or asset upload default is flattening them. A sensible test fixture protects that editorial distinction even if both routes were previously managed by a single function.

Check ownership of the dynamic exceptions with two observations

A migration can technically leave the live service on a handler while a new static object masks what a visitor sees. Do not rely on a source rule that names the handler alone. In the fictional preview, seed a first in-memory revision of the live list, request the documented public read surface, then change only the preview's fixture revision through its test setup and read again. Do this within a controlled test system rather than manipulating anyone's production data. The static articles should still show the same approved source identity. The dynamic response should reflect its update according to the existing documented freshness policy.

Freshness is contextual. If the intended service admits a small time-to-live, immediate replay returning the prior value may be expected. Record both expected policy and observed time. If the existing app reads its data only on refresh instead of updating a visible document, test that interface rather than inventing a push requirement. The fixture is about preserving the existing behavior during a narrow release, not redesigning all asynchronous flows. The branch that hosts article assets should not silently change how long the live interface remains stale or how it handles an upstream failure.

Now perform the same two-observation check for one stable article, replacing only the dynamic fixture input. A good rehearsal shows that the same article revision remains stable and that the dynamic fixture has changed appropriately. This cross-check catches a setup where the whole app was pinned to an old build, and another where the broad test configuration inadvertently switches new content for every route. A signed-in state that reveals additional information is outside a signed-out rehearsal unless separately authorized and intentionally covered. Don't claim a public test verified user-level restrictions. Keep the results scoped to the behavior you actually observed.

Consider supporting static images and documents too. Existing primary routes may refer to a figure or downloadable asset whose path inherits separate cache and MIME behavior. A tiny secondary fixture can verify the intended reference exists, the type is appropriate, and the asset still matches its intended identifier. Choose a public synthetic asset or an approved public baseline. This is not a need to mirror every file in the archive or collect all user traffic. It simply makes the article's content contract less superficial than a headline and status alone. A related download that now returns HTML with a 200 status is a practical regression even when the article headline remains unchanged.

Make an inventory discrepancy actionable before upload

When the exporter creates a directory of ready files, compare it to the contract using both additions and exclusions. A ledger of intended documents gives a reviewer something to diff. In the miniature archive, the first release intends exactly two new public article objects. There must be no newly emitted document corresponding to the consolidated alias or the withdrawn exhibit. Supporting assets, framework-generated chunks, and dynamic endpoint routing can be accounted for separately. A high count with no inventory teaches little: it may combine approved output with a thousand unnecessary source copies.

Report quantities at useful boundaries. The source list contains the intended semantic articles. The exporter emits file paths. The upload process can ignore paths, add framework outputs, or transform asset routing. The deployed service exposes actual request paths. A format like shard bundles makes these counts naturally unequal. Don't turn a system that uses grouping into a suspect result because there aren't two upload objects per two articles. Conversely if the plan is to export one document for each target route, rows that never produce a reachable file need investigation before release. Compare sets and route identities, not only totals.

Diagnose a synthetic inventory failure. An archived staging folder carries an old HTML copy at a filename that serves the retired exhibit, and the export adds its own replacement guide. Because the existing file has a neighboring timestamp, a simple newest-file review misses it. The rejected release report should name the actual planned upload object, the public route it would own according to the test configuration, and the ledger item it violates. Resolve whether it was stale output, an explicit migration conflict, or a supported alternate name. Don't silently drop every file with a similar stem; related content may live under an independent route that is still intended to publish.

Compare permitted limit figures only after building the final candidate in a comparable environment. Check the documented maximum upload size for one object and the overall object allowance for the known target. Limits can differ by plan, tool version, and product; a handbook for another deployment isn't proof of the current allowance. If plan is unverified, preserve that as a release gate rather than guessing the larger limit or attempting an upgrade. The article migration can proceed in a smaller isolated rehearsal while the actual larger decision remains open. That is better than redesigning the archive because someone compared apples and subdirectories.

Write a decision record that can be replayed

An imagined release receipt starts with the exact preview identifier and planned boundary. Two article routes are candidates. The alias returned one approved permanent redirect. The retired response matched the status and no-content markers. The live list changed with the test revision and didn't get a static fallback. Then add the exceptions: a narrow keyboard navigation run worked for the first route, but in-document anchor verification for the consolidated guide still needs a first-party link example. That last fact is not erased by all the green rows. Whether it blocks release depends on how important those existing links are and the predeclared acceptance criteria.

When a discrepancy appears, name the next decisive test. If the direct document loads but the reading-list link fails, collect the browser navigation mode and returned content type before changing a route. If the previously retired title reappears only in a warmed context, compare a controlled preview trace against the release's documented cache behavior before deleting files. If the target expected HTML but returns a different type only on an old host alias, separate host routing from the document's own path. A narrow hypothesis preserves the original release purpose and gives the next person a chance to reproduce the problem.

Also save the rollback evidence. An earlier version ID and its intended asset manifest can make an authorized operator faster, but a plan is not itself an executed rollback. A rehearsal against preview can verify that the previous policy still routes correctly and that no stateful data depends on promotion. Record how to decide whether to roll back when only one route class regresses. For example, a broken retired route with a sensitive-content marker may warrant a stop under the declared policy even while the new articles look beautiful. A minor approved visual difference might not. This distinction belongs in the acceptance conversation, not in an automatic rule inferred from arbitrary screenshot differences.

Finally, make the receipt easy to run again without personal session details. Keep the fixture sites synthetic where possible and store the expected canonical host for real authorized checks as a clear environment parameter. Use visible facts or hashes instead of retaining private response bodies in reports. Include earlier decision references and reasons for preserving the exception. The next release can rerun critical baseline requests even if the developer who first assembled the migration is gone. That is the practical purpose of a contract: it lets an archive change implementation while preserving knowable promises to people who saved, linked, and rely on its addresses.

Sample the reader journey from the published entry point

A manual preview session should start where readers actually start. Open a signed-out index page, tab or tap to an approved fixture article, check its heading, and use the ordinary browser Back control. Then use the public article address in a clean tab as a second path. The observations answer different questions: the index path exercises the link and app handoff, and the clean tab exercises the document from its address. Include a refresh after successful navigation. If that now shows a not-found screen, the original transition may have displayed a client-side result which the server cannot serve by itself.

Set the expected viewport and input method before calling the review complete. An article that loads correctly on a desktop pointer but hides its citation or download on a narrow screen has a different kind of defect from a bad HTTP code. Test a small sampling at the preview stage rather than asking a status probe to certify accessibility. In the made-up archive, the table headings and link labels are useful mobile markers because they retain the context of the content. Preserve closure evidence as two separate rows: observed rendering and route contract. That keeps a successful HTTP rehearsal valuable even when a real presentation issue still needs fixing.

Release in a shape you can reverse

Build an isolated two-article canary: an ordinary canonical article and one with a redirect or cache edge case. Keep the rest of the archive as it was, including search, live data, and published counters. Run the fixture against the existing public baseline where that is safe, then the isolated preview. Save the result with a commit identifier, target, test date, a count of routes, and whether signed-out or signed-in conditions were used. Attach evidence for critical discrepancies rather than flattening everything into a green checkbox.

Check the sitemap separately. It should list the canonical URLs you actually intend people and crawlers to find. Do not imply an editorial update just because the static exporter ran. Google's sitemap guidance describes using a verifiable significant update for lastmod. Preserve intentional historical dates when the content and its meaningful signals have not changed.

Decide what rollback actually restores before you release. Pointing at the old commit might restore code but leave edge redirects, static assets, or cached responses from the newer configuration. A rollback note should say which manifest, deployment version, and routing configuration to restore together, and which negative checks to repeat afterward. You do not need to perform a production rollback just to write the plan; you can rehearse the equivalent transition in a preview environment.

The high-value question after a migration is not “did the homepage load?” It is “did each URL retain its role?” An archived article gives the right content. An alias leads to that article. A retired page stays retired. A live service still reflects live state. If each of those facts has an explicit fixture and a recorded preview result, expanding from two pages to two thousand becomes a reviewable release decision instead of a leap of faith.

Frequently asked
What is Write a Route Contract Before You Move an Article Archive to Static HTML about?
A small workshop library wants to move its how-to articles from a dynamic renderer to static HTML. The team builds the pages, uploads a preview, and opens a…
What should you know about four route classes, one explicit decision per URL?
Assume the fictional Lantern Workshop Library has a reading archive plus a live seat reservation service. Its article URLs look like /read/bench-dog-spacing . Readers share links on a community forum. Old editorial aliases point at newer article names. Some guides were retired because their instructions were…
What should you know about a static file can outrank the handler you thought was in charge?
Static asset hosting and a dynamic handler can serve the same host. Their order matters. On one platform, existing files can bypass the Worker by default; on another, the framework router may intercept the request first. An innocent-looking read/old-tool-list/index.html could shadow the dynamic retirement check. A…
What should you know about prove the preview has the right behavior?
Start with a machine-readable fixture. The exact format matters less than making expected outcomes reviewable in Git. A page with a 301 rule and one with a 404 rule should not both show up in a “migrated article count.” A representative fixture can be written without any production names:
What should you know about the brownout case: direct link works, click fails?
If the site uses a framework with client-side navigation, test two separate entrances. First, open the article directly in a fresh browser. Second, begin on the archive and tap the real card. Repeat with and without prefetch when your framework supports it. A static document is an understandable response to a full…
References & sources
  1. Apiary Reading Room — Open, cited knowledge base — funded to keep bee & practical research free.
From the Apiary Reading Room. Opinion & editorial — not financial advice. We don't overclaim.
More from the Reading Room