Search, sitemaps and 404s
Three small files make a static site feel finished: a page for addresses that don’t exist, a sitemap for search engines, and an index your own search can read.
A 404 page
Make a page at content/404/, with any template, and write what you want visitors to see. A build writes it as /404/index.html like any page, and copies it to /404.html, which is where Cloudflare Pages, Netlify and most static hosts look for a not-found page.
{
"template": "page",
"title": "Page not found",
"description": "",
"fields": {
"heading": "This page isn't here."
}
}
The 404 page is left out of the sitemap and the search index.
A sitemap
Tell Verso where the site lives, and a build writes sitemap.xml with every live page:
{
"name": "Verso",
"url": "https://verso.example"
}
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url><loc>https://verso.example/</loc></url>
<url><loc>https://verso.example/changelog/0-1/</loc><lastmod>2026-11-16</lastmod></url>
</urlset>
A trailing slash on url is dropped. Pages with a date get a lastmod. Drafts are never included.
A search index
Add "index": true to verso.json, and a build writes pages.json: a list of every live page with its words as plain text. Verso doesn’t ship a search box. The index is there for one you write, in a few lines of JavaScript.
[
{
"url": "/docs/design/tokens/",
"title": "Design tokens — Verso docs",
"label": "Tokens",
"description": "Add and change colours, sizes, fonts…",
"date": "",
"tags": [],
"headings": ["Where tokens come from", "The Design panel", "Colour ramps"],
"text": "A token is a named value: a colour called proof…"
}
]
| Key | What it holds |
|---|---|
url | The page’s address |
title | Its search title, or its label if it has none |
label | What people call it: its title without a “ — Site name” tail, or its folder’s name |
description, date, tags | From its page settings |
headings | The text of every h2, h3 and h4 in its rich text |
text | Its text fields and rich text as plain text, up to 20,000 characters. Code blocks are left out |
A simple search scores each page by where the words appear:
const pages = await (await fetch('/pages.json')).json();
function search(query) {
const words = query.toLowerCase().split(/\s+/).filter(Boolean);
return pages
.map((p) => {
const title = p.title.toLowerCase();
const heads = p.headings.join(' ').toLowerCase();
const text = p.text.toLowerCase();
let score = 0;
for (const w of words) {
if (title.includes(w)) score += 10;
if (heads.includes(w)) score += 4;
if (text.includes(w)) score += 1;
}
return { page: p, score };
})
.filter((r) => r.score > 0)
.sort((a, b) => b.score - a.score);
}
Feeds
Each channel in verso.json gets an RSS feed at /<folder>/feed.xml once the site has a "url", and the channel’s pages link to it from their head. See Feeds and sub-folders.
Drafts
A page with "draft": true is left out of everything a build writes: its own page, lists on other pages, the sitemap and the index. It stays visible in the editor, so you can keep working on it.