Configuration

Everything Cairn can be told lives in two places: cairn.toml at the project root, and a front matter block at the top of each page. This page is the complete reference for both.

The file

cairn.toml has two tables, [site] and [build], plus optional [[nav]] entries. Every key has a default, so a working file can be three lines; this one sets everything.

cairn.toml

[site]
title = "Fieldnotes"
base_url = "https://docs.fieldnotes.dev"
language = "en"
description = "Field guides for small teams"

[build]
theme = "theme"
output = "dist"
minify = true
drafts = false
hash_assets = true

# Optional: pin entries into the top of the sidebar
[[nav]]
label = "Changelog"
path = "/changelog/"

Note

cairn serve re-reads cairn.toml on every save, so config edits show up on the next reload. cairn build reads it once at startup.

The [site] table

Identity keys: they feed page titles, canonical links, the sitemap and the feed. None of them affect what gets built.

[site] keys
Key	Type	Default	Description
`title`	string	"Cairn Site"	Site name, used in the shell and every page title.
`base_url`	string	"/"	Absolute URL of the deployed site; feeds canonical links, the sitemap and the feed.
`language`	string	"en"	Written to the `lang` attribute of every page.
`description`	string	""	Fallback meta description for pages that set none of their own.

The [build] table

Behaviour keys: what gets built, where it lands, and how it is fingerprinted.

[build] keys
Key	Type	Default	Description
`theme`	string	"theme"	Folder the page shell and styles load from.
`output`	string	"dist"	Where builds land. Cleared and rewritten on every build.
`minify`	bool	true	Minify HTML and CSS output. Turn off when diffing builds.
`drafts`	bool	false	Include pages marked `draft = true`. `serve` always includes them.
`hash_assets`	bool	true	Fingerprint CSS and theme assets (`theme.a41f.css`) so far-future cache headers are safe.

Navigation and the sidebar

You do not configure the sidebar; Cairn derives it. Folders under content/ become groups, pages become links, and both sort by weight, then title. The tree in your repo is the tree your readers see.

[[nav]] entries exist for the exceptions: links you want pinned above the derived tree regardless of where (or whether) they live in content/. Each entry is a label and a path, and order in the file is order on the page.

cairn.toml

[[nav]]
label = "Changelog"
path = "/changelog/"

[[nav]]
label = "GitHub"
path = "https://github.com/cairn-build"

Per-page front matter

Each Markdown file opens with a TOML block between +++ fences. Only title is required; a file without front matter is skipped by design.

Front matter keys
Key	Type	Default	Description
`title`	string	required	Page title: the h1, the sidebar label, and the browser tab.
`description`	string	site default	Meta description for this page.
`weight`	int	0	Sort order within the page's folder; lower sorts first.
`draft`	bool	false	Excluded from `build` unless `drafts = true`; always served locally.
`template`	string	"page"	Theme template to render with, for one-off layouts.

content/guides/deploying.md

+++
title = "Deploying"
description = "Ship the dist folder to any static host."
weight = 3
+++