static export path normalization

situation

export generated canonical directory pages like /guide/
/guide (no slash) hit an asset layer that did not normalize the path before lookup → rendered framework 404
initial smoke check recorded only HTTP success on nearby routes — status proves transport, not that title and content rendered

why

every static deployment joins two owners: the url a reader types and the asset path the export produces
transport-only verification passes while the spellings disagree
assert document identity — title and heading — not status
proving both spellings turns a reader-facing 404 into a repeatable post-deploy check

root cause

url owner and asset owner disagreed about trailing slashes
export owned directory-shaped pages; asset lookup treated the no-slash spelling as a different resource
outer router did not redirect or normalize before static lookup
not an MDX parsing problem, not a missing document: the canonical page existed and rendered; only the alternate spelling missed its asset boundary

evidence that found it

check	weak result	decisive result
transport probe	`200` from a nearby route	response title and primary heading match the requested document.
canonical route	`/guide/` renders	confirms the export contains the page.
non-canonical route	`/guide` returns a framework 404	isolates path normalization before asset lookup.
generated output	directory exists for `guide/`	confirms the export's required path shape.

compound guardrail

choose one canonical route form; configure the export around it
redirect or normalize the alternate form before the asset layer resolves a document
verify both forms after every routing or hosting change
assert document identity, not only status: title, primary heading, one known section present
keep the corpus loader independent of hosting glue — a hosting change cannot alter which MDX pages are discovered

good and bad

bad

probe: GET /guide
assertion: status is 200

accepts an error document, redirect shell, or cached fallback instead of the guide. the miss ships to readers as a framework 404 while the check stays green; first evidence is a lost visitor.

good

probe: GET /guide and GET /guide/
assertion: both responses contain title "guide" and heading "guide"

tests the actual reader outcome, protects both url forms. a spelling disagreement fails the check right after the routing or hosting change that introduced it, not as a silent 404 found later.