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>.

FileURL
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

/examples/routing/demo

A real route under this page. Follow the links: each one is a client-side navigation inside the frame.

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

/examples/routing/demo/hello-pragma

Open /demo/missing-post from the Posts list to see the not-found branch.

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

/examples/routing/demo/closed-syntax

Both components live in demo/_components/ and are invisible to routes outside demo/.

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

/examples/routing/demo/new

This site's own layout. The live frame is the same layout around a demo page.

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

/examples/routing/demo/tabs?tab=specs

The URL is the state: reload or share a tab link and the same tab opens.

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

/examples/routing/demo/go

Submit a slug: the form action calls navigate() and the post opens without a page load.

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

/examples/routing/demo/a/b

The frame requests /examples/routing/demo/a/b, which no file matches.

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 modulepreload of the route's modules, which downloads and compiles them without running them until you navigate.
  • Wraps the swap in document.startViewTransition where the browser has it.
  • Scrolls to the top on a new page, restores the position on back and forward, scrolls to #hash targets 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.