Quickstart

Cairn turns a folder of Markdown into a fast static site with one binary and one config file. This page takes you from nothing to a deployed site in about five minutes.

Install

Cairn ships as a single self-contained binary. Pick whichever route fits your machine; they all put the same cairn executable on your path.

curl

# macOS and Linux
curl -fsSL https://get.cairn.build | sh

Homebrew

brew install cairn-build/tap/cairn

npm

npm install -g @cairn/cli

Check the install with cairn --version. You should see 2.4.1 or newer.

Initialise a project

cairn init scaffolds a working site: a content folder, the default theme, and a cairn.toml already pointed at both.

terminal

cairn init docs
cd docs
cairn serve

cairn serve starts a local server at localhost:4131 with live reload. Edit any file under content/ and the browser refreshes before you have switched windows back.

Project structure

Everything Cairn needs lives in the folder you just created. There is no hidden state and no lockfile; the tree below is the whole project.

cairn.tomlsite config, one file
content/
- index.mdbecomes /
- guides/
  - install.mdbecomes /guides/install/
theme/
- layout.htmlpage shell
- theme.css
static/copied through untouched
dist/generated; never edit

URLs mirror the content tree: content/guides/install.md builds to /guides/install/. Delete a file and its page is gone on the next build; nothing else references it.

Configuration

All configuration is cairn.toml at the project root. The scaffolded file sets the first three options; the rest have defaults you can leave alone until you need them.

cairn.toml options
Option	Type	Default	Description
`title`	string	"Cairn Site"	Site name, used in the shell and page titles.
`base_url`	string	"/"	Absolute URL of the deployed site; feeds canonical links and the sitemap.
`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.

cairn.toml

title = "Fieldnotes"
base_url = "https://docs.fieldnotes.dev"
theme = "theme"

# optional
minify = true
drafts = false

Build and deploy

Build

One command, no flags needed. Cairn rebuilds only what changed, so second builds of a large site land in tens of milliseconds.

terminal

cairn build
➤ 42 pages in 118ms → dist/

Note

dist/ is disposable. Add it to .gitignore and let your host build from source; committing build output is the most common cause of stale pages.

Deploy

dist/ is plain static files, so any static host works: point Netlify, Cloudflare Pages, or GitHub Pages at the repo with cairn build as the build command and dist as the output directory. Nothing runs at request time.

Troubleshooting

The two problems nearly every first build hits, and their one-line fixes.

Note

Pages missing from the build? Files without front matter are skipped by design. Every page needs at least a title key between the +++ fences at the top of the file.

Warning

Never edit dist/ by hand. It is cleared and rewritten on every build, so hand edits are silently destroyed. If you need a file carried through verbatim, put it in static/ instead.