Documentation Site Template

What's Included

Code snippet omitted: it ships with the download.

No build step and no images. Open any page and it runs; every page shares the one assets/ folder.

The reading order (which is also the prev/next pager order) is: Introduction → Quickstart → Configuration → Themes → Deploying → CLI reference. The Quickstart lives at index.html so a deployed site lands visitors on the page most of them want.

Quick Start

1. Replace the brand in the top bar: the wordmark text, the version badge, and the github.com/cairn-build link. The top bar is repeated markup, so this edit happens in all six files (a find-and-replace across *.html does it in one pass).
2. Replace each article with your own content (see Writing pages — the search, rail and copy buttons follow your markup automatically). Delete any page you don't need, and remove its sidebar entry from the other files.
3. Update each page's <title> and <meta name="description">.
4. Deploy the folder anywhere that serves static files.

Adding a Page

The honest cost of plain HTML with no build step: shared chrome is repeated per file, so adding a page touches every file once.

1. Copy the existing page closest to the one you want (a reference page for tables, a guide for prose).
2. Edit its <title>, meta description, crumbs, <h1> and article content, and rebuild its "On this page" list to match the new headings (href="#id" per h2[id]/h3[id]; the scrollspy and palette pick them up from the markup).
3. Add the page's .sb-link to the sidebar in all six existing files, and move aria-current="page" to the right link in the new file.
4. Wire it into the pager: the new page's prev/next, plus the next/prev of its two neighbours.

Steps 3 and 4 are the repetition tax. Everything else (search index, scrollspy, copy buttons, palettes) reads the DOM and needs no registration.

Writing Pages and Sections

The chrome is driven by the markup, so editing content is the whole job:

• Add or rename a section: give it an <h2 id="..."> (or <h3 id="...">). The command palette indexes it at load, and it becomes a scroll target.
• List it in the rail: add a matching <li><a href="#id"> to the "On this page" list. The scrollspy pairs rail links with headings by id and silently skips links whose heading is gone, so a deleted section never breaks the rail.
• Delete anything: every lookup in the script is guarded. Remove the rail, the palette markup, the tabs, or whole article sections and the rest keeps initialising.
• Code blocks: a dark panel is <div class="code"> with a .code-bar label row and a <pre data-code>. Any pre[data-code] gets a copy button injected into its bar at runtime. Syntax colour is hand-marked: wrap commands/keys in <span class="tk-a">, strings/values in tk-s, comments in tk-c.
• Callouts: <div class="callout"> is a note (green border); add callout--warn for the red-bordered warning. The red is a border only — never use it as a text colour, it is not measured for that.
• Tabs: the install block pairs data-tab data-target="name" buttons with data-tab-panel="name" panels by name, not index, so delete or add pairs freely (keep id/aria-controls matched). Without JavaScript the panels stack, each showing its own label.

The Command Palette (the signature)

Cmd+K / Ctrl+K, or the search button, opens the palette on any page. It fuzzy-filters as you type (matched characters highlight), arrows move the selection, Enter jumps — navigating to a page entry, or smooth-scrolling to a heading on the current page and flashing it — and Escape closes, returning focus to wherever you opened it from.

The index is built from the DOM at load: every sidebar link becomes a page entry (grouped under its sidebar heading; choosing one follows the link, or scrolls to the top if it is the current page), every article h2[id]/h3[id] on the current page becomes a heading entry, plus scripted actions ("Copy install command" reads the pre[data-code="install"] block and only exists on pages that have one; "Back to top"). There is no list to maintain — your edits to the sidebar and article are the search index. To add a custom action, push one more { label, kind, group, run } object where the shipped actions are defined in initPalette() in assets/script.js.

Palettes

The template ships with three palettes, each paired with its own display face so the three read as three identities rather than one design in three colours. Paper is the default in :root; Dark and Slate are the ALTERNATE PALETTES blocks at the end of assets/style.css.

Palette	Ground	Accent	Display face
Paper (default)	near-white, barely warm	deep viridian green	Chakra Petch, a squared technical sans
Dark	green-grey near-black	mint	JetBrains Mono 700, a monospace
Slate	cool blue-grey white	deep indigo	Space Grotesk 600, a grotesk

