SEO and head
The layout <head> holds the defaults every page shares. A page writes its own <title>, <meta> and <link> at the top of its file, and the build moves them into <head>. With ssr = true they can come from server data, so crawlers and link-preview bots get the real values in the first response.
Layout defaults, page overrides
A tag at the top level of a page replaces the layout tag with the same name, property, http-equiv or rel + hreflang, in place; a tag the layout lacks, like canonical, is appended. <html lang> comes from lang in pragma.json, and charset and viewport are always emitted.
Keep canonical and og:url out of the layout, or every page claims the same address. X reads og:title, og:description and og:image when the twitter:* versions are missing, so this site's layout sets only twitter:card, and a page overrides og:* once for both. Add a twitter:* tag only when X should show something else, like the shorter title on this demo page.
routes/examples/seo/demo/index.html
<title>Field notes · pragma</title><meta name="description" content="Short notes on how pragma renders pages, written as a demo of static head tags."><link rel="canonical" href="https://pragma.leonavas.com/examples/seo/demo"><meta property="og:url" content="https://pragma.leonavas.com/examples/seo/demo"><meta property="og:title" content="pragma field notes: how a page gets rendered"><meta property="og:description" content="Short notes on how pragma renders pages."><meta name="twitter:title" content="pragma field notes"><div class="wrap py-12 lg:py-16"> <section class="prose"> <h1 class="text-3xl font-medium tracking-tight text-ink">Field notes</h1> <p>A static page: every tag in its head is a literal written at the top of this file.</p> <ul> <li><a href="/examples/seo/demo/prebuilt-html">Why pragma ships prebuilt HTML</a></li> <li><a href="/examples/seo/demo/head-tags-from-data">Head tags rendered from server data</a></li> </ul> </section></div>
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
GET
GET
Tags from server data with ssr = true
Write {data.post.title} inside <title>, and :content, :href or {} in an attribute of <meta> and <link>, reading data, params or query; then add export const ssr = true to the route's .server.js. The server fills them before it sends the page, so a link-preview bot, which never runs JavaScript, sees the article instead of the site defaults.
Build absolute URLs in load from a fixed origin, never from the request's Host header. A missing value keeps the static fallback, such as the <title> text; a <meta> left without content or a <link> without href is dropped. On client navigation the router replaces <title>, <meta> and <link> with the next page's.
routes/examples/seo/demo/[slug].html
<title>{data.head.title}</title><meta name="description" :content="data.head.description"><meta name="robots" :content="data.head.robots"><link rel="canonical" :href="data.head.url"><meta property="og:type" content="article"><meta property="og:url" :content="data.head.url"><meta property="og:title" :content="data.article.title"><meta property="og:description" :content="data.head.description"><meta property="og:image" :content="data.head.image"><meta property="og:image:alt" :content="data.head.imageAlt"><meta property="article:published_time" :content="data.head.published"><script type="application/ld+json">{ "@context": "https://schema.org", "@type": "Article", "headline": "{data.article.title}", "description": "{data.head.description}", "image": "{data.head.image}", "datePublished": "{data.head.published}", "mainEntityOfPage": "{data.head.url}", "publisher": { "@type": "Organization", "name": "pragma" }}</script><div class="wrap py-12 lg:py-16"> <if data.article> <article class="prose"> <h1 class="text-3xl font-medium tracking-tight text-ink">{data.article.title}</h1> <p class="font-mono text-xs text-faint"><time :datetime="data.article.published">{data.article.date}</time></p> <for paragraph in data.article.body key=paragraph.id> <p>{paragraph.text}</p> </for> <p><a href="/examples/seo/demo">All field notes</a></p> </article> </if> <else> <section class="prose"> <h1 class="text-3xl font-medium tracking-tight text-ink">Note not found</h1> <p>No field note has this address. The status is still 200, so this page tells crawlers <code>noindex</code> instead.</p> <p><a href="/examples/seo/demo">All field notes</a></p> </section> </else></div>
routes/examples/seo/demo/[slug].server.js
import articles from './_articles.json' with { type: 'json' }export const ssr = trueconst siteOrigin = 'https://pragma.leonavas.com'function headFor(article) { if (!article) return { title: 'Note not found · pragma field notes', robots: 'noindex' } return { title: article.title + ' · pragma field notes', description: article.summary, url: siteOrigin + '/examples/seo/demo/' + article.slug, image: siteOrigin + article.image, imageAlt: article.imageAlt, published: article.published, }}export async function load({ params }) { const article = articles.find(entry => entry.slug === params.slug) ?? null return { article, head: headFor(article) }}
routes/examples/seo/demo/_articles.json
[ { "slug": "prebuilt-html", "title": "Why pragma ships prebuilt HTML", "summary": "Every route is compiled to a complete HTML file, so the first paint never waits for JavaScript.", "published": "2026-11-02", "date": "2 November 2026", "image": "/og.png", "imageAlt": "pragma: native HTML, CSS and JS with a Rust CLI", "body": [ { "id": "p1", "text": "The build expands every component in place and writes one HTML file per route. A visitor, a crawler and a link-preview bot all get the same complete markup on the first request." }, { "id": "p2", "text": "JavaScript then binds to that markup instead of rebuilding it, so nothing jumps when the modules arrive." } ] }, { "slug": "head-tags-from-data", "title": "Head tags rendered from server data", "summary": "With ssr = true, bound title, meta and link tags are filled on the server, so previews show the real entity.", "published": "2026-11-16", "date": "16 November 2026", "image": "/og.png", "imageAlt": "pragma: native HTML, CSS and JS with a Rust CLI", "body": [ { "id": "p1", "text": "A link-preview bot reads the first HTML response and nothing else. If the title and description come from the database, the server has to write them into head before it sends the page." }, { "id": "p2", "text": "This page is that case: every tag in its head comes from the article you are reading." } ] }]
Live result
GET
GET
Soft 404 and real 404
load returns data, not a status, so a dynamic route whose entity is missing still answers 200: a soft 404, which search engines may index as an empty page. Bind <meta name="robots"> to data.head.robots and return 'noindex' only for the missing entity; in every other case the value is undefined and the tag is dropped.
An address that matches no route gets routes/_404.html with status 404, from pragma serve, the Node adapter and Workers alike.
routes/examples/seo/demo/[slug].server.js
import articles from './_articles.json' with { type: 'json' }export const ssr = trueconst siteOrigin = 'https://pragma.leonavas.com'function headFor(article) { if (!article) return { title: 'Note not found · pragma field notes', robots: 'noindex' } return { title: article.title + ' · pragma field notes', description: article.summary, url: siteOrigin + '/examples/seo/demo/' + article.slug, image: siteOrigin + article.image, imageAlt: article.imageAlt, published: article.published, }}export async function load({ params }) { const article = articles.find(entry => entry.slug === params.slug) ?? null return { article, head: headFor(article) }}
routes/examples/seo/demo/[slug].html
<title>{data.head.title}</title><meta name="description" :content="data.head.description"><meta name="robots" :content="data.head.robots"><link rel="canonical" :href="data.head.url"><meta property="og:type" content="article"><meta property="og:url" :content="data.head.url"><meta property="og:title" :content="data.article.title"><meta property="og:description" :content="data.head.description"><meta property="og:image" :content="data.head.image"><meta property="og:image:alt" :content="data.head.imageAlt"><meta property="article:published_time" :content="data.head.published"><script type="application/ld+json">{ "@context": "https://schema.org", "@type": "Article", "headline": "{data.article.title}", "description": "{data.head.description}", "image": "{data.head.image}", "datePublished": "{data.head.published}", "mainEntityOfPage": "{data.head.url}", "publisher": { "@type": "Organization", "name": "pragma" }}</script><div class="wrap py-12 lg:py-16"> <if data.article> <article class="prose"> <h1 class="text-3xl font-medium tracking-tight text-ink">{data.article.title}</h1> <p class="font-mono text-xs text-faint"><time :datetime="data.article.published">{data.article.date}</time></p> <for paragraph in data.article.body key=paragraph.id> <p>{paragraph.text}</p> </for> <p><a href="/examples/seo/demo">All field notes</a></p> </article> </if> <else> <section class="prose"> <h1 class="text-3xl font-medium tracking-tight text-ink">Note not found</h1> <p>No field note has this address. The status is still 200, so this page tells crawlers <code>noindex</code> instead.</p> <p><a href="/examples/seo/demo">All field notes</a></p> </section> </else></div>
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
GET
GET
robots.txt and a sitemap
Files in public/ are served from the site root as they are, with the right content-type. Routes only produce HTML, so sitemap.xml is a static file too: write it by hand, or generate it from your data with a script before pragma build, and point to it from robots.txt with a Sitemap: line.
public/robots.txt
User-agent: *Allow: /Sitemap: https://pragma.leonavas.com/sitemap.xml
public/sitemap.xml
<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> <url><loc>https://pragma.leonavas.com/</loc></url> <url><loc>https://pragma.leonavas.com/agents</loc></url> <url><loc>https://pragma.leonavas.com/guide</loc></url> <url><loc>https://pragma.leonavas.com/examples</loc></url> <url><loc>https://pragma.leonavas.com/examples/syntax</loc></url> <url><loc>https://pragma.leonavas.com/examples/components</loc></url> <url><loc>https://pragma.leonavas.com/examples/state</loc></url> <url><loc>https://pragma.leonavas.com/examples/stores</loc></url> <url><loc>https://pragma.leonavas.com/examples/routing</loc></url> <url><loc>https://pragma.leonavas.com/examples/data</loc></url> <url><loc>https://pragma.leonavas.com/examples/overlays</loc></url> <url><loc>https://pragma.leonavas.com/examples/styling</loc></url> <url><loc>https://pragma.leonavas.com/examples/packages</loc></url> <url><loc>https://pragma.leonavas.com/examples/logs</loc></url> <url><loc>https://pragma.leonavas.com/examples/seo</loc></url> <url><loc>https://pragma.leonavas.com/examples/seo/demo/prebuilt-html</loc></url> <url><loc>https://pragma.leonavas.com/examples/seo/demo/head-tags-from-data</loc></url></urlset>
Live result
GET
GET
Structured data with JSON-LD
Write one <script type="application/ld+json"> per schema at the top level of the page. The build moves it into <head> and rejects invalid JSON with the line and column. Inside its strings, {data.article.title} works as it does in a <meta>: with ssr = true the server writes each value JSON-escaped, so a quote in a title cannot break the script. JSON-LD without {} is static and needs no ssr.
The field notes article in the showcase above declares an Article from the same data as its title and Open Graph tags. This is what the server sends:
curl -s http://127.0.0.1:5181/examples/seo/demo/head-tags-from-data | grep -A11 ld+json
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Head tags rendered from server data",
"description": "With ssr = true, bound title, meta and link tags are filled on the server, so previews show the real entity.",
"image": "https://pragma.leonavas.com/og.png",
"datePublished": "2026-11-16",
"mainEntityOfPage": "https://pragma.leonavas.com/examples/seo/demo/head-tags-from-data",
"publisher": { "@type": "Organization", "name": "pragma" }
}
</script>
What pragma check rejects
Head tags have one place to go, and the check enforces it with html/head. Each message below is the real output of pragma check --strict for the code next to it.
-
routes/about.html
<section> <meta name="description" content="..."> </section>error [html/head] <meta> belongs in <head>: write it at the top level of the page fragment (or in the layout <head>)
-
lib/components/share/share.html
<div> <meta property="og:title" content="..."> </div>error [html/head] <meta> belongs in <head>: write it at the top level of the page fragment (or in the layout <head>)
-
routes/_layout.html
<head> <meta property="og:url" :content="params.slug"> </head>error [html/head] the layout <head> is static (the same on every page); put bound tags at the top of the page fragment
-
routes/post.html, with no ssr in post.server.js
<title>{data.title}</title>error [html/head] bound head tags are rendered by the server so crawlers see them: add export const ssr = true to routes/post.server.js
-
routes/post.html
<meta name="description" :content="$summary">error [html/head] head tags are rendered by the server and read only data, params or query; "$summary"
-
routes/notes.html
<script type="application/ld+json">{ "@type": "Article", "headline": "Notes", }</script>error [html/json-ld] invalid JSON-LD: trailing comma
-
routes/post.html, with no ssr in post.server.js
<script type="application/ld+json">{ "@type": "Article", "headline": "{data.title}" }</script>error [html/head] JSON-LD with {path} is rendered by the server so crawlers see it: add export const ssr = true to routes/post.server.js
-
lib/components/share/share.html
<div> <script type="application/ld+json">{ "@type": "Organization", "name": "Shop" }</script> </div>error [html/script] JSON-LD <script type="application/ld+json"> goes at the top level of a page