cairn.pub
On this page
  1. What cairn is
  2. Roles
  3. Signing in
  4. Posts and pages
  5. Writing
  6. Components
  7. Images
  8. Tags
  9. Tidy, if your site has it
  10. Saving and publishing are separate steps
  11. When something looks wrong
  12. The guides

Help

This page is for the people who write on a cairn site: what the system is, how you sign in and write, and what happens when you publish. The detailed guides are linked at the end.

What cairn is

Your organization’s website runs on a system called cairn: open-source software built to help small teams manage a website together, with the writing experience of the people who use it at its center.

Most of the system works out of sight. The part that concerns you is the one it was built around: a writing environment where the people of your organization draft, revise, and publish the site’s pages themselves, with no technician in the loop for the everyday work of writing. A developer set the site up once and remains behind it; from that point on, the words belong to the writers.

Two facts about the arrangement are worth holding from the start. Nothing you do while drafting can break the live site, since your work stays private until you deliberately publish it. And every save is kept, so no version of your work is ever lost.

Roles

By default, cairn has exactly two roles, and they are the entire permission model. Editors write, save, and publish. Owners do everything editors do and also manage the editor list itself: adding a new colleague, removing a departed one, granting ownership to another. Some organizations name their own roles on top of this (an instructor, a club admin) for a screen your developer built, but for cairn’s own writing surface, you’re still either an editor or an owner. There are no finer-grained permissions to learn, no workflows to configure, and no approval queues; a site of this scale runs on trust, and cairn’s design assumes it.

Signing in

Signing in happens entirely by email. Enter your address at your site’s /admin page, and a sign-in link arrives in your inbox; following it signs you in on that device. There is no password; access rides on your email address, which means there is nothing to forget, nothing to reuse across sites, and nothing for an attacker to steal from a leaked list. If a link doesn’t arrive within a minute or two, check spam, then confirm with your site’s administrator that your address is on the editor list.

Posts and pages

Everything you write is either a post or a page, and the difference is the one you’d guess from any publication. A post is dated: news, announcements, anything that belongs to a moment. Posts accumulate newest-first and feed the site’s archives, and they are what a reader means by “what’s new.” A page stands outside time: About, Join, Contact, the writing that describes the organization rather than reports on it. Pages tend to live in the site’s navigation, and they change by revision rather than by succession.

When you create something new, the choice between them comes first, and it’s usually obvious. If it could go out in a newsletter, it’s a post. The standing facts of the organization (how to join, where to find you, who to contact) are pages. Some sites add kinds of their own (a club might keep bulletins or race results as separate lists), and each behaves like one of the two: dated or standing.

Writing

You write in markdown, a convention for indicating structure in plain text that has become the standard for serious writing tools. It was designed in 2004 around one principle: a marked-up document should remain fully readable as ordinary text, because the marks mirror what they mean. Asterisks around a phrase emphasize it even before anything renders, a line beginning with # reads as the heading it is, and a bracketed phrase followed by an address is recognizably a link:

## A heading

