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
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.