Design

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…"
  }
]
KeyWhat it holds
urlThe page’s address
titleIts search title, or its label if it has none
labelWhat people call it: its title without a “ — Site name” tail, or its folder’s name
description, date, tagsFrom its page settings
headingsThe text of every h2, h3 and h4 in its rich text
textIts 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.