Some words matter more than others, so you can make them **bold** or
give them *emphasis*. A blank line starts a new paragraph, and
[a link](https://example.com) is a bracketed phrase followed by its address.

- A list is lines that begin with a dash.
- Readers see them as proper bullets.

> A quotation is a line that begins with an angle bracket.

The toolbar enters the marks for you, the editor keeps a cheat-sheet for the rest, and a spellchecker runs as you type. The division of labor is deliberate: your marks say only what something is, a heading or an emphasis, and the site decides how everything looks, so every page you write stays consistent with the rest of the site.

The editor itself is built for sustained writing, and it borrows deliberately from the desktop writing apps. Its default posture sets prose in a comfortable reading measure with generous type, and a second posture, one click away, shows the same text denser and closer to the markup, which is the better view for reworking tables or long link lists. Focus mode dims every paragraph except the one you’re writing in. Typewriter scrolling keeps your current line vertically centered, so your eyes stay in one place while the page moves. Zen mode clears everything else away. None of these change your text, and you can ignore every one of them and type.

The preview beside your writing doesn’t approximate your site’s look; it renders your draft through the site’s own machinery, typography and all. When you’re deciding whether a heading breaks where it should or a quotation carries the weight you want, you’re deciding against the real thing.

If you’ve written in iA Writer, Ulysses, or Bear, the marks will already look familiar, and if you haven’t, you’ll be learning the same convention those tools teach.

Components

Markdown covers prose. For the pieces of a page that are more than prose (a photo with a caption, a callout box, a pull quote, a video), cairn uses components. A component arrives through the insert menu as a small labeled block: in the plain text it reads as what it is, and in the preview it appears as the site’s styled version.

The insert menu composes these: it asks for the block’s particulars and writes the markup itself. A finished callout, for example, looks like this in your draft:

:::callout[Bring a life jacket]{tone="tip"}
The club has loaners at the boathouse, but the ones that fit
best are the ones you own.
:::

And renders like this on the page:

Edit the words inside a block freely, and leave its marker lines as they are; if one is ever damaged, the insert menu can produce a fresh one. Your site’s component library may differ from this site’s, and if it doesn’t meet your needs, a new component is exactly the kind of thing your site’s developer can build for you.

Images

Images arrive through the same insert flow as everything else. Choose a picture from your site’s media library, or upload a new one on the spot, and the editor places it in your draft with a spot for a caption. Each image asks for a short written description as well; readers who use a screen reader hear that description in place of the picture, and writing a good one is part of the craft. The test is whether the description carries what the picture contributes in context: for a racing story, “two dinghies rounding the windward mark in light air” serves the reader; “sailboats on a lake” does not.

Tags

Posts carry tags (your site may name them topics), and the tags come from a single list the site maintains, rather than from whatever each writer types in the moment. The constraint is deliberate: one shared vocabulary means the site’s archive pages and topic feeds stay coherent as different people write over the years. If a tag you need is missing, the list can be extended in the admin.

Tidy, if your site has it

Some sites turn on tidy, an AI copy-editing tool built on Claude, Anthropic’s language model. It reads your draft, or a passage you select, and proposes the kind of small fixes a professional copy editor would mark: a misspelling, a doubled word, a comma that splices two sentences. Its remit stops where your choices begin. Word choice, sentence rhythm, structure, argument, and tone are yours; a stylistic decision is not an error. It shows you each proposed fix beside your original, changes nothing until you accept it, and an accepted round can be undone in one step. It is not meant to draft your prose, and it will not take your voice.

Saving and publishing are separate steps

Save keeps your work private: a draft persists indefinitely, and readers never see it. You can save a half-formed thought on Tuesday and return to it in March; nothing expires, and nothing is published by accident. Publish is the deliberate step that puts words on the live site; until you take it, nothing changes for readers, and shortly after you take it, the live site carries the new page.

The entry list shows where everything stands. A published post reads as published; one with unpublished changes is marked Edited; a brand-new draft is marked New. If someone else edited the same entry while you were writing, cairn refuses to save over their work. Neither of you can lose words to the other.

When something looks wrong

Your site’s administrator is the first call. A useful report names the page, what you did, and what you saw; a screenshot spares everyone a paragraph of description. Some oddities are ordinary: a page you just published can take a short while to appear, because the live site rebuilds itself after each publish, and a photo that looks fine in the preview but wrong on the page usually means the site’s design handles that image size differently in context, which is worth showing the administrator rather than fighting alone.

Behind all of it sits the same guarantee this page opened with: everything you publish is kept in the site’s history, so the administrator can restore an earlier version of any page, and nothing you can do in the writing environment is expensive to undo. The worst case is asking for help, not losing work.

The guides

The full editor guides render here on this site, part of cairn’s own documentation: