Content files
Every page is a folder. Its settings and short fields are in page.json, each rich text field is an HTML file beside it, and its images live in the same folder.
The folder’s path is the page’s address: content/page.json is the home page, and content/docs/reference/cli/page.json is /docs/reference/cli/. Folders starting with a dot are ignored. You can make every file here by hand, and the editor will pick it up.
page.json
{
"template": "doc",
"title": "Commands — Verso docs",
"description": "Every Verso command and flag.",
"date": "2026-11-16",
"order": 1,
"tags": ["Reference", "Command line"],
"fields": {
"heading": "Commands",
"cover": { "file": "terminal.jpg", "alt": "A terminal window" },
"accent": { "color": "proof" }
},
"blocks": {
"sections": [
{ "id": "b-3f9a1c", "block": "feature", "fields": { "title": "Fast" } }
]
}
}
| Key | What it holds |
|---|---|
template | Required. The name of a file in templates/, without .html |
title | The search title, for <title>. Shown as {{ page.title }} |
description | The search description, for <meta name="description"> |
date | A date written YYYY-MM-DD. Used by the newest and oldest sorts |
draft | true keeps the page out of the built site |
order | A number for the order sort. Lower comes first |
tags | A list of tag names, like ["Design", "Process"]. Spellings that make the same address count once. See Tags and tag pages |
tags-of | A folder in content/, like "journal". Makes this page the list of that folder's tags, with a page for each tag beneath it |
fields | Text, image and colour fields, by name |
blocks | The blocks in each block area, and the items of each repeater, by name |
Field values
- text is a string.
- image is
{ "file": "photo.jpg", "alt": "…" }. The file must be in the page’s folder. - color is
{ "color": "proof" }, naming one of the site’s colour tokens. - rich fields are never in
page.json. They are files (below).
Verso writes page.json with its keys always in this order, two-space indents and a newline at the end, so changes show up as small, readable diffs.
Blocks
Each block area holds a list of block instances. An instance has an id that never changes, the name of a file in blocks/, its own fields, and, if the block has block areas or repeaters of its own, its own blocks. A component instance has a component name instead of a block.
{ "id": "b-91c2e0", "block": "grid", "fields": {}, "blocks": {
"items": [ { "id": "b-77ad01", "block": "card", "fields": { "title": "One" } } ]
} }
A repeater's items are kept the same way, under the repeater's name. Each item's block names the file and the list, joined by two dashes: "about--team" for {{ list:team }} in templates/about.html, or "team--people" for {{ list:people }} in blocks/team.html.
site.json
Shared fields and shared block areas, the ones written {{ site.footer:text }} or {{ site.header:blocks }}, are the same on every page, so they live in content/site.json rather than in a page. Text fields go under "fields", rich text fields under "rich" as HTML, and shared block areas under "blocks", as lists of block instances like a page's:
{
"fields": { "footer": "Made in Savannah" },
"rich": { "notice": "<p>Closed for the holidays.</p>" },
"blocks": {
"header": [
{ "id": "b-9187e8", "block": "site-nav", "fields": { "name": "Northlight" } }
]
}
}
An image in a shared block area is kept in content/ itself, and its file name starts with a slash, like { "file": "/logo.png", "alt": "…" }. The editor writes the file when something shared is edited. A site with nothing shared doesn't need it.
Rich text files
Each rich text field is its own file beside page.json, named after the field: body is body.html. It holds clean HTML with no classes or styles, and only the elements the field allows.
<p>Verso has three commands.</p>
<h2>verso build</h2>
<pre><code data-lang="bash">npm run build</code></pre>
<aside><p><strong>Tip:</strong> Set the output folder to dist.</p></aside>
Paragraphs, bold, italic and line breaks are always allowed. Each tool on the field adds more:
| Tool | Elements |
|---|---|
headings | h2, h3, h4 |
lists | ul, ol, li |
links | a with href (http, https, mailto, tel or a path) |
images | figure, img with src and alt, figcaption |
tables | table, thead, tbody, tr, th, td |
quotes | blockquote |
callouts | aside |
embeds | iframe from YouTube or Vimeo, in a figure |
code | pre, and code with an optional data-lang |
Anything else is removed when the editor saves. When you write these files by hand, escape <, > and & inside code blocks. Whitespace inside pre is kept exactly.
Images
A page’s images live in its own folder, so they move with it. File names must start with a letter or number and end in .jpg, .jpeg, .png, .gif, .webp or .avif. In rich text, refer to them by file name alone: <img src="chart.png" alt="…">.
Starting layouts
A page type's starting layout is templates/<type>.layout.json, beside the template. It has a page's "blocks" and "fields", usually without words. Every new page of that type starts with a copy, with fresh block ids. Images stay behind unless their file name starts with a slash.
{
"fields": {},
"blocks": {
"content": [
{ "id": "b-start1", "block": "hero", "fields": {} },
{ "id": "b-start2", "block": "text", "fields": {} }
]
}
}
Component files
A component is an arrangement of blocks used on many pages, saved as components/<name>.json. Pages hold instances of it with their own content. Change the file and every page follows.
{
"name": "pricing",
"label": "Pricing",
"tree": [
{ "block": "grid", "key": "k1", "blocks": { "items": [ { "block": "card", "key": "k2" } ] } }
],
"shared": { "k2.title": "Starter" },
"defaults": { "k1.heading": "Plans" }
}
shared holds locked fields, the same on every page. defaults holds what a new instance starts with. Names use lowercase letters, numbers and dashes.