The face and the colours are independent tokens (--font-display and --font-display-weight sit in each block next to the colours), so keep the palette and swap the face, or the other way round. All three faces are in the Google Fonts <link> in the <head> of every page; a browser only downloads the one the page uses, but once you have settled, trim the link to the family you kept. The reading face (Wix Madefor Text) and the code face (Ubuntu Sans Mono) are the same in every palette.

To use one, set the attribute on the <html> tag of every page (the palette is pure CSS, so the attribute is the whole mechanism):

Code snippet omitted: it ships with the download.

That is the whole change. Each block restates every colour token and its --*-rgb triple, and everything on the page already draws from those tokens, so nothing else needs touching. Once you have settled on one, the tidier end state is to copy its values into the :root block at the top of style.css and delete the alternates, so the stylesheet states one palette rather than three.

Dark is a reading theme, not a terminal. The ground stays off black, raised panels go lighter than the ground, ink is a soft off-white rather than pure white, hover links go lighter (--accent-deep holds a paler mint, where the light palettes hold a darker green), and code panels sit slightly above the ground where in the light palettes they are the page's one dark mass. It also restates color-scheme: dark, so native scrollbars and form chrome follow.

Two tokens exist only because of the dark palette. --scrim (the dialog and drawer backdrop) and --shadow-rgb (box shadows) are stated per palette instead of deriving from --ink-rgb: in Dark, --ink is near-white, and a backdrop derived from it would render a white fog instead of dimming the page.

The default token block, for reference:

Code snippet omitted: it ships with the download.

Contrast. Every palette is measured to the same bar, composited on the surface it lands on: ink and both its dim variants on the ground, the sidebar panel and the cards; the accent as text on all three and on both washes; the code panel's ink, comment, string, label and command colours; text on the solid-accent "Copied" state; and the red border at the 3:1 non-text bar. The full tables are in the header comment at the top of style.css. Everything clears 4.5:1 (the red is a border only, never text, in every palette). If you edit a palette: in Paper the first pair to fail is accent text on --accent-wash over the sidebar (keep --accent at or darker than #1E7A57); in Dark it is the same pair as the mint darkens (keep --accent at or lighter than #74B892).

The picker on the demo is not in your download. The dock in the corner of the online demo is preview scaffolding that lives in a file the zip does not contain. Your copy has the palettes without it, which is the right way round: a real docs site should not carry a theme switcher.

Type

• --font-display — Chakra Petch: wordmark, headings, sidebar group labels, table headers. Squared, technical, used at conservative sizes. --font-display-weight (600) is the weight those labels and h2/h3 use; the wordmark and h1 stay at 700. Dark and Slate set both tokens to their own faces (see Palettes).
• --font-body — Wix Madefor Text: all reading text.
• --font-mono — Ubuntu Sans Mono: code, the version badge, kbd hints.

Swap them by editing the tokens and the Google Fonts <link> in the <head> of every page together.

Accessibility

• Skip link to the article; real <nav>, <main>, <article>, <aside> landmarks; heading order h1 → h2 → h3; the options table is a real <table> with a caption and column headers.
• The palette is role="dialog" aria-modal="true" with a combobox input driving a listbox via aria-activedescendant; focus is trapped while open and returned on close. The install tabs are a real ARIA tablist with roving tabindex, arrow keys, Home and End.
• Visible focus rings everywhere (2px accent outline; mint on the dark code panels), measured in the table above.
• Reduced motion: the palette opens and closes instantly, the rail marker jumps, tabs swap without fading, and Lenis never starts, via both the CSS media query and the gsap.matchMedia branch.
• Without JavaScript nothing is lost: the sidebar groups are native open <details>; the rail is plain anchor links; the install panels stack, each labelled; the search and menu buttons (which can only drive JS) are hidden; copy buttons are injected at runtime so they never exist to fail. The has-js class is added synchronously in <head> and removed by the script if GSAP fails to load, so a blocked CDN degrades to the same plain document.

Smooth Scrolling

Lenis drives window scrolling on the shared GSAP clock and is optional: remove the CDN tag and the lenis block near the top of script.js to drop it. It is also switchable without edits — data-smooth="off" on <html> or ?smooth=off in the URL — and it never runs under reduced motion. The sidebar carries data-lenis-prevent, which keeps the mouse wheel native inside its own scroll; put that attribute on any other scrollable panel you add.

Dependencies

• GSAP 3.15.0 (core)
• ScrollTrigger
• Lenis 1.3.17 (optional)