Guide 11
Routing
cngxjs (opens in new tab) Updated Guide 11 of 13
The output is a static SPA. A small hash router handles deep links, scroll restoration, tab activation, and view transitions, without shipping a framework runtime.
Why hash routing
Hash URLs work everywhere: GitHub Pages project sites, S3 prefixes, intranet hosts behind
reverse proxies, even file:// previews. No server-side rewrites needed,
deep links survive moves between hosts, and refreshing on any page just works.
Tab activation by hash
Each entity tab (Info, API, Source, Theming Tokens, Example) has a stable hash id. Sharing a URL
like #api opens the API tab; sharing
#L42 on a Source tab scrolls to that line. Hash-based line anchors take
priority over same-named DOM ids, so #L\d+ always wins.
Scroll restoration
Anchor scrolls account for the sticky NavBar height. Clicking
#api doesn’t hide the heading behind the topbar. Back/forward
navigation restores the prior scroll position. URL updates use
history.replaceState so the browser’s history isn’t polluted
with intermediate hash changes.
No first-paint flash
Hash-targeted content is hidden during initial parse via a
cdx-hash-pending class on
<html>; the router removes it after applying the initial
hash, so deep-linked pages never flash their default state before settling.
Sub-path hosting
Because routing is hash-based, the document root can sit anywhere: a project subdomain, a
sub-folder under a marketing site, a per-version folder under
/documentation/<label>/. The version-switcher uses the
pathname segments (lastIndexOf(currentLabel)) to compute target
URLs, so version hops work even when the docs live deep inside a host.