site.toml reference

site.toml is the repo-local configuration for a site. It lives at the root of the site's content store, next to the pages. Every field is optional — a site serves without one — and it is read fresh on every request, so a git push applies changes with no restart.

Site creation and vhost mapping are admin-managed through /site (see the configuration reference); this page covers only the repo-local site.toml.

Example

title       = "My Notes"
description = "Personal knowledge base"
base_url    = "https://wiki.example.com"
paginate_by = 10
ignore_dirs = ["out", "vendor"]

[nav]
links = [
  { label = "Home",   url = "/" },
  { label = "Search", url = "/search" },
  { label = "Tags",   url = "/tags/" },
]

[markdown]
unsafe_html         = true
syntax_highlighting = true
highlight_style     = "base16-ocean.dark"

[taxonomies]
category = "categories"
series   = "series"

Top-level fields

Field	Default	Description
title	store name	Site name shown in the navbar and browser <title>
description	—	Meta description; also the RSS <description>
base_url	—	Absolute URL prefix for sitemap <loc> and RSS <link>
paginate_by	0 (off)	Max items per page in list views; 0 disables pagination. A list layout can take over with the paginate() template function
build_future	false	Render pages whose frontmatter date lies in the future; the default holds them back until their date passes
ignore_dirs	[]	Root-relative directories to exclude from the rendered site

[nav]

Navbar links, in order.

Field	Description
links[].label	Link text
links[].url	Link destination

[markdown]

Field	Default	Description
unsafe_html	false	Pass raw HTML in the Markdown through unescaped (wrapper <div>s, <iframe>, …). Enable only for first-party content.
syntax_highlighting	false	Highlight fenced code blocks (via syntect). Requires unsafe_html, since highlighting is emitted as raw HTML.
highlight_style	base16-ocean.dark	syntect theme name
smart_punctuation	false	Convert straight quotes to curly, -- to em-dashes, etc.

Themes include base16-ocean.dark / .light, Solarized (dark) / (light), InspiredGitHub, and Monokai Extended.

By default the renderer strips raw HTML for safety, so features that depend on it (a scoping <div>, embedded <iframe>, and syntax highlighting) are inert until unsafe_html = true. Enable it only when you author all of the site's content.

[taxonomies]

Declare frontmatter fields as navigable taxonomies — the key is the URL segment (singular), the value is the frontmatter field name. See taxonomies.

ignore_dirs

In markdown mode the store is filtered before any path becomes a page, a listing entry, or a static asset:

• Hidden directories are always ignored — any path with a component starting with . (.git/, .venv/, .cache/, …). This is unconditional and needs no configuration.
• ignore_dirs extends the filter to non-hidden directories. Each entry is a root-relative path; the directory and every descendant are excluded. Leading and trailing slashes are tolerated; globs are not — out matches out/ and out/a/b.md, while out* matches nothing.

An ignored file returns 404 and appears in no listing, sitemap, RSS feed, or search result, while staying in the store (still committed, pushed, and pulled). HTML-mode sites serve every file and ignore this setting.

[[redirect]] and [[asset]]

site.toml also serves redirects and file downloads directly:

[[redirect]]
from = "/old-page"
to   = "/new-page"

[[asset]]
url   = "/downloads/tool.bin"
parts = ["files/tool-v1.bin"]

See Downloads & redirects for the full behavior — composed multi-part bodies, custom headers, and HEAD-readable checksums.

Overriding settings for local testing

Every scalar site.toml setting has an EVERLOCK_SITE_* environment variable — the field name uppercased, with [markdown] keys flattened to MARKDOWN_* — so a setting can be tried locally while the committed file stays untouched:

EVERLOCK_SITE_BUILD_FUTURE=true everlock site preview --path ./website

EVERLOCK_SITE_PAGINATE_BY=3 \
EVERLOCK_SITE_MARKDOWN_SMART_PUNCTUATION=true \
everlock site preview --path ./website

Booleans take true/false (or 1/0), EVERLOCK_SITE_IGNORE_DIRS takes a comma-separated list, and everything else is a plain string. An override replaces just its own setting — the rest of site.toml stays in effect, including sibling [markdown] keys. A variable that names no known setting, or a value that fails to parse, is reported in the server log together with the list of valid settings.

The environment is read once at process start and applies to every site the process serves, which makes this a tool for local previews and staging instances rather than per-site production configuration.