Routing
Every .html in routes/ is a route. The router swaps only the page, prefetches links and keeps the layout alive.
Files are routes
The path of a file under routes/ is its URL. index.html maps to the folder, [name] in a file or folder name is a param, and a static segment beats a param: demo/new.html wins over demo/[slug].html for /demo/new. A page is a fragment with optional top-level <title>, <meta> and <link> tags; it has no <html>, <head> or <body>.
| File | URL |
|---|---|
| routes/index.html | / |
| routes/about.html | /about |
| routes/blog/index.html | /blog |
| routes/blog/[slug].html | /blog/:slug |
| routes/blog/[slug]/edit.html | /blog/:slug/edit |
| routes/[lang]/index.html | /:lang |
Names starting with _ are private; only _layout.html and _404.html are special, any other _x.html is an error. x.html next to x/index.html, or two params in the same folder, is app/route-conflict. There is no [...rest], no optional param and no nested layout.
routes/examples/routing/demo/index.html
<title>Posts · routing demo</title><meta name="robots" content="noindex"><script> import { posts as allPosts } from './_posts.js' const posts = allPosts</script><c-demo-page> <p-demo-nav></p-demo-nav> <h1 class="text-2xl font-medium tracking-tight">Posts</h1> <ul class="grid gap-2"> <for post in $posts key=post.slug> <li><a class="text-ink underline" href="/examples/routing/demo/{post.slug}">{post.title}</a></li> </for> </ul> <ul class="grid gap-2 text-sm text-muted"> <li><a class="underline" href="/examples/routing/demo/new">/demo/new</a> is new.html, not [slug]</li> <li><a class="underline" href="/examples/routing/demo/missing-post">/demo/missing-post</a> matches [slug], no post</li> <li><a class="underline" href="/examples/routing/demo/a/b">/demo/a/b</a> matches nothing: 404</li> <li><a class="underline" href="/examples/routing/demo" data-reload>Reload this page</a> with data-reload</li> </ul></c-demo-page>
routes/examples/routing/demo/new.html
<title>New post · routing demo</title><meta name="robots" content="noindex"><c-demo-page> <p-demo-nav></p-demo-nav> <h1 class="text-2xl font-medium tracking-tight">New post</h1> <p class="text-muted">This is <code class="text-ink">demo/new.html</code>. A static segment beats a param, so <code class="text-ink">[slug].html</code> never sees the slug "new".</p></c-demo-page>
routes/examples/routing/demo/_posts.js
export const posts = [ { slug: 'hello-pragma', title: 'Hello, pragma', author: 'Ana', date: '2026-11-02', summary: 'The first post: why the HTML ships prebuilt.' }, { slug: 'closed-syntax', title: 'A closed syntax', author: 'Rui', date: '2026-11-09', summary: 'Four sigils, five block tags and nothing else.' }, { slug: 'new', title: 'A post called "new"', author: 'Ana', date: '2026-11-12', summary: 'Never rendered: /demo/new is new.html, because a static segment beats [slug].' },]
Live result
Dynamic routes with [slug]
The param is params.slug everywhere: in HTML, in the page's <script> after import { params } from 'pragma', and in a load. It is always a URL-decoded string. Reading a param the route does not have is a check error that lists the valid ones. Here a derived function in the page's script finds the post in a local module; with a .server.js the same lookup would run in load (see Data and SSR).
A missing post is data, not an error: the branch renders "not found" and the status stays 200, a soft 404. On static hosting something has to map /demo/abc to [slug].html; pragma serve, the Node adapter and the Workers adapter do it from the manifest.
routes/examples/routing/demo/[slug].html
<title>Post · routing demo</title><meta name="robots" content="noindex"><script> import { params } from 'pragma' import { posts } from './_posts.js' const post = () => posts.find(entry => entry.slug === params.slug) ?? null</script><c-demo-page> <p-demo-nav></p-demo-nav> <if $post> <article class="grid gap-3"> <h1 class="text-2xl font-medium tracking-tight">{$post.title}</h1> <p-post-meta :post="$post"></p-post-meta> <p class="text-muted">{$post.summary}</p> </article> </if> <else> <article class="grid gap-3"> <h1 class="text-2xl font-medium tracking-tight">Post not found</h1> <p class="text-muted">No post has this slug. Not found is just data here, so the response is still 200.</p> </article> </else> <p class="text-sm text-faint">params.slug = <span class="font-mono text-ink">{params.slug}</span></p></c-demo-page>
routes/examples/routing/demo/_posts.js
export const posts = [ { slug: 'hello-pragma', title: 'Hello, pragma', author: 'Ana', date: '2026-11-02', summary: 'The first post: why the HTML ships prebuilt.' }, { slug: 'closed-syntax', title: 'A closed syntax', author: 'Rui', date: '2026-11-09', summary: 'Four sigils, five block tags and nothing else.' }, { slug: 'new', title: 'A post called "new"', author: 'Ana', date: '2026-11-12', summary: 'Never rendered: /demo/new is new.html, because a static segment beats [slug].' },]
Live result
Route-local components
A component in _components/ next to a route is used as <p-name> by every page in that folder and below: the lookup walks up from the page to routes/. p-post-meta has no <script>, so :post="$post" aliases the page's path at build time and {$post.author} reads through it. Promoting it means moving the folder to lib/components/ and renaming it c-post-meta.
routes/examples/routing/demo/_components/post-meta/post-meta.html
<p class="text-sm text-faint"> <span>{$post.author}</span> <span aria-hidden="true">/</span> <time :datetime="$post.date">{$post.date}</time></p>
routes/examples/routing/demo/_components/demo-nav/demo-nav.html
<nav aria-label="Routing demo"> <a href="/examples/routing/demo" class="nav-link">Posts</a> <a href="/examples/routing/demo/tabs" class="nav-link">Tabs</a> <a href="/examples/routing/demo/go" class="nav-link">Go to</a> <a href="/examples/routing/demo/new" class="nav-link">New</a></nav><style> [data-c="demo-nav"] { display: flex; flex-wrap: wrap; gap: 0.5rem 1.25rem; padding-bottom: 0.875rem; border-bottom: 1px solid var(--color-line); font-family: var(--font-mono); font-size: 0.75rem; }</style>
Live result
One layout and automatic active links
routes/_layout.html wraps every page. Its optional <head> comes first, is static (a binding there fails check with html/head) and is copied into every page; exactly one <main data-page> holds a lone <slot>. The layout has no <script> and reads only shared, params and query; behavior goes in a component. A <title> in the layout <head> is the fallback for pages without one, and pragma.json's name is the last resort. A page can also write <meta> and <link> at its top level: the build moves them into <head>, replacing the layout's tag with the same name (see SEO and head).
Any routed <a href> without query or hash that points to the current page gets aria-current="page", in the prebuilt HTML and after every navigation. This site styles .nav-link[aria-current="page"] in green: look at the header above, or at the demo nav in any frame on this page.
routes/_layout.html
<head> <meta name="description" content="pragma is a web framework built for coding agents: native HTML, CSS and JavaScript, prebuilt pages, WebMCP tools and a Rust CLI that checks everything an agent writes."> <meta name="theme-color" content="#0e1014"> <meta name="color-scheme" content="dark"> <link rel="icon" href="/favicon.svg" type="image/svg+xml"> <meta property="og:type" content="website"> <meta property="og:site_name" content="pragma"> <meta property="og:locale" content="en_US"> <meta property="og:title" content="pragma: the web framework for agents"> <meta property="og:description" content="Native HTML, CSS and JS, closed syntax, WebMCP by default and a Rust CLI built for coding agents."> <meta property="og:image" content="https://pragma.leonavas.com/og.png"> <meta property="og:image:width" content="1200"> <meta property="og:image:height" content="630"> <meta property="og:image:alt" content="pragma: native HTML, CSS and JS with a Rust CLI"> <meta name="twitter:card" content="summary_large_image"></head><a href="#main" class="skip-link bg-accent px-3 py-2 font-mono text-xs text-accent-ink no-underline">Skip to content</a><header class="sticky top-0 z-40 border-b border-line bg-ground"> <nav class="wrap flex h-14 items-center justify-between gap-3 font-mono text-xs" aria-label="Main"> <a href="/" class="flex shrink-0 items-center gap-2.5 text-ink no-underline" aria-label="pragma home"> <svg class="size-5 text-accent" viewBox="0 0 32 32" aria-hidden="true"><path d="M8 11l5 5-5 5" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="square"></path><rect x="16" y="19" width="8" height="2.6" fill="currentColor"></rect></svg> <span class="text-sm font-semibold tracking-tight">pragma</span> <span class="hidden border border-line px-1.5 py-0.5 text-faint sm:inline">v0</span> </a> <ul class="flex items-center gap-3 sm:gap-6"> <li><a href="/guide" class="site-link">Guide</a></li> <li><a href="/examples" class="site-link">Examples</a></li> <li><a href="/agents" class="site-link">Agents</a></li> <li class="hidden sm:block"> <a href="https://github.com/leonavas/pragma" class="site-link"> <svg class="size-4" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg> <span class="sr-only md:not-sr-only">GitHub</span> </a> </li> </ul> </nav></header><main data-page id="main" tabindex="-1" class="flex-1 outline-none"><slot></slot></main><footer class="mt-24 border-t border-line"> <div class="wrap flex flex-col gap-4 py-8 font-mono text-xs text-faint md:flex-row md:items-center md:justify-between"> <p class="max-w-md">Built with pragma: prebuilt HTML, no client framework, zero warnings from <span class="whitespace-nowrap text-muted">pragma check --strict</span>.</p> <ul class="flex flex-wrap gap-x-5 md:shrink-0"> <li><a href="/guide" class="nav-link inline-flex min-h-11 items-center">Guide</a></li> <li><a href="/examples" class="nav-link inline-flex min-h-11 items-center">Examples</a></li> <li><a href="/agents" class="nav-link inline-flex min-h-11 items-center">For agents</a></li> <li><a href="/llms.txt" class="nav-link inline-flex min-h-11 items-center">llms.txt</a></li> <li><a href="/examples/seo" class="nav-link inline-flex min-h-11 items-center">How this head is built</a></li> <li><a href="https://github.com/leonavas/pragma" class="nav-link inline-flex min-h-11 items-center">GitHub</a></li> </ul> </div></footer>
Live result
Tabs and filters live in the query
query.tab holds the query as a string, in HTML and in scripts (import { query } from 'pragma'); a repeated key keeps the last value, and a missing query.x never throws. Links build their URL with href="?tab={tab.id}". Since automatic aria-current ignores links with a query, bind :aria-current to a derived value that is 'true' or false.
Every navigation, including a query-only one, recreates the page state: click the counter, then switch tabs, and it starts again at zero.
routes/examples/routing/demo/tabs.html
<title>Tabs · routing demo</title><meta name="robots" content="noindex"><c-demo-page> <p-demo-nav></p-demo-nav> <p-query-tabs></p-query-tabs></c-demo-page>
routes/examples/routing/demo/_components/query-tabs/query-tabs.html
<script> import { query } from 'pragma' const sections = [ { id: 'overview', label: 'Overview', body: 'A ten-key keyboard with hot-swap switches.' }, { id: 'specs', label: 'Specs', body: '87 keys, USB-C, 1.2 kg, aluminium case.' }, { id: 'reviews', label: 'Reviews', body: '4.8 out of 5 from 312 reviews.' }, ] let clicks = 0 const active = () => sections.find(section => section.id === query.tab) ?? sections[0] const tabs = () => sections.map(section => ({ ...section, current: section === active() && 'true' })) const queryTab = () => query.tab ?? 'undefined' function bump() { clicks += 1 }</script><div> <nav class="query-tabs-list" aria-label="Product sections"> <for tab in $tabs key=tab.id> <a class="query-tabs-link" href="?tab={tab.id}" :aria-current="tab.current">{tab.label}</a> </for> </nav> <p class="query-tabs-panel">{$active.body}</p> <p class="text-sm text-faint">query.tab = <span class="font-mono text-ink">{$queryTab}</span></p> <button type="button" class="btn btn-small" @click="bump">Clicked {$clicks} times</button></div><style> [data-c="query-tabs"] { display: grid; justify-items: start; gap: 1rem; } .query-tabs-list { display: flex; flex-wrap: wrap; width: 100%; border-bottom: 1px solid var(--color-line); } .query-tabs-link { margin-bottom: -1px; padding: 0.5rem 0.875rem; border-bottom: 1px solid transparent; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; text-decoration: none; } .query-tabs-link:hover { color: var(--color-ink); } .query-tabs-link[aria-current="true"] { border-bottom-color: var(--color-accent); color: var(--color-ink); } .query-tabs-panel { min-height: 3rem; }</style>
Live result
Navigating from an action, and full reloads
After an action, navigate(url) from 'pragma' goes through the router like a link click. Use it only when there is no link to click: never a <button> that navigates, location.href or history.pushState. A link with data-reload, target or download, or a click with a modifier key, skips the router and loads the page in full.
routes/examples/routing/demo/go.html
<title>Go to · routing demo</title><meta name="robots" content="noindex"><script> import { navigate } from 'pragma' let slug = 'closed-syntax' function openPost() { navigate('/examples/routing/demo/' + encodeURIComponent(slug.trim())) }</script><c-demo-page> <p-demo-nav></p-demo-nav> <form class="flex max-w-sm flex-col items-start gap-3" notool @submit="openPost"> <label class="grid w-full gap-2 text-sm"> <span class="text-muted">Post slug</span> <input class="border border-line-strong bg-sunken px-3 py-2 text-ink" :model="$slug" required> </label> <button class="btn btn-primary">Open post</button> </form></c-demo-page>
Live result
The 404 page
A URL that matches no route renders routes/_404.html, served with status 404 by pragma serve and the Node adapter. It is a normal fragment with a <title>; it may have a <script> for state and actions, but never a .server.js. The Workers adapter resolves param routes and answers unknown URLs with this page and a real 404 too.
routes/_404.html
<title>Page not found · pragma</title><meta name="robots" content="noindex"><script> const requestedPath = () => decodeURI(location.pathname)</script><div class="wrap grid gap-10 pt-16 lg:grid-cols-2 lg:items-center lg:gap-16 lg:pt-28"> <div> <h1 class="text-4xl font-medium tracking-tighter sm:text-5xl">Page not found</h1> <p class="mt-6 max-w-md text-lg leading-relaxed text-muted">Every page of this site is a file in routes/. No file matches this address, so the server answered with routes/_404.html and status 404.</p> <div class="mt-8 grid gap-3 sm:flex sm:flex-wrap"> <a href="/" class="btn btn-primary">Back to home</a> <a href="/examples" class="btn">Browse the examples</a> </div> </div> <c-terminal title="pragma serve"> <pre tabindex="0" aria-label="The request and the 404 answer"><code><span class="term-cmd">GET {$requestedPath}</span><span class="term-err">404</span> no route matches <span class="term-ink">{$requestedPath}</span><span class="term-dim">served routes/_404.html</span></code></pre> </c-terminal></div>
Live result
What the router does for free
- Intercepts same-origin
<a href>clicks and swaps only<main data-page>plus the page's<title>,<meta>and<link>tags, so description, canonical and Open Graph follow the page (SEO and head). The layout stays mounted and its directives are reapplied. - Prefetches on hover, on focus and when a link scrolls into view (at idle): the prebuilt HTML plus a
modulepreloadof the route's modules, which downloads and compiles them without running them until you navigate. - Wraps the swap in
document.startViewTransitionwhere the browser has it. - Scrolls to the top on a new page, restores the position on back and forward, scrolls to
#hashtargets and moves focus to<main>.
None of it needs code: there is no router to configure, and the pages on this site use nothing else.