Introduction

Cairn is a static-site build tool for documentation and content sites: one binary, one config file, and a folder of Markdown that becomes a deployable site. This page explains what it is and how its pieces fit.

What Cairn is

Cairn takes a folder of Markdown files and builds it into plain HTML, CSS and assets that any static host can serve. There is no runtime, no database and no plugin system to configure before you can write: the tool ships as a single self-contained binary, and a working project is three things: a content/ folder, a cairn.toml, and a theme.

That smallness is the point. Everything Cairn knows about your site is visible in the project folder, so there is no hidden state to fall out of step with your files, and nothing to migrate when you move machines. Delete a page and it is gone on the next build; nothing else references it.

Why it exists

Most site generators grow toward being application frameworks: a plugin API, a data layer, a template language with its own package ecosystem. That flexibility is real, and so is its cost: a content site ends up with a build it cannot explain. Cairn goes the other way: it does one shape of site extremely well and refuses the rest.

In practice that buys you two things. Builds stay fast enough to feel instant, with incremental rebuilds of a large site landing in tens of milliseconds, and projects stay legible: a colleague can open the folder, read cairn.toml top to bottom, and know everything the build will do.

Core concepts

Three ideas carry the whole tool. Everything else is a flag.

The content directory

Every Markdown file under content/ becomes a page, and URLs mirror the folder tree: content/guides/install.md builds to /guides/install/. Each file opens with a small front matter block between +++ fences; a title is the only required key.

+++
title = "Installing"
weight = 2
+++

# Installing

One binary, no dependencies.

One config file

cairn.toml at the project root is the only configuration. It names the site, points at the theme, and sets build options; the scaffolded file is a handful of lines and the full reference fits on one page.

Themes

A theme is a folder of templates and CSS. The default theme covers a complete docs site out of the box, and overriding it is file-by-file: copy the one template you want to change into your project and Cairn prefers your copy. There is no theme API to learn; see Themes.

Where to go next

1. The Quickstart takes you from nothing to a deployed site in about five minutes.
2. Configuration is the complete cairn.toml and front matter reference.
3. Deploying covers hosts, CI and redirects once you are ready to ship.