Themes

A theme is a folder of templates and CSS, nothing more. The default covers a complete docs site; making it yours ranges from changing six CSS custom properties to replacing templates one file at a time.

The default theme

cairn init copies the default theme into your project as theme/, so you own it from the first build: it is code in your repo, not a dependency that updates underneath you. It renders the layout you are reading now (top bar, sidebar tree, article column and an "on this page" rail), and it is deliberately small enough to read in one sitting.

Theme structure

Cairn looks for three kinds of file in the theme folder: a page shell, partials the shell includes, and static assets copied through with the build.

Overriding templates and partials

Templates resolve project-first: if a file exists at the same path in your project's theme folder, Cairn uses yours; otherwise it falls back to the built-in copy. That makes customisation incremental: override one partial today, another next month, and diff against the original whenever you upgrade.

Templates are plain HTML with a small set of {{ }} placeholders. There are no loops to learn beyond the two you can see in the default theme.

<!-- Replaces the built-in footer on every page -->
<footer class="site-foot">
    <p>{{ site.title }} · built {{ build.date }}</p>
</footer>

Theming with CSS custom properties

theme.css opens with a token block, and every colour, font and measurement in the stylesheet resolves from it. Most reskins never go past this block.

:root {
    --ground: #FCFCFA;   /* page background */
    --ink: #20241F;      /* reading text */
    --accent: #17694A;   /* links, active states */
    --font-body: system-ui, sans-serif;
    --measure: 46rem;    /* article column width */
}