colophon docs

colophon documentation

2001-12-30T00:00:00Z

End-user guides for authoring, theming and publishing a colophon site.

Authoring content — frontmatter, supported Markdown, the rich blocks (maths, diagrams, callouts, code) and how they render, wikilinks, embeds and images.
Themes — selecting a theme, per-environment theme overrides, writing or overriding a theme, the template variables, and progressive enhancement.
SEO & social — the seo: frontmatter block and the canonical / Open Graph / Twitter / JSON-LD metadata colophon emits.
Image & audio generation — gen: image prompts, AI or recorded post audio (podcast feeds), providers, the --generate-ai step, the kill switch, and pruning.
Authors & personas — the author (the shown byline + h-card) vs the persona (a hidden, shareable writing voice), and the persona context command that emits write-as context (style guide + relevant exemplars) for an AI author.
Publishing — environments vs publishers, credentials, and routing assets to an object store.
Syndication (POSSE) — cross-post to Mastodon/Bluesky/anywhere with colophon syndicate: the ledger, gating, and the command/mastodon/bluesky/bridgy drivers.
Agent skills (design) — the planned authoring skills (seo, draft, tag, social…) and the prompt packs that drive them.
How-to guides — short zero-to-published recipes: federate via Bridgy Fed, show webmentions, syndicate to Mastodon/Bluesky. Each notes whether it's shipped or planned.
Changelog — user-facing changes per release, each pointing at the guide that documents it in full.

Design notes and the roadmap live in PLAN.md and design/.

Generated from docs/README.md — edit it there.

Authoring content

2001-12-29T00:00:00Z

A colophon post is a Markdown file with a YAML frontmatter block. Files come from one or more sources (a content/ folder, an Obsidian vault, …); the source's folder structure becomes the site's URL structure.

---
title: My first post
date: 2026-06-15
description: A one-line summary for feeds and link previews.
tags: [notes, colophon]
draft: false
---

Write the body in **Markdown**.

Frontmatter fields

All fields are optional unless noted.

Field	Meaning
`title`	Post title. If omitted, falls back to a leading `# heading` or the file name.
`date`	Publish date (`YYYY-MM-DD`). If omitted (Obsidian), the file's modified time is used.
`type`	Page type (`post`, `page`, or a custom value). Overrides the date-based default — see Page types.
`slug`	Overrides the final URL segment (otherwise derived from the file path).
`aliases`	Old/alternate URL paths that redirect here (e.g. after a rename) — see Redirects.
`description`	Summary for feeds, `<meta name="description">` and `og:description`.
`tags`, `categories`	Lists for organisation/feeds.
`author`	The byline — an `authors/<id>.yaml` id. Defaults to the first author, else "Anonymous". See Authors & personas.
`persona`	The hidden writing voice (a `personas/<id>.yaml` id) used by the agent; never shown.
`hero`	Banner image shown at the top of the post. A path, an Obsidian `"[[image.png]]"`, or a `"gen:<prompt>"` to generate one — see Image generation.
`image`	Preview/social-card image (`og:image` + index thumbnail). Accepts a path or a `"gen:<prompt>"`.
`hero_alt`, `image_alt`	Alt text for those images. Empty = decorative (`alt=""`); set it when the image carries meaning.
`hero_fit`, `image_fit`	How the image fills its box — CSS `object-fit`: `cover` (crop, default), `contain` (letterbox), `fill`, `scale-down`, `none`.
`hero_position`, `image_position`	Which part shows when cropping — CSS `object-position`, e.g. `top` or `50% 20%`.
`audio`	Spoken (TTS) reading of the post. Omit to follow the site default (on when a speech provider is configured); set `true`/`false` to force it. Needs `generation.speech`. See Image & audio generation.
`audio_file`	Attach a pre-recorded audio file (a path or `[[embed]]`) instead of generating one — no AI. Wins over `audio`.
`audio_voice`	Override the reading voice id (generated audio only); else the author's/persona's `voice`, else the site default.
`attachments`	Downloadable files shipped with the post (scripts, archives, datasets, PDFs…). A list of paths or `{path, label, feed}` mappings — see Attachments (downloads).
`syndication`	URLs where this post also lives (e.g. a Mastodon/Bluesky copy you cross-posted). A list of absolute URLs, rendered as mf2 `u-syndication` "Also posted on…" links. The `colophon syndicate` ledger also feeds these automatically.
`syndicate`	POSSE control for `colophon syndicate`: `false` opts this post out; a list (`[mastodon]`) picks a subset of the environment's targets; absent = all of them.
`syndicate_text`	Optional custom blurb for the syndicated copy (else the driver derives one from the title/summary).
`lang`	Per-post language (BCP-47, e.g. `fr`), overriding the site `lang`. Emitted as `<html lang>`.
`glossary`	`false` turns off automatic glossary decoration for this post; an explicit `<abbr>` still works.
`draft`	`true` keeps the post out of production builds (shown in preview/serve).
`publish`	Obsidian whitelist flag, honoured when a source sets `publish_required: true`.
`publish_after`	Embargo: not published until this time (ISO 8601, e.g. `2026-07-01T09:00:00Z`).
`predecessor`	The slug (or bare filename) of the post that immediately precedes this one in a series — see Post series.
`series`	Optional series title. Latest-wins: the newest post in the chain that sets it names the series.

Slugs are normalised: each path segment is lower-cased and non-alphanumerics collapse to single hyphens, so Archive/My Post.md → archive/my-post.

Page types

Every entry has a type that decides how it's placed and which theme template renders it:

A post is chronological — listed on the index, included in feeds, and shown on its tag pages.
A page is standing chrome — surfaced in the theme's nav menu instead, and kept out of the list and feeds (e.g. About, Now).

By default the type is inferred: an entry with a date is a post, one without is a page. Set type: in frontmatter to override that, or to use a custom type:

---
title: Side Projects
type: project        # a custom type; styled by a theme's project.html if it has one
---

type: page makes a dated entry standing (nav, not feeds); type: post makes a dateless entry a listed post.
A custom type (e.g. project) is listed like a post, but a theme can give it its own look — see Themes → Page types. This type is unrelated to seo.type (the schema.org type).

Post series

A post can declare that it follows an earlier post with a single backward link, and colophon reconstructs the whole ordered series from those links — adding "Part N of M" / previous / next navigation to every member.

---
title: "Building a Widget, Part Two"
date: 2026-06-11
predecessor: building-a-widget-part-one   # the post just before this one
---

predecessor: pins the slug (or bare filename, resolved like a [[wikilink]]) of the immediately preceding post. It's a single linear chain — a post is in at most one series.
series: is the optional title. It's latest-wins: the name is taken from the newest post in the chain that sets it; if no member sets it, the series is untitled.

Because colophon rebuilds the whole site every time, a backward pointer is enough — you never edit old posts. Publishing Part Two (which points back at Part One) is what gives Part One its forward link to Part Two; the engine walks the chain and regenerates both. The series renders oldest→newest, and the current post is highlighted in the list.

Themes get per-post variables (series_name, series_total, series_index, series_parts, series_prev, series_next) — set only for posts in a series of two or more — and a series flag on each post-list item. The bundled press theme shows the series in the left rail and marks series entries on the index; other themes can adopt the variables.

colophon doctor warns (without failing) when a predecessor: doesn't resolve to a known post, when the links form a cycle, or when two posts name the same predecessor (a branch).

Markdown support

colophon parses GitHub Flavored Markdown — tables, strikethrough, task lists, autolinks — plus automatic heading IDs (so ## My Heading is linkable as #my-heading).

The raw-block contract (progressive enhancement)

Rich blocks are rendered as semantic HTML that carries its raw source as text, tagged by type. colophon itself loads no JavaScript — it only guarantees the markup. A theme then chooses how to present each block: a no-JS/minimal theme shows readable raw text; the default theme upgrades it with highlight.js, KaTeX and Mermaid.

You write	colophon emits	Enhanced by
```go … ```	`<pre><code class="language-go">…</code></pre>`	a syntax highlighter
```mermaid … ```	`<pre class="mermaid">…</pre>`	Mermaid
$E=mc^2$ (inline)	`<span class="math math-inline">E=mc^2</span>`	KaTeX
`$$ … $$` (display)	`<div class="math math-display">…</div>`	KaTeX
`> [!note] Title` …	`<div class="callout callout-note">…</div>`	CSS only (no JS)
`> [!quote] Attribution` …	`<figure class="pullquote"><blockquote>…</blockquote><figcaption>…</figcaption></figure>`	CSS only (no JS)

Notes:

Maths is matched on a single line. A currency heuristic leaves prose like $5 and $10 alone. The LaTeX source is preserved verbatim, so it is readable even without KaTeX.
Callouts use Obsidian syntax — a blockquote whose first line is [!type] Optional Title. The body is normal Markdown. Types map to colours via CSS classes (note/info, tip/success, warning, danger, example, …).
Pull-quotes are the [!quote] callout type — they render as a semantic <figure> with the text after [!quote] as the attribution <figcaption> (omit it for an unattributed quote). The press theme styles this as a large display epigraph; other themes can target .pullquote. Plain blockquotes (> without [!quote]) are unchanged.
Mermaid uses the diagram source as the element's text, so it degrades to a readable description without the library.

Tip — preview every feature in your theme. colophon serve --showcase injects a built-in /showcase/ page (embedded in the binary, never written to your content) that renders every one of these blocks — callouts, pull-quotes, tables, maths, diagrams, media, attachments, glossary — in your active theme, with the source shown alongside. Handy when writing or styling a theme.

Links, wikilinks and images

Standard Markdown links and images work as usual.
Wikilinks resolve across every source at build time — a vault note can link to a post in content/ and vice versa: [[note]], [[note|alias]], [[note#heading]]. An unresolved link degrades to plain text rather than breaking.
Tags (tags: frontmatter) render on each post and on the index, linked to a generated page per tag at /tags/<tag>/ that lists every post sharing it — so tags become sideways navigation across entries.
Embeds (![[image.png]], ![[image.png|alt]]) resolve attachments vault-wide and are copied next to the page.
![](relative.png) images are copied beside the page so the relative src resolves; external (https://…) images are left untouched.
Generated images — ![alt](<gen:a prompt here>) produces the image with an AI provider and caches it. Wrap the prompt in <…> when it contains spaces. See Image generation.
Video & audio embeds — an image embed whose target is a media file renders as a player, not a broken image. ![A short demo](demo.mp4) becomes a <video controls>; ![](clip.mp3) becomes an <audio controls>. The file is copied/routed exactly like an image (so object storage works the same), and the embed's alt text becomes the player's aria-label. See Embedding video and audio.

Images and object storage

By default images are co-located with the page and served relatively. A site can route images (or any path glob) to an object store (e.g. Cloudflare R2) instead — see the publisher configuration. When routing is active the build rewrites those image URLs to the store's public base, so the page references https://assets.example.com/… while the bytes are uploaded to the store rather than your HTML host.

Embedding video and audio

There is no new syntax — use the markdown image embed you already know, pointing at a media file. colophon recognises the extension and renders a player instead of an <img>:

![A short demo](demo.mp4)     <!-- → <video controls>, with the alt as its aria-label -->
![[demo.mp4]]                  <!-- Obsidian embeds work too -->
![](interview.mp3)            <!-- → <audio controls> -->

Video: .mp4, .webm, .mov, .m4v, .ogv. Audio: .mp3, .m4a, .aac, .oga, .ogg, .wav, .flac, .opus.
The file is discovered, copied beside the page, and routed to object storage exactly like an image — self-hosting "just works", including via R2.
A direct external file URL plays too (e.g. ![](https://cdn.example.com/clip.mp4)); it is left untouched and not copied.
This is independent of audio_file:/audio:, which attach a single podcast-style reading of the whole post (with the themed player and feed enclosure). Inline embeds are just media in the body.

Big files belong in object storage or a CDN, not your Git host. Route a **/*.mp4 glob to R2 (see the publisher config) and the embed URL is rewritten automatically.

Attachments (downloads)

List downloadable files in frontmatter and colophon copies/routes them like images and renders a Downloads block on the post. Each entry is either a bare path or a {path, label, feed} mapping:

---
title: Release Notes
attachments:
  - changelog.txt                                   # label defaults to the file name
  - { path: build.sh, label: "Build script", description: "Sets up the toolchain" }
  - { path: dataset.zip, label: "Dataset", description: "Raw measurements", feed: true }
---

Paths resolve relative to the post (same rules as an image embed); [[embed]] works too.
label sets the link text (defaults to the file name); description adds a one-line note beneath it. The file's size and a short filetype badge (ZIP, PDF, MP4…) are shown automatically.
feed: true also lists the file as a feed enclosure/attachment (see below). Without it, the file is downloadable on the page but stays out of the feeds.
Posts with attachments get a small paperclip marker in the listing (alongside the audio speaker), in the press and contrib themes.

Attachments in feeds. A post's audio reading and any feed: true attachment are emitted to the syndication feeds so podcast/feed clients can fetch them:

JSON Feed — every item appears in attachments (multiple allowed).
Atom — each is a <link rel="enclosure"> (multiple allowed).
RSS — carries a single <enclosure> per the spec: the audio reading wins, else the first feed: true attachment.

Slide decks

A post can be projected into a themed slide deck — published at …/<slug>/slides/, linked from the post's Downloads box, and flagged with a slides marker in the listing (alongside the audio and attachment markers). It's derived from the post: headings become slides (or bullets), prose becomes speaker notes, and other blocks render on the slide. With JavaScript it's a keyboard/swipe presentation (P = presenter notes, F = fullscreen); with JS off the same file reads as a long-form document.

Set the site default in colophon.yaml (slides.enabled), then opt a post in or out:

---
title: A Short Talk
slides: true                 # or the block form below
# slides:
#   enabled: true
#   split: [h2]              # slide boundaries (a list). default: every heading.
---

split lists the boundaries: h1–h6, hr, splitslide, the block kinds image/table/ code/math/diagram/audio/video, and text:<match> (split before a block whose text begins with the match). The default splits on every heading; narrow it (e.g. [h2]) to fold deeper headings into bullets.
The post's slides: overwrites the site default by key (it does not deep-merge): a key you set replaces that value, keys you omit inherit.
A site-wide slides.enabled: true applies to listed content (posts and custom types); standing pages (About, etc.) don't get a deck from the default — they opt in with their own slides: true.
An environment can override the site default (slides: { enabled, split } under the environment), e.g. decks on in preview, off in production.
Three inline markers mirror the <tts> family: <splitslide> forces a break, <slide>…</slide> makes one verbatim slide, and <noslide>…</noslide> stays in the post but is kept out of the deck.

Multiple languages (translations)

Publish the same post in several languages. Enable the languages on the site, then add a translation with a .<lang>.md filename:

# colophon.yaml
sites:
  - lang: en                 # the default language (stays at the normal URL)
    languages: [en, es, fr]  # the languages you publish in

content/posts/my-post.md       → English   →  /posts/my-post/
content/posts/my-post.es.md    → Spanish   →  /es/posts/my-post/
content/posts/my-post.fr.md    → French    →  /fr/posts/my-post/

Translations are linked by their base slug (my-post); each can set its own title, description, hero, even slug. The default language stays at the normal path; others are published under a /<lang>/ prefix.
Every translation emits hreflang alternates (plus x-default) so search engines serve the right language, and the press theme shows a language selector in the post header.
A small, dismissible banner offers a reader their preferred language (from the browser) when the post is available in it — it never force-redirects.
Each translation is a normal post, so it gets its own spoken reading, feeds, glossary and deck.
A .<lang> is only treated as a language when <lang> is in languages — a file like my.notes.md is unaffected.

How file references resolve

Two kinds of reference resolve differently:

Per-post references — markdown embeds/images, and a post's hero/image — resolve against that post's own source (its driver's rules: a vault searches its scan roots and the vault, an md-dir resolves dir-relative). They stay driver-relative so a missing embed is a real error, not silently masked by another source.
Project-level references — an author avatar — resolve across every content source and then fall back to the project root. The same avatar: assets/me.png therefore works whether the file lives in a content dir, a vault, or the project's own assets/ — portable across drivers.

colophon doctor dry-resolves every defined reference through the same machinery and warns when one can't be sourced (a likely broken link). An undefined reference is fine — it just means none was wanted. data:/http(s):// references always pass through untouched.

Redirects (aliases)

When you rename a post (or want short links), list the old paths in aliases: so the old URLs keep working:

---
title: A Renamed Post
slug: renamed
aliases:
  - old-name            # /old-name/        → /posts/renamed/
  - 2020/legacy-post    # nested paths fine
---

Each alias is normalised like a slug (lower-cased, non-alphanumerics → hyphens, / kept). For each, the build emits:

a meta-refresh stub at <alias>/index.html → the post (works on any static host),
a line in a root _redirects file, and
a root .nojekyll (so GitHub Pages serves the stubs and the _search/ index).

How that becomes a redirect depends on the host: Cloudflare Pages, Netlify and GitLab Pages read _redirects and serve a real 301; S3 static-website hosting gets a 301 too (colophon sets the object redirect header on publish); plain object stores (R2, bare S3/MinIO) and GitHub Pages fall back to the client-side meta-refresh stub. Either way the old URL resolves.

Collisions are resolved deterministically with a warning: an alias that matches a real page is ignored (the page wins), and if two posts claim the same alias the newest wins.

Glossary

Drop a glossary.yaml (term → definition) at the project root and colophon publishes it as glossary.json; a JS-enabled theme then automatically decorates the first occurrence of each term in your prose with an accessible pop-over (a "dictionary stanza" with the term and its definition). It is never rendered as a page, and it degrades gracefully — the text-only theme just shows the words plain.

# glossary.yaml
API: "Application Programming Interface — the contract one program exposes for another to call."
SSG: "Static Site Generator — renders content into static HTML served as-is."

You write naturally — no markup needed. When you do want control over a specific word, three controls are available (the syntactic sugar):

You want…	Write…	Effect
Turn the whole post off	`glossary: false` in frontmatter	No automatic matching. Explicit `<abbr>` forces still work.
Force a specific word	`<abbr>API</abbr>`	Always decorated, even mid-post or in an opted-out post — the same `<abbr>` auto-match produces. An `<abbr title="…">` you write yourself is left alone.
Suppress one word	`<noabbr>Go</noabbr>`	That occurrence is left plain (use it when a term is also a common word). The mirror of `<abbr>`.

Decoration always skips code, links, headings, your own <abbr title="…"> and anything inside <noabbr>, and only the first occurrence of a term is auto-decorated, so a post is never peppered with repeats.

Sources

md-dir — a directory of Markdown files (default: content/).
obsidian — an Obsidian vault, read in place. By convention it publishes only notes with publish: true (unless the source sets publish_required: false), derives a missing title from a leading # heading or the file name, and a missing date from the file's modified time.

Multiple sources are merged into one site; deletions and renames flow through the build's reconciliation, so the output always matches the inputs.

Generated from docs/content.md — edit it there.

Publishing

2001-12-28T00:00:00Z

colophon separates what/where (environments) from how (publishers).

A publisher is a deploy mechanism: copy to a folder, upload to Cloudflare Pages, push to an object store. Publishers are pure mechanism and carry no policy.
An environment is a named build+deploy profile: which publishers to deploy to, whether to include drafts, and optional overrides (title, base_url, theme).

publishers:
  - id: local
    driver: local
    path: ./dist

environments:
  - name: production
    publish: [local]
    allow_publish: false   # safety latch: requires --allow-publish to deploy

colophon publish --env production --allow-publish

Publishers

Driver	Purpose
`local`	Copy the built tree to a directory (offline preview / diffing).
`cloudflare-pages`	Deploy the site to Cloudflare Pages (direct upload).
`cloudflare-r2`	Upload files to Cloudflare R2 (S3 + R2 control-plane: public-URL discovery, `--create` expose).
`s3`	Upload files to any S3-compatible store (MinIO, B2, Wasabi, Amazon S3) — pure data plane, no SDK.
`tigris`	The `s3` driver with Tigris (Fly.io) defaults — needs only a bucket.
`git`	Force-push the built tree to a branch of any git remote (GitHub/GitLab/Codeberg Pages, mirrors, self-hosted).
`github-pages`	The `git` driver with GitHub-friendly defaults (branch `gh-pages`).
`command`	Run any CLI against the built tree (surge, Netlify, Vercel, rsync, …) — the escape hatch.

Configuration and interpolation

colophon has two distinct interpolation layers — they look similar ({…}) but resolve at different times, and every driver supports the first:

1. Config interpolation — {env:VAR} (all drivers, all config). Any string value in the config may reference the environment, resolved before the YAML is parsed, so it works in any setting of any publisher (or anywhere else in the config):

Form	Resolves to
`{env:VAR}`	the value of `VAR`, or empty if unset
`{env:VAR:-default}`	the value of `VAR`, or `default` if unset

Values come from the process environment and from .env / .env.defaults (loaded first; a real env var wins over a .env entry). colophon env lists every {env:VAR} a project references, set or not. This is how non-secret settings stay flexible while secrets stay in the environment — you never write a token into config:

publishers:
  - id: r2
    driver: cloudflare-r2
    bucket: "{env:R2_BUCKET:-my-assets}"          # default when unset
    account_id: "{env:CLOUDFLARE_ACCOUNT_ID}"     # required; empty if unset
    public_url: "{env:R2_PUBLIC_URL:-}"           # optional; empty default

2. Command interpolation — {dir}, {public_url}, … (the command driver only). The command publisher additionally interpolates its command argv at publish time with runtime values (the materialised directory, the manifest path, …) and the publisher's own settings — see Run any CLI. The two layers compose: {env:VAR} is substituted when the config loads, then {placeholder} when the command runs, so a single command entry can use both.

Per-driver settings and their interpolation are documented in each driver's README — linked from the Publishers table targets below and listed in Secrets and permissions.

Secrets and permissions

Deploy credentials are never read from config — they come from the environment, so they never pass through the agent or the YAML:

Publisher	Secret env vars	Token permission
`cloudflare-pages`	`CLOUDFLARE_API_TOKEN`	Account → Cloudflare Pages → Edit
`cloudflare-r2`	`R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` (or `AWS_*`)	R2 → Object Read & Write (+ bucket-create for `--create`)
`s3`	`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`	Object read & write (+ bucket-create for `--create`)
`tigris`	`TIGRIS_ACCESS_KEY_ID` / `TIGRIS_SECRET_ACCESS_KEY` (or `AWS_*`)	Tigris access key (`tid_`/`tsec_`) — Editor
`git` / `github-pages`	`GITHUB_TOKEN` / `GH_TOKEN` / `GIT_TOKEN` (HTTPS remotes only)	Repo contents → write (e.g. a GitHub fine-grained PAT or `GITHUB_TOKEN` in Actions). SSH remotes use the agent — no token.

Non-secret settings (account id, bucket, project) may use {env:VAR} config interpolation. Each driver's README documents its settings and interpolation: local, cloudflare-pages, cloudflare-r2, s3 / tigris, git / github-pages, command.

Provisioning with `--create`

colophon publish --env <name> --create provisions destinations before deploying: cloudflare-pages creates the Pages project; cloudflare-r2 / s3 / tigris create the bucket. All are idempotent — an existing destination is left untouched.

For the object stores, --create also sets a CORS policy allowing cross-origin GET/HEAD from any origin (via the S3 PutBucketCors API — the only way to configure CORS on R2, which has no dashboard for it). This matters when assets are fetched with fetch() or imported as an ES module rather than via an <img>/<script> tag — notably a routed search index (below): a cross-origin <img> needs no CORS, but fetch()/import() do. The step is best-effort: if a store doesn't support PutBucketCors, the publish warns and continues, and you set CORS manually.

Generic S3 / MinIO / Backblaze / Wasabi

The s3 driver is plain S3 (SigV4) with no control-plane code — point it at any S3-compatible store with an endpoint and region:

publishers:
  - id: s3
    driver: s3
    bucket: my-assets
    endpoint: "https://s3.us-east-1.amazonaws.com"   # or http://localhost:9000 (MinIO)
    region: us-east-1
    public_url: "https://my-assets.s3.us-east-1.amazonaws.com"

Credentials come from AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY. publish --create creates the bucket (idempotent). public_url is how colophon learns the public base URL — there's no control-plane lookup, so set it (a route with no resolvable URL stays inactive).

Tigris (Fly.io)

Tigris is Fly.io's global object store, and it's plain S3 — colophon talks to it with the same client as any S3 store, so no flyctl / Fly SDK / control-plane token is involved. The tigris driver is the s3 driver with the endpoint (https://t3.storage.dev) and region (auto) defaulted, so it needs only a bucket:

publishers:
  - id: assets
    driver: tigris
    bucket: my-blog-assets
    public_url: "https://my-blog-assets.t3.storage.dev"   # the bucket's public/CDN domain

Credentials come from TIGRIS_ACCESS_KEY_ID / TIGRIS_SECRET_ACCESS_KEY (the tid_/tsec_ keys, falling back to AWS_*). publish --create creates the bucket. Two things are one-time dashboard settings (Tigris has no data-plane API for them, which is what keeps publishing SDK-free): make the bucket public to serve a site from it, and optionally attach a custom domain (a CNAME to <bucket>.t3.storage.dev). Newer accounts serve public content from t3.tigrisfiles.io — set public_url to whatever the bucket actually serves at.

Provisioning credentials is separate: flyctl storage create issues a bucket + keys, but that's a one-time setup step, not part of colophon publish. colophon only consumes the keys from the environment.

Git-based hosting (GitHub / GitLab / Codeberg Pages)

The git driver publishes by force-pushing the built tree as a single orphan commit to a nominated branch of a git remote. Whatever serves that branch — GitHub Pages, GitLab Pages, Codeberg Pages, a mirror, a self-hosted bare repo — then serves the site. It uses go-git (pure Go), so no git binary is required.

Because each publish is a fresh orphan commit, the branch always mirrors exactly the current build — there's no history to drift and no stale files to prune. It never touches your working tree: the build is staged in a temp repo and pushed from there.

Setting	Default	Purpose
`repo`	(required)	Remote URL (`https://…`, `git@host:owner/repo`, `ssh://…`) or local path.
`branch`	`main` (`gh-pages` for `github-pages`)	The branch to force-push.
`public_url`	(provider-derived)	The site's canonical URL. Auto-derived for known hosts (below); set it for a custom domain.
`commit_author` / `commit_email`	`colophon` / `colophon@users.noreply.github.com`	Author of the publish commit.
`commit_message`	`colophon: publish <timestamp>`	Commit message.

public_url is auto-derived from the remote for known hosts, so you usually don't set it:

Host	Repo	Derived URL
`github.com`	`me/blog`	`https://me.github.io/blog/`
`github.com`	`me/me.github.io`	`https://me.github.io/` (user/org site)
`gitlab.com`	`me/site`	`https://me.gitlab.io/site/`
`codeberg.org`	`me/pages`	`https://me.codeberg.page/`

Anything else (a self-hosted host, a custom domain via a CNAME) resolves no URL — set public_url explicitly.

GitHub Pages

publishers:
  - id: pages
    driver: github-pages              # branch defaults to gh-pages
    repo: "git@github.com:me/blog.git"   # SSH: pushes via your ssh-agent

environments:
  - name: production
    publish: [pages]
    allow_publish: true

In GitHub Actions, use an HTTPS remote and the workflow token instead of SSH:

  - id: pages
    driver: github-pages
    repo: "https://github.com/me/blog.git"   # GITHUB_TOKEN → push over HTTPS

Then point the repo's Settings → Pages at the gh-pages branch.

GitLab Pages

  - id: pages
    driver: git
    repo: "git@gitlab.com:me/site.git"
    branch: pages                      # match your .gitlab-ci.yml `pages` job source

GitLab serves Pages from a CI job, so the branch is whatever your pages: job builds from.

Codeberg Pages

  - id: pages
    driver: git
    repo: "git@codeberg.org:me/pages.git"
    branch: pages                      # Codeberg serves the `pages` branch

Any git remote

git is not GitHub-specific — push to a mirror, a self-hosted Forgejo/Gitea, or a local bare repo (handy for tests). Set public_url since the host is unknown:

  - id: mirror
    driver: git
    repo: "git@git.example.com:web/site.git"
    branch: deploy
    public_url: "https://www.example.com"

Authentication follows the remote scheme: an https:// remote uses a token from GITHUB_TOKEN / GH_TOKEN / GIT_TOKEN; an git@… / ssh:// remote uses your SSH agent; a local path needs neither.

Run any CLI: the `command` publisher

When no built-in driver fits, the command driver runs an arbitrary CLI against the built tree — so any deploy tool that takes a directory (surge, Netlify, Vercel, Wrangler, exe.dev, Azure SWA, rsync, scp, aws s3 sync, a bespoke script) is a publisher with no driver of its own.

colophon materialises the (routed) tree to a temp directory and runs your command there, with the directory as its working dir, the parent environment inherited (so the tool's own token var flows through), COLOPHON_* context injected, and CI=true. A non-zero exit fails the publish.

publishers:
  - id: surge
    driver: command
    command: ["surge", "{dir}", "myblog.surge.sh"]   # argv list — never a shell
    public_url: "https://myblog.surge.sh"            # SURGE_TOKEN comes from the env

  - id: rsync
    driver: command
    host: "deploy@example.com:/var/www/blog"          # any custom setting → {host}
    command: ["rsync", "-az", "--delete", "{dir}/", "{host}"]
    public_url: "https://www.example.com"

The command is an argv list executed directly — never through a shell, so there's no shell injection surface. For a one-liner with pipes or &&, make the shell explicit: ["sh", "-c", "aws s3 sync {dir} s3://bucket --cache-control max-age=3600"].

Interpolation. Every argument is interpolated with {placeholder} tokens drawn from your own publisher settings plus colophon runtime values (which win on a clash): {dir} / {output_dir} (the materialised tree, also the CWD), {manifest} (a JSON file classifying each path as page/asset/feed/… with content-type and size, written beside the tree so it isn't published unless you reference it), {public_url}, {id}, {file_count}, and any setting you declare ({host}, {domain}, {project}, …). Unknown placeholders error, so a typo fails loudly. Per-environment overrides vary any setting, so one command publisher can target staging vs production. The same values are exposed as COLOPHON_OUTPUT_DIR / COLOPHON_MANIFEST / COLOPHON_PUBLIC_URL / … env vars.

Secrets stay in the environment. colophon never injects a token into the command line — the child inherits the environment and the target tool reads its own $SURGE_TOKEN / $VERCEL_TOKEN there, matching colophon's env-only rule and the deploy-CLI best practice of keeping credentials out of argv (where they'd leak into process listings and shell history). The command runs with your privileges from your own config — same trust as a Makefile — and is gated behind --allow-publish like every deploy.

Per-environment overrides

An environment can override any publisher setting via overrides, keyed by publisher id — so one publisher definition serves several environments. For example, a single local publisher can write a distinct output directory per environment (handy for previewing a different theme side by side) without defining a publisher per env:

publishers:
  - id: local
    driver: local
    path: ./dist            # default output dir

environments:
  - name: dist
    publish: [local]        # → ./dist
  - name: text
    publish: [local]
    theme: minimal
    overrides:
      local:
        path: ./dist-text   # same publisher, a different dir for this env

Overrides also carry per-environment publisher tweaks like a Cloudflare Pages branch.

Redirects (aliases)

A post's aliases: (Authoring → Redirects) produce, at build time, a meta-refresh stub per old URL, a root _redirects file, and a root .nojekyll. How that becomes a redirect depends on the host:

Host	Result
Cloudflare Pages, Netlify, GitLab Pages	real 301 from `_redirects`
S3 static-website hosting	real 301 — the `s3` publisher sets the object redirect header on publish
Cloudflare R2, bare S3/MinIO, local	client-side meta-refresh stub (no in-bucket redirects)
GitHub Pages	client-side meta-refresh stub; the `.nojekyll` is what keeps `_search/` and the stubs from being stripped

So redirects work everywhere; hosts that support server-side rules get a true 301, the rest fall back to the (always-emitted) stub. colophon doctor warns about alias conflicts before you ship.

WebSub (real-time feeds)

WebSub lets subscribers get your new posts pushed instantly instead of polling. List one or more public hubs and colophon does both halves: it advertises them in every feed (<link rel="hub"> in RSS/Atom, a hubs entry in JSON Feed, plus rel="self"), and pings them after each successful publish so the hub re-fetches and fans out to subscribers.

sites:
  - id: main
    federation:
      websub:
        hubs:
          - https://pubsubhubbub.appspot.com/   # Google's public hub (or run your own)

The ping is best-effort: it runs only on a real deploy (a public base_url, not gated), and a hub that's slow or down only logs a WEBSUB … ping failed line — it never fails the publish. No hubs configured → nothing is advertised or pinged.

On-site search

colophon builds a static search index at build time — a sharded, content-addressed BM25 index a tiny browser reader queries client-side (no server, no service). Enable it per site with the search stanza:

sites:
  - id: main
    search:
      mode: lexical     # off (default) | lexical
      fuzzy: true       # opt-in typo tolerance (trigram + Levenshtein); roughly doubles the index

The string shorthand search: lexical still works (equivalent to mode: lexical, no fuzzy).

mode — lexical turns search on; omitted/off leaves it out entirely (no index, no box).
fuzzy — when on, a query token that finds no exact/prefix match falls back to typo-tolerant matching (so "wikilnk" finds "wikilinks"). It's opt-in because the trigram index it needs roughly doubles the index size — a cost a low-bandwidth search shouldn't pay unasked.

Results are prefix-matched by default ("wiki" → "wikilinks"), with query-aware highlighting and an occurrence count. The index + reader ship only when search is on, under _search/; a theme renders the box (the press, press-gazette and press-broadsheet themes include one). colophon search "<query>" queries the same engine from the CLI (always fuzzy), in text or --json.

For large sites, the index can be routed to an object store to keep it off a Pages-style file budget — see Routing the search index below (it also covers the CORS that a cross-origin index needs, set automatically by --create).

Routing assets to an object store

Shipping large or numerous images with a Pages/Workers deployment can exhaust its file budget. Routing sends matching paths to a different publisher — typically images to an object store — and rewrites their URLs to that store's public base.

sites:
  - id: main
    routing:
      - match: "**/assets/**"          # glob; ** crosses slashes, * does not
        publisher: r2                  # rewrite target inherited from the r2 publisher

publishers:
  - id: r2
    driver: cloudflare-r2
    bucket: "{env:R2_BUCKET:-my-assets}"
    account_id: "{env:CLOUDFLARE_ACCOUNT_ID}"
    public_url: "{env:R2_PUBLIC_URL:-}"  # optional; auto-discovered for R2 (see below)

environments:
  - name: production
    publish: [cf, r2]    # HTML to Pages, routed images to R2

How it works:

Build rewrites every routed image reference to the route's URL + path, so the HTML points at the object store.
Publish partitions the tree: the route's publisher (r2) receives only the matched files; every other publisher (cf) receives the unrouted remainder.

The route's URL is resolved as: the route's own base_url, else the target publisher's public_url, else — on publish, for Cloudflare R2 with a CLOUDFLARE_API_TOKEN — the bucket's auto-discovered URL (a connected custom domain, preferring the shortest, else the r2.dev managed URL). So publish --create provisions the bucket, enables r2.dev, and images serve from it with no URL in config; connect a custom domain later and the next publish prefers it automatically.

A rule is inactive until a URL resolves and its publisher is deploying in the environment. With nothing resolvable, routing is a no-op: images stay co-located and the whole tree goes to the default publisher — so local builds and previews work with no object store configured.

Routing the search index

The static search index (_search/**) can be routed to the object store too, to keep it off a Pages-style file budget:

routing:
  - match: "_search/**"
    publisher: r2

When routed, colophon points the browser reader at the store's URL automatically (the search_base it emits follows the route). Because the reader loads the index with fetch() and imports search.js as a module — neither CORS-exempt — the bucket must allow cross-origin GET; publish --create sets that policy for you (see Provisioning). Unrouted, the index stays on the same origin and no CORS is involved.

Generated from docs/publishing.md — edit it there.

Themes

2001-12-27T00:00:00Z

A theme turns colophon's page data into HTML. Themes are pongo2 templates (Jinja2/Django syntax) plus static assets. Three themes ship built in:

default — full-featured: hero banners, index thumbnails, and vendored highlight.js / KaTeX / Mermaid for code, maths and diagrams, plus self-hosted web fonts.
press — colophon.blog's brand theme. Literary-modern (Fraunces over Inter), light & dark, drifting glow, ink-blob title reveal, feed popouts. It inherits default (see base themes), so it reuses the same vendored libraries and fonts without shipping its own copy. The home-page lede under the title comes from the site's optional tagline: (presentational, distinct from the SEO description:); unset renders no lede.
minimal — plain, readable text. No JavaScript and no web fonts; rich blocks show as their raw source (the raw-block contract).

More themes (flux, signal, obsidian) live in contrib/themes/ and are installed by copying them into your project.

Selecting a theme

Set it on the site, and optionally override it per environment — handy for previewing a theme before promoting it to production:

sites:
  - id: main
    theme: default        # site default

environments:
  - name: production
    # inherits theme: default
  - name: text
    theme: minimal        # this environment builds with the minimal theme

Precedence: environment theme > site theme > default. Build or serve an environment to see its theme:

colophon build --env text     # builds public/ with the minimal theme
colophon serve                # serves every environment, each with its own theme

Inspecting and ejecting themes

colophon themes list            # default, minimal, press
colophon themes eject minimal   # copies the built-in into themes/minimal/ to edit
colophon themes eject default   # full default theme, incl. its vendored libraries

eject writes a built-in theme to themes/<name>/ in your project; the on-disk copy then overrides the built-in (use --force to overwrite an existing directory). It's the easiest way to start customising — eject, then edit only the files you care about. Ejecting an overlay theme (e.g. press) writes only its own files; the base theme's inherited assets stay in the binary and still resolve at build, so the eject stays small.

Supplying your own theme

Put files under themes/<name>/ in your project root and set theme: <name> (or eject one to start from). Files there override the built-in default per file, so you only write what you want to change:

themes/
  mytheme/
    page.html      # overrides the post template
    style.css      # overrides the stylesheet
    logo.svg       # a new static asset, copied to the output root

An unknown theme name with no themes/<name>/ directory falls back to the default theme.

Base themes (inheriting another theme)

A theme can inherit another theme's templates and static assets by declaring a base. For an on-disk theme this is automatic: any themes/<name>/ directory inherits default, so it only needs the files it changes (this is why dropping in a single style.css works). A built-in theme inherits explicitly via a one-line base file naming the base theme — the built-in press theme contains base → default, so it reuses the default's vendored libraries and fonts and supplies only its own page.html, index.html and style.css.

Resolution order, highest precedence first: your project's themes/<name>/ → the theme's own files → its base theme's files. The base marker is never copied to the output.

Community themes (`contrib/themes/`)

The colophon repo ships extra themes under contrib/themes/ that are not baked into the binary. To use one, copy it into your project and select it:

cp -r contrib/themes/flux myblog/themes/flux
# then, in colophon.yaml:  theme: flux

Because on-disk themes inherit default, a contrib theme only carries its own templates and style.css; the vendored libraries and fonts come from the built-in default at build time.

Theme files

File	Role
`page.html`	Renders a single entry (post or page). Required — the default for every page type.
`index.html`	Renders the site index (post list).
`<type>.html`	Optional. Renders entries of page type `<type>` (e.g. `project.html`); falls back to `page.html`. See Page types.
`favicon.svg`	Default site icon (override per-site with `favicon:` pointing at a project file).
`theme.yaml`	Optional. Theme metadata — a `description`, and `image.genai.system_prompt` (the house style for generated images). Not copied to the output.
anything else	Any non-`.html` file is copied verbatim to the output root (CSS, JS, fonts, images).

Static assets keep their relative path: themes/mytheme/vendor/app.js is written to /vendor/app.js and referenced as {{ base_path }}vendor/app.js.

Page types

Every entry has a type. By default it's derived from whether the entry has a date — a dated entry is a post (chronological: listed on the index, in feeds, on tag pages), a dateless one is a page (standing chrome: surfaced in the nav menu, not in the list/feeds). An author can override this with a type: in frontmatter (see Authoring → page types), including custom types like project.

As a theme author you don't have to do anything: every type renders with page.html unless you opt in. When you want a type to look different, you have two ways — pick whichever suits.

1. A dedicated template — add themes/<theme>/<type>.html. An entry of that type renders with it; any type without its own file falls back to page.html. The file is an ordinary single-entry template and receives the same variables as page.html (see the table below). For example, to give type: project entries a bespoke layout:

{# themes/mytheme/project.html — renders entries with `type: project` #}
<!doctype html>
<html lang="{{ lang }}">
<head>
  <meta charset="utf-8"><title>{{ meta_title }}</title>
  <link rel="stylesheet" href="{{ base_path }}style.css">{{ seo_head|safe }}
</head>
<body>
  <article class="project">
    <h1>{{ title }}</h1>
    {% if image %}<img class="project-shot" src="{{ image }}" alt="{{ title }}">{% endif %}
    {{ content|safe }}
    {% if tags %}<footer>{% for t in tags %}<a href="{{ t.url }}">{{ t.name }}</a> {% endfor %}</footer>{% endif %}
  </article>
</body>
</html>

2. Branch inside page.html — the page_type variable holds the resolved type, so one template can switch on it without a separate file:

{% if page_type == "project" %}
  <span class="badge">Project</span>
{% elif page_type == "page" %}
  {# a standing page — maybe hide the date/reading-time line #}
{% else %}
  <time>{{ date }}</time> · {{ read_time }} min
{% endif %}

Placement. A custom type is listed (post-like) by default; the built-in page is the only standing (nav) type. So type: page makes a dated entry standing (it appears in nav_pages, not in the index list or feeds), and type: post makes a dateless one listed. You don't render the nav/list yourself per type — the build routes entries into nav_pages (standing) vs pages (listed) for you; your per-type template only styles the single entry.

The templating language

Templates are pongo2 — Jinja2/Django syntax:

{{ value }} prints a value (HTML-escaped by default).
{{ value|safe }} prints pre-rendered HTML without escaping — required for content, feed_head and seo_head.
{% if x %}…{% elif y %}…{% else %}…{% endif %} and {% for item in list %}…{% endfor %}.
Filters chain with |, e.g. {{ title|default:site_title }}, {{ tags|length }}.
{# comment #} (keep it on one line — pongo2 rejects a newline inside {# … #}).

Always prefix internal links with {{ base_path }} ({{ base_path }}style.css, {{ base_path }}{{ p.url }}). base_path makes the theme work whether the site is served from / or a sub-path.

Template variables

`page.html` (a single post)

Variable	Description
`site_title`	The site title.
`title`, `date`, `description`	Post metadata (`date` is a date; may be empty).
`meta_title`	Pre-resolved `<title>` text (SEO title → title → site title).
`content`	The rendered post HTML. Output with `{{ content\|safe }}`.
`base_path`	URL prefix for internal links (always starts and ends with `/`).
`base_url`	Absolute site root, for canonical/social URLs.
`feed_head`	`<link rel="alternate">` feed-discovery tags. Output with `{{ feed_head\|safe }}`.
`seo_head`	Full SEO `<head>`: canonical, robots, Open Graph, Twitter, JSON-LD. `{{ seo_head\|safe }}`.
`analytics_head`	Analytics provider markup (statsfactory beacon and/or GA loader). Output once before `</body>` with `{{ analytics_head\|safe }}`. Empty when the site configures no analytics. See Analytics.
`glossary_head`	Glossary styles + decorator `<link>`/`<script>`. Output once before `</body>` with `{{ glossary_head\|safe }}`. Empty unless the page uses a glossary term. See Glossary.
`lang`	The page's BCP-47 language tag — put it on `<html lang="{{ lang }}">`.
`favicon`	Favicon filename, or empty.
`hero`	Hero banner URL (page-relative, or absolute when routed), or empty.
`hero_alt`, `hero_style`	Hero alt text, and a ready `object-fit`/`object-position` style string (may be empty). Use as `alt="{{ hero_alt }}"`{% if hero_style %} `style="{{ hero_style }}"`{% endif %}.
`image`, `image_abs`	Preview image href; absolute preview URL for `og:image`.
`image_alt`, `image_style`	Card-image alt text and `object-fit` style (the index list items carry `image_alt`/`image_style` too).
`tags`	List of `{name, url}` — linked tag chips. Prefix nothing; `url` is ready to use.
`category`	Primary category string (first category, else first tag, else empty).
`read_time`	Estimated reading time in whole minutes (integer).
`toc`	List of `{level, id, text}` headings, for a table of contents.
`page_type`	The resolved page type (`post`, `page`, or a custom value) — for branching within a shared template.
`draft`, `embargoed`, `embargo_until`	Preview-only flags for not-yet-public posts.
`has_code`, `has_math`, `has_mermaid`	True when the post uses that block type — load the matching library only when set.
`author_name`, `author_initials`, `author_bio`, `author_url`, `author_avatar`	Author h-card fields for the byline (empty when unset). `author_avatar` is a ready-to-use `src`: a file-path avatar is published to `/assets/<name>` and emitted root-anchored (or as the object-store URL when routed); `data:`/`http(s)://` and `gravatar` avatars resolve to a URL that passes through.
`has_audio`, `audio`, `audio_type`	True when the post has an audio reading (recorded or generated TTS); `audio` is its URL and `audio_type` its MIME. See Audio, video & downloads.
`audio_listen`, `audio_play`, `audio_pause`	Localised player UI strings (figcaption + play/pause aria-labels), in the page's language. Present only when `has_audio`.
`has_attachments`, `attachments`, `attachments_html`	Downloads. `attachments_html` is a ready-to-drop-in, no-JS block (`{{ attachments_html\|safe }}`); `attachments` is the structured list — `{url, label, description, name, type, type_label, size, bytes}` — if you'd rather build your own. `has_attachments` is the flag. See Audio, video & downloads.
`mentions_enabled`, `has_mentions`, `mentions`, `mentions_html`, `mentions_attrs`, `mentions_src`	Webmentions (replies/likes/reposts). What's populated depends on the site's `display.mode` — see Webmentions.
`has_syndication`, `syndication`, `syndication_html`	"Also posted on…" links from the post's `syndication:` frontmatter (absolute URLs). `syndication_html` is a no-JS drop-in of mf2 `u-syndication` links (`{{ syndication_html\|safe }}`, empty when none); `syndication` is the raw URL list to build your own.

`index.html` (the post list, and per-tag pages)

Variable	Description
`lang`, `site_title`, `base_path`, `base_url`, `feed_head`, `favicon`, `analytics_head`	As above. (Listing pages carry no prose, so no `glossary_head`.)
`heading`	Page heading — the site title on the home page, or `Tagged “<name>”` on a tag page.
`tagline`	The site's optional `tagline:`, for a hero lede under the title. Empty when unset — guard with `{% if tagline %}`.
`seo_head`	The listing's SEO `<head>` block (canonical, Open Graph/Twitter, JSON-LD). Emit with `{{ seo_head\|safe }}`.
`feeds`	List of `{label, href}` for subscribe links.
`pages`	List of posts: `{title, url, date, draft, embargoed, embargo_until, image, image_alt, image_style, audio, has_audio, has_attachments, tags, series}`. Prefix `url` with `base_path`. Use `has_audio`/`has_attachments` to flag entries with media (see below).

Enhancing rich blocks

colophon emits the raw-block markup; how to enhance it is entirely the theme's choice. The default theme loads vendored libraries from themes/default/vendor/, gated on the has_* flags so a page only pulls in what it uses:

{% if has_math %}
<link rel="stylesheet" href="{{ base_path }}vendor/katex/katex.min.css">
<script defer src="{{ base_path }}vendor/katex/katex.min.js"></script>
<script>/* render every .math element with katex */</script>
{% endif %}

Your theme is free to do something else with the same markup: load the libraries from a CDN, swap in a different highlighter, or — like the minimal theme — do nothing and let the raw text stand. The markup contract (<pre class="mermaid">, <span class="math …">, <pre><code class="language-…">, <div class="callout …">) does not change.

Audio, video & downloads

colophon resolves media; the theme decides how it looks. There are four touch-points.

1. Inline video/audio embeds. A body embed pointing at a media file (![](demo.mp4), ![](clip.mp3)) is rendered for you as <video class="post-video" controls …> or <audio class="post-inline-audio" controls …>. You only need to style them — make them responsive in your prose:

.prose .post-video { display: block; max-width: 100%; height: auto; }
.prose .post-inline-audio { display: block; width: 100%; }

2. The audio reading + player. When has_audio is set, a post has a podcast-style reading (recorded audio_file: or generated TTS). The build emits a shared, dependency-free player.js to the site root whenever any page has audio. Opt in with the markup contract — a container marked data-audioplayer with the source and localised labels, plus the script:

{% if has_audio %}
<figure class="post-audio" data-audioplayer data-src="{{ audio }}"
        data-label-play="{{ audio_play }}" data-label-pause="{{ audio_pause }}">
  <figcaption>{{ audio_listen }}</figcaption>
  <audio controls preload="none" src="{{ audio }}"></audio>   <!-- no-JS fallback -->
</figure>
{% endif %}
...
{% if has_audio %}<script defer src="{{ base_path }}player.js"></script>{% endif %}

player.js progressively enhances the <figure> into a play/pause control with a scrubbable waveform (a <src>.json peaks sidecar when present, else peaks decoded from the audio in-browser on first play and cached, else live Web Audio, else idle); with JS off the native <audio> still plays. Style the enhanced parts via .post-audio.ap-ready, .ap-toggle, .ap-wave, .ap-time — see any bundled theme's CSS.

The content of a generated reading is shaped by authoring hints — type-aware cues for code/diagrams/tables, and <notts>/<tts> to hide or force text. Those are an author concern, documented in Authoring content; a theme doesn't handle them.

3. The downloads block. The engine renders the whole Downloads list for you — a no-JS, semantic fragment with stable classes. Drop it in wherever you like (the bundled themes put it below the author box) and style it with CSS:

{{ attachments_html|safe }}   {# empty when the post has none, so no guard needed #}

It emits .post-downloads > .downloads-title + .downloads-list > .dl-item > a.dl, each row with .dl-ico (paperclip), .dl-main (.dl-label + optional .dl-desc) and .dl-meta (.dl-type badge + .dl-size). Style those classes to taste.

Prefer your own markup? Ignore the fragment and loop the structured attachments list instead — each entry has url, label, description, name, type, type_label, size, bytes:

{% if attachments %}<ul class="my-downloads">
  {% for f in attachments %}
  <li><a href="{{ f.url }}" download>{{ f.label }}</a>
      {% if f.description %}<p>{{ f.description }}</p>{% endif %}
      <span>{{ f.type_label }} · {{ f.size }}</span></li>
  {% endfor %}
</ul>{% endif %}

4. Listing markers. On index.html, each pages entry carries has_audio and has_attachments. The press and contrib themes show a small inert speaker / paperclip mark in the row's top-right corner so readers can spot posts with media at a glance — copy that pattern, or surface it however suits your design:

{% if p.has_audio or p.has_attachments %}<span class="post-flags">
  {% if p.has_audio %}<span class="pf" aria-label="Has an audio reading">…speaker svg…</span>{% endif %}
  {% if p.has_attachments %}<span class="pf" aria-label="Has downloadable files">…paperclip svg…</span>{% endif %}
</span>{% endif %}

Microformats2 (IndieWeb)

The bundled themes annotate posts with microformats2 — invisible class names that let other software (IndieWeb readers, Webmention senders, Bridgy) understand your content. It's pure markup: no JS, no config (the old microformats toggle was removed — it's always on). If you write your own theme, mirror the pattern so it stays parseable:

Post page: the post container is h-entry, with p-name (title), dt-published (the <time>), e-content (the rendered body), a u-url permalink ({{ permalink }} is the absolute URL), and a nested p-author h-card (p-name + u-url on the author, u-photo on the avatar).
Listing/index: the list is h-feed, each entry h-entry, the title link u-url p-name, the date dt-published.
Identity: author profile links carry rel="me".

When a theme splits the title/byline away from the body (e.g. a hero block), carry the stray properties into the h-entry root as hidden elements (<data class="p-name" value="…">, a hidden <time class="dt-published">) — see the signal/obsidian contrib themes.

Webmentions (responses)

Shipped. All bundled + contrib themes carry the responses block; configure federation.indieweb.webmention.display.mode (and run colophon webmention fetch) to populate it. See Show webmentions.

Webmentions are replies/likes/reposts from other sites, shown under a post. The engine never decides how they render — it only exposes the data, and the site picks a display.mode (federation.indieweb.webmention.display.mode). What the engine populates depends on that mode:

Variable	`live`	`asset`	`disabled`
`mentions_enabled`	`true` (unless the post sets `webmentions: false`)	`true` (unless opted out)	`false`
`has_mentions`	`false` — not known at build (JS fills the count)	accurate, from the synced list	`false`
`mentions`	empty — no build-time data	structured list (bake your own)	empty
`mentions_html`	empty	engine-rendered drop-in block	empty
`mentions_src`	the receiver's client-fetch endpoint	your published `_mentions/<post>.json`	unset

live — the browser fetches the receiver directly; most realtime, no rebuild, but no build-time data (so no count, no baking) and nothing for no-JS readers.
asset — the browser fetches your curated _mentions/ asset (refreshed out-of-band by webmention publish); because that list also exists at build, the engine fills mentions / mentions_html / has_mentions, so a theme may bake instead of relying on JS.
disabled — nothing is exposed or shipped, regardless of the per-post setting.

Always guard the block on mentions_enabled and keep it a sibling of the content element, never inside it (so it's never read aloud by the TTS reading — same rule as the author card/downloads).

Progressive-enhancement block (what press uses). Bake the asset-mode HTML server-side, then let the engine-emitted mentions.js refresh it (or, in live mode, populate it):

{% if mentions_enabled %}
<section class="responses" {{ mentions_attrs|safe }} aria-label="Responses">{{ mentions_html|safe }}</section>
{% endif %}
…
{% if mentions_enabled %}<script defer src="{{ base_path }}mentions.js"></script>{% endif %}

mentions_attrs is the engine-owned data-mentions* wiring (the source URL, plus data-mentions-live

target + blocklist in live mode) — drop it in and the same markup works across modes and reader drivers. With JS off (and asset mode) the baked mentions_html still shows; with JS on, mentions.js fetches and renders/refreshes.

Build your own from the structured list (asset mode), e.g. to restyle or split by type:

{% if has_mentions %}<section class="responses">
  {% for m in mentions %}
  <article class="response {{ m.type }} h-cite">
    {% if m.author.photo %}<img class="u-photo" src="{{ m.author.photo }}" alt="">{% endif %}
    <a class="p-author h-card u-url" href="{{ m.author.url }}">{{ m.author.name }}</a>
    {% if m.content %}<div class="p-content">{{ m.content }}</div>{% endif %}
    <a class="u-url" href="{{ m.url }}"><time class="dt-published">{{ m.published }}</time></a>
  </article>
  {% endfor %}
</section>{% endif %}

Each mentions item is {type (like|repost|reply|mention), author{name,url,photo}, url, content, published}. A no-JS / text theme (e.g. minimal) just uses asset mode + {{ mentions_html|safe }} and skips the script entirely.

Silo icons

Responses, the "Also posted on…" (u-syndication) links, and the author h-card links show a small brand icon when colophon recognises the source silo (Bluesky, Mastodon, GitHub, X, Reddit, Hacker News, Threads, Flickr, LinkedIn, Tumblr, GitLab — else a generic website globe). These are glyphs in a tiny webfont, silos.woff2, that the engine emits at the site root (when responses are active) and renders into <span class="silo">. A theme just declares the face and styles the span:

@font-face { font-family: "Colophon Silos"; src: url("silos.woff2") format("woff2"); font-display: swap; }
.silo { font-family: "Colophon Silos"; line-height: 1; }

The font is curated from Font Awesome (Brands + Solid) by contrib/scripts/silo-font — re-run it to add a network or change the set. Detection (host → silo) lives in internal/build/mentions.go + assets/mentions.js, kept in sync with the font's silos.json codepoints.

Analytics

colophon owns the analytics clients; a theme's only job is to include them. When a site configures a provider (statsfactory and/or Google Analytics — see analytics), the build writes that provider's loader to the site root — analytics-sf.js for the cookieless statsfactory beacon, analytics-ga.js for the Google Analytics loader — and exposes the matching <script> markup (with each page's dimensions) as the analytics_head variable.

A theme leverages both providers with one line, just before </body>:

{% if analytics_head %}{{ analytics_head|safe }}{% endif %}
</body>

The theme never names a provider: analytics_head already contains whichever loaders are enabled (statsfactory, GA, both, or — when the site configures none — nothing, leaving the line inert). Every built-in and contrib theme includes it; a JS-enabled custom theme should too.

Glossary

If the site ships a glossary.yaml (see authoring) and a page uses a term, the build publishes the data + a small decorator and exposes a glossary_head variable. A theme opts in with one line before </body> (right where the analytics line goes):

{% if glossary_head %}{{ glossary_head|safe }}{% endif %}
</body>

That's it — no per-theme CSS or JS needed:

The decorator and styles are engine-provided (glossary.js + glossary.css, written to the site root). The decorator wraps terms in <abbr class="gloss" data-gloss="…"> and shows an accessible pop-over on hover/focus (role="tooltip" + aria-describedby, Escape to dismiss).
The default styling adapts to your theme through the token contract: it uses --accent for the underline and --elevated/--text/--muted/--border + --serif/--sans for the dictionary-stanza card (with neutral fallbacks for token-less themes).
To customise the look, override .gloss and .gloss-tip (and .gloss-tip .gloss-term / .gloss-def) in your own stylesheet — e.g. press gives .gloss a light wavy underline.
A text-only / no-JS theme simply omits the line: terms stay plain readable text, so the page still works correctly without the decorator (this is what minimal does).

Build a theme — step by step

The fastest route is to start from a built-in and change only what you want. A new theme inherits default, so you can ship as little as one CSS file.

1. Create the theme directory in your project and point a build at it:

mkdir -p themes/mytheme

# colophon.yaml
sites:
  - id: main
    theme: mytheme          # or set it on one environment to preview first

2. Add a stylesheet. With nothing else present, mytheme uses the default templates and your CSS:

/* themes/mytheme/style.css */
body { font-family: Georgia, serif; max-width: 42rem; margin: 2rem auto; }

colophon serve            # open the printed URL; edits live-reload

That alone is a working theme. Everything below is optional, added when you want more control.

3. Take over the post template. Copy a built-in as a starting point, then edit it:

colophon themes eject default   # writes themes/default/ — copy what you need into mytheme/

A minimal themes/mytheme/page.html:

<!doctype html>
<html lang="{{ lang }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ meta_title }}</title>
  <link rel="stylesheet" href="{{ base_path }}style.css">
  {{ feed_head|safe }}
  {{ seo_head|safe }}
</head>
<body>
  <header><a href="{{ base_path }}">{{ site_title }}</a></header>
  <article>
    <h1>{{ title }}</h1>
    {% if date %}<time>{{ date }}</time>{% endif %}
    {% if read_time %}<span>· {{ read_time }} min read</span>{% endif %}
    {{ content|safe }}
    {% if tags %}<footer>{% for t in tags %}<a href="{{ t.url }}">{{ t.name }}</a> {% endfor %}</footer>{% endif %}
  </article>
</body>
</html>

4. Add the index (themes/mytheme/index.html) — the post list, the nav menu (standing pages like About), and per-tag pages:

<!doctype html>
<html lang="{{ lang }}">
<head><meta charset="utf-8"><title>{{ heading }}</title>
  <link rel="stylesheet" href="{{ base_path }}style.css">{{ feed_head|safe }}</head>
<body>
  {% if nav_pages %}<nav>{% for n in nav_pages %}<a href="{{ n.url }}">{{ n.title }}</a> {% endfor %}</nav>{% endif %}
  <h1>{{ heading }}</h1>
  <ul>
  {% for p in pages %}
    <li><a href="{{ base_path }}{{ p.url }}">{{ p.title }}</a>
        {% if p.date %}<small>{{ p.date }}</small>{% endif %}</li>
  {% endfor %}
  </ul>
</body>
</html>

nav_pages is the list of standing pages ({title, url}); pages is the chronological posts. The build sorts entries into these two buckets by page type — you just render them. (Add the same nav_pages block to page.html so the menu appears on entries too.)

5. (Optional) Tailor specific page types. Add a <type>.html template, or branch on the page_type variable inside page.html, to give a type its own look. See Page types. Skip this and every entry just uses page.html.

6. Decide how rich blocks render. Do nothing (raw text shows, like minimal), or enhance them with the has_* gates as shown in Enhancing rich blocks. The vendored libraries are inherited from default, so {{ base_path }}vendor/katex/… resolves with no extra files in your theme.

7. Add your own assets. Any non-.html file under themes/mytheme/ is copied to the output root, keeping its path: themes/mytheme/logo.svg → /logo.svg, referenced as {{ base_path }}logo.svg. Self-host fonts the same way and @import them from your CSS.

8. Build and ship:

colophon build --env production    # writes public/ with your theme

Checklist: every internal href/src starts with {{ base_path }}; content, feed_head and seo_head use |safe; {# comments #} stay on one line. To contribute a theme back, drop it in contrib/themes/ following the existing ones.

Generated from docs/themes.md — edit it there.

SEO & social metadata

2001-12-26T00:00:00Z

colophon gives every post correct search and social metadata by default — canonical URL, description, Open Graph + Twitter cards, schema.org JSON-LD, and robots — derived from the post's existing fields (title, description, tags, date, image, persona). An optional seo: frontmatter block overrides any of it, and is the precise target an authoring skill can fill in.

The `seo:` block

seo:
  title:        # <title> / og:title; ≤60 chars (else: the post title)
  description:  # meta description; 140–160 chars (else: description / excerpt)
  keywords: []  # focus terms (else: the post's tags)
  canonical:    # absolute URL override (else: base_url + slug)
  noindex: false# robots noindex (drafts & embargoed posts are noindex regardless)
  image:        # absolute social-image URL override (else: the `image` field)
  type:         # schema.org @type (default: BlogPosting)
  social:       # copy tuned for sharing, when it should differ from the search copy
    title:
    description:

Every field maps to exactly one piece of output, so what you set is what gets rendered.

What gets emitted (page `<head>`)

Output	Source
`<link rel="canonical">`	`seo.canonical` → `base_url` + slug
`<meta name="description">`	`seo.description` → `description`
`<meta name="robots">` noindex	`seo.noindex`, or any draft/embargoed post
`<meta name="keywords">`	`seo.keywords` → tags
Open Graph (`og:type/site_name/url/title/description/image/locale`)	`seo` → post fields; `og:title`/`description` prefer `seo.social.*`; `og:image` is `seo.image` → the `image` field → the `hero` cover art; `og:locale` from the page/site `lang`
`article:published_time` / `modified_time` / `tag` / `author`	the post date, tags, and persona
Twitter card (`summary_large_image` when an image exists, else `summary`)	the resolved image
`<script type="application/ld+json">` BlogPosting	headline, description, image, dates, keywords, `author` (persona → Person/Organization), `publisher` (site)

The JSON-LD author comes from the post's persona (persona: frontmatter, else the first configured persona): an individual persona renders as a Person, a brand persona as an Organization, with the persona's first h-card URL as author.url.

Defaults vs. overrides

You never need an seo: block — a plain post already produces all of the above from its title/description/tags/date/image/persona. Use seo: to:

give search a tighter title/description than the on-page ones,
write punchier social: copy for shares,
set an explicit canonical (e.g. a syndicated original),
noindex a page, or point image at an external social card.

Generating a good seo: block from the article is what the planned seo skill (skills.md) does.

Listing pages (home, tags, authors)

The home page and every generated listing — /tags/<tag>/ and /authors/<id>/ — also carry their own metadata: a canonical URL, description, website-flavoured Open Graph + Twitter cards, og:locale, and schema.org JSON-LD (a Blog for the home page, a CollectionPage for tag/author listings). These draw on two optional site-level fields:

sites:
  - id: main
    title: My Blog
    base_url: https://example.com
    description: One line that becomes the home page's meta/OG description.
    image: /assets/social.png   # default share image (absolute URL, or resolved against base_url)

Both are optional — unset simply omits the corresponding tags. description feeds the listing pages' <meta name="description"> and the JSON-LD; image is their default og:image/ twitter:image. Per-tag and per-author listings reuse the same description/image with their own heading as the title.

Generated from docs/seo.md — edit it there.

Image & audio generation

2001-12-25T00:00:00Z

colophon can generate images from a text prompt with an AI provider, anywhere it accepts an image: a post's hero:/image: frontmatter and Markdown body embeds. A generated image is cached on disk (and committed with your content), so it is produced once and then ships through the normal asset pipeline like any other image — including routing to an object store.

The feature is opt-in and off until you configure a provider.

Writing a `gen:` reference

Anywhere you'd put an image path, write gen: followed by the prompt.

In frontmatter:

---
title: On Patience
hero: "gen:a weathered fisherman waiting by a still lake at dawn, photoreal"
hero_alt: "A fisherman waiting by a calm lake at first light"
image: "gen:a minimalist book cover, muted teal palette"
---

In the body — wrap the prompt in <…> whenever it contains spaces (plain Markdown image syntax stops at the first space):

![A fisherman at dawn](<gen:a weathered fisherman by a still lake at dawn, photoreal>)

The alt text works exactly as for any image — write it for meaning, leave it empty for purely decorative banners.

Tuning a single image

Append query-style parameters to the prompt:

![cover](<gen:a quiet mountain road in fog?aspect=16:9>)

aspect (e.g. 1:1, 16:9, 9:16) is the common one; available parameters depend on the provider. Per-reference parameters override the defaults: in your config.

Reuse

Two references with the same prompt, model and parameters resolve to the same generated file — so a hero and an in-body embed sharing one prompt are generated once. Change the prompt, the model, or a parameter and you get a new image.

Configuration

Add a generation: block to colophon.yaml:

generation:
  image:
    provider: minimax            # which service to use (see table below)
    model: ""                    # optional — defaults per provider
    defaults:                    # optional — params applied to every prompt
      aspect: "16:9"
    output_dir: ""               # optional — default: content/assets/generated
    concurrency: 5               # optional — max images generated at once
    system_prompt: ""            # optional — house style; overrides the theme's (see below)
    # api_key: "{env:MINIMAX_API_KEY}"   # optional — see "API keys" below

Providers

`provider`	Default model	API key (environment variable)
`google`	`gemini-3.1-flash-image`	`GEMINI_API_KEY` (or `GOOGLE_API_KEY`)
`minimax`	`image-01`	`MINIMAX_API_KEY`
`openai`	`gpt-image-1`	`OPENAI_API_KEY`
`xai`	`grok-imagine-image-quality`	`XAI_API_KEY`
`together`	(set `model:`)	`TOGETHER_API_KEY`
`deepinfra`	(set `model:`)	`DEEPINFRA_API_KEY`
`custom`	(set `model:`)	set `api_key:`

custom targets any OpenAI-compatible images endpoint — also set base_url: and api_path: (e.g. /images/generations).

xai is Grok Imagine: xAI's OpenAI-compatible images endpoint. Set model: grok-imagine-image for the cheaper tier, and use aspect as usual (it is sent as xAI's aspect_ratio):

generation:
  image:
    provider: xai                # Grok Imagine — reads XAI_API_KEY
    defaults:
      aspect: "16:9"

API keys

Keys are read from the environment, never required in the file:

If you set api_key: (typically "{env:VAR}"), that value is used.
Otherwise colophon reads the provider's default environment variable from the table.

Either way the secret stays in your shell / .env / CI secrets, not in colophon.yaml.

House style (theme system prompt)

So you don't repeat the same look in every prompt, a house style is applied to every generated image — describe only the subject in each post and let the style come from the theme. The style is resolved in this order (first wins):

Per-reference ?systemprompt=… (below)
Site config — generation.image.system_prompt
Theme — image.genai.system_prompt in the theme's theme.yaml
Theme — the theme's description (a gentle fallback)

A theme sets its style in theme.yaml:

# themes/<name>/theme.yaml
description: "A clean editorial broadsheet theme."
image:
  genai:
    system_prompt: "editorial illustration, muted palette, soft depth, no text or lettering"

So hero: "gen:a lighthouse on a rocky coast" is generated in the theme's style with no extra wording in the post.

Per image, you can override or switch it off with the reserved systemprompt parameter:

?systemprompt=bold woodcut print, two-tone — use this style instead for this image
?systemprompt=none (or nil, or empty) — no house style for this image

![A lighthouse, in woodcut](<gen:a lighthouse on a rocky coast?systemprompt=bold woodcut, two-tone>)

The house style is part of the cache identity, so changing it (in the theme, the config, or a post) regenerates the affected images.

Audio readings (podcasts)

A post can carry an audio reading — generated by AI or a file you recorded yourself. Both become a player in the theme and a podcast <enclosure> in the feeds (RSS/Atom/JSON).

# pre-recorded — no AI, just attach a file (copied like a hero image)
audio_file: episode.mp3
# AI text-to-speech: omit to use the site default; set true/false to force per-post
audio: true
audio_voice: "English_Graceful_Lady"   # optional; else the author's/persona's voice, else the default

audio: is optional and three-state: omit it to follow the site default (read aloud when a speech provider is configured), or set true/false to force it for this post. audio_file wins if both are set. The reading voice resolves: post audio_voice → the author's (or persona's) voice: → the generation.speech default.

Configure the speech provider alongside the image one:

generation:
  speech:
    provider: minimax        # MiniMax t2a (more providers later)
    model: speech-2.6-hd
    voice: "English_Graceful_Lady"
    format: mp3              # default — the podcast-portable, now-patent-free choice

Authors/personas can carry a default voice (e.g. a cloned voice id):

# authors/sam.yaml
id: sam
name: Sam Avery
voice: "English_Graceful_Lady"

Themes get has_audio (bool) and audio (URL) to render a player or filter audio posts. The press theme shows a themed play/pause + scrubbable waveform player under the byline.

Waveform. The player derives the waveform from the audio itself, in the browser (Web Audio decodeAudioData), on first play — so generated readings cost a single TTS call, not a second one, and the computed peaks are cached in localStorage for instant redraws. For a recorded file you can still ship a precomputed episode.mp3.json of the form {"peaks":[0.1, 0.7, …]} (values 0–1) next to it — e.g. produced with ffmpeg/audiowaveform — and it renders instantly (paused, pre-play); a .wav is read directly at build. Until peaks exist, the player shows a resting shape or a live Web Audio visualiser (same-origin). When audio is routed cross-origin to an object store, the in-browser decode and any peaks fetch need CORS (a GET policy) on the bucket.

What gets read aloud

Blocks that don't translate to speech — code, math, tables, diagrams — aren't read verbatim (reading code or LaTeX aloud is gibberish). By default each is replaced with a short spoken cue ("Here, the post shows a Go code example."), the first cue adds "Visit the post to view it.", and a closing note is appended. Prose, headings, lists, blockquotes and callouts are read normally. Tune it per type:

generation:
  speech:
    transcript:
      blocks:                # cue | drop (silent) | keep (read the text)
        code: cue
        math_display: cue
        math_inline: drop
        table: cue
        diagram: cue
        inline_code: spell   # spell | keep | drop — "spell" voices symbols ("/etc" → "slash etc")
      wrap_up: true          # append the closing "visit the post" note

Acronyms in your glossary are read as their expansion so they're spoken as words, not letters — SSH → "Secure Shell", DDD → "Domain Driven Design". Only entries that look like acronym expansions qualify (an all-caps term with a short Title-Case definition whose letters spell the acronym), so an ordinary term like Rust is left alone. Turn it off with generation.speech.transcript.expand_acronyms: false.

For finer control, wrap content in the body:

<notts>…</notts> — shown on the page but never spoken (e.g. an aside, a pronunciation- hostile string).
<tts>…</tts> — always read verbatim, overriding the rules above (e.g. a short code snippet you do want spoken).

Both the injected speech (cues, hint, wrap-up, inline-code symbol names) and the player UI (the "Listen" caption and Play/Pause labels) are localised to the post's language (lang: frontmatter, else the site lang). English, Spanish, French, German, Italian and Mandarin ship built in; add or override any language with a project i18n/tts/replacements.json (same shape as the built-in table). A missing language or field falls back to English.

(No LLM is involved — cues are fixed text. An abstractive summary reading would need a text-LLM provider, which colophon doesn't have yet.)

Turning generation on/off

Three nested switches, all defaulting on, all behaving the same way: when off, no new assets of that kind are generated (no provider/API calls) even with --generate-ai, while everything already generated and committed keeps being served.

generation:
  enabled: true          # master — turns ALL generation off in one line
  image:
    enabled: true        # just images
  speech:
    enabled: true        # just audio (also the per-post audio default — see below)

generation.speech.enabled does double duty: it's the audio guard and the default for a post's audio: field. With a speech provider configured and speech enabled, every post reads aloud by default; a post opts out with audio: false. Without a provider, audio is off regardless (so speech effectively self-disables). Image generation has no per-post equivalent (images are explicit gen: references), so image.enabled is purely the guard.

Cleaning up the cache

colophon doctor reports cached generated assets that no content references any more (after an edited prompt, a changed style/model/voice, or a deleted post). colophon doctor --prune deletes them (and their sidecars).

Image post-processing

Some providers bake black letterbox bars into images. colophon removes them deterministically after generation (generation.image.postprocess.trim_letterbox, on by default): it crops solid black borders and re-frames to the requested aspect. It's a no-op on clean images and needs no configuration; set it to false to disable.

Generating images

Generation is a separate, explicit step — ordinary builds never call the provider:

colophon build --generate-ai

This produces only the images that aren't already cached, writing each into output_dir alongside a .json sidecar that records the prompt, provider, model, parameters and date. Already-cached images are reused with no API call. Generations run in parallel (up to concurrency, default 5 — lower it if your provider rate-limits you).

--generate-ai is also a flag on colophon publish, so a deploy can generate any still-uncached media first: colophon publish --env production --generate-ai. (The same applies to TTS audio readings — without the flag, an uncached reading is skipped with a build --generate-ai to create it hint.)

Then commit the generated files (content/assets/generated/ by default). The cache is part of your content: it makes builds reproducible and means a plain colophon build or colophon publish — including in CI — needs no API key and incurs no cost.

If a gen: reference has no cached image and you build without --generate-ai (or the provider errors, or no provider is configured), colophon warns and skips it — the build still succeeds, the image is just absent, exactly like any other missing asset. colophon doctor will not flag gen: references as broken.

Good to know

File format follows the provider. colophon names each file by its actual content (e.g. MiniMax returns JPEG, so you get .jpg), so the served Content-Type is always correct.
Changing the model or a default reuses nothing — it's a new prompt identity, so the old image stays in the cache until you delete it. There is no automatic pruning yet.
Provider model names change. Pin model: if you need stability; the defaults track each provider's current recommended image model.

Generated from docs/image-generation.md — edit it there.

Authors & personas

2001-12-24T00:00:00Z

colophon separates who is shown from how it's written:

An author is the byline readers see — an identity (a person, or a brand name).
A persona is a hidden writing voice the agent writes in — never shown, and shareable across authors.

A post carries up to two fields: author: (the byline) and persona: (the voice). The voice is purely an authoring aid; nothing about a persona is rendered.

Authors

Authors live in authors/<id>.yaml and supply the byline, author page, feed author and JSON-LD author:

id: ada                       # the id (defaults to the file stem, e.g. authors/ada.yaml)
name: "Ada Lovelace"          # the byline shown to readers
bio: "Writes about distributed systems."
avatar: assets/avatar.png     # see below — a file, a data:/https:// URL, or `gravatar`
urls: ["https://example.com"]
email: ada@example.com

The avatar may be:

a file under a content source (e.g. assets/avatar.png, resolved the same way a markdown image embed is — the first source that can open it wins). It is published once to /assets/<name> and the byline/topbar src is root-anchored, so it renders from every page depth (and is rewritten to the object-store URL when an assets/** route is active).
a data: URI (a self-contained inline image),
a fully-qualified http(s):// URL (a hosted image), or
Gravatar — avatar: gravatar uses this author's email:, or avatar: "gravatar:me@example.com" carries the address inline. It resolves to the author's Gravatar image. Append Gravatar options after a ? to override the defaults (s=200&d=mp), e.g. "gravatar:me@example.com?d=identicon&s=256".

data:, http(s):// and resolved gravatar avatars pass through untouched; a file path that no source can open is warned about (no broken src is emitted).

A post names one with author: ada. If a post sets no author:, the first configured author is the default; with no authors at all, the byline is "Anonymous" (a post without an author still builds — it's just unattributed).

colophon authors               # list bylines (alias: colophon author)
colophon author show ada       # one author's full h-card
colophon authors --json        # machine-readable (for a skill/agent)

Personas (the writing voice)

Personas live in personas/<id>.yaml and are only a voice — a style/character the agent writes in, plus the references it may draw on:

id: technical
name: "Senior engineer"        # a human label (not shown)
style:
  guide: "Plain, precise, technical. Short sentences. No hype. Senior-engineer perspective."
  references:
    - "https://example.com/glossary"

The same persona can be used by different authors — Ada and Grace can both publish in the technical voice under their own bylines. A persona's corpus is every post written in it, regardless of author, so the voice stays consistent and the exemplar pool grows.

colophon persona list            # id, label, and whether a style guide is set
colophon persona list --json     # machine-readable (for a skill/agent)

Write-as context

colophon does not generate prose. It emits context and the calling agent does the writing. persona context returns a voice's style guide and references plus the most relevant exemplars drawn from the posts written in that voice:

colophon persona context technical --topic "raft leader election"
colophon persona context technical --topic "raft" --tag distributed --top-k 5 --json

With --topic, exemplars are ranked by relevance (a pure-Go BM25 over the persona's posts — no embeddings, no API key). Without a topic, the most recent posts are returned.
--tag (repeatable) narrows the corpus to exemplars carrying that tag.
--top-k sets how many exemplars to emit (default 3).
The persona id is optional when there is a single persona (or one named default).

Finding where to write & what exists

Two commands round out the authoring toolbox (both take --json):

colophon sources               # where each source's content lives + how a post is marked live
colophon posts                 # existing entries: slug, title, type, author, persona, tags
colophon posts --tag go --author ada   # filter, e.g. to find cross-reference targets

Creating & previewing

colophon new post|page validates the author and persona, derives a unique pinned slug, writes a frontmatter skeleton to the right source, and reports the disk path and URL — then a person or an agent fills the body (colophon never generates prose):

colophon new post "Raft leader election" --author ada --persona technical --tag distributed
# wrote:  content/posts/raft-leader-election.md
# slug:   posts/raft-leader-election
# url:    /posts/raft-leader-election/   (preview: colophon serve)

--author / --persona are validated against authors/*.yaml / personas/*.yaml (errors list the valid ids); both are optional.
the slug derives from the title and is made unique — --unique=hash (default) appends a short id on a collision, --unique=counter appends -2; --slug sets it explicitly.
--in <source> chooses the source to write into; --print emits to stdout instead of writing.

Preview, and jump straight to a page:

colophon serve --open=latest     # opens the newest post in the browser
colophon serve --open=sitemap    # also: home | atom | rss | json | robots | <slug>

serve also prints the home/latest/sitemap/feed URLs at startup, so an agent can read them without a browser.

This is the core of the agent write-as flow: an agent picks a voice (persona) for style and an author for the byline, fetches the write-as context, drafts in that voice, previews, and publishes — all through the CLI, with deploy secrets resolved server-side and never passed to the agent.

Retrieval is built in memory on each call (zero state). A persisted/semantic index is a future option; the command shape stays the same.

Generated from docs/personas.md — edit it there.

Syndication (POSSE)

2001-12-23T00:00:00Z

POSSE — Publish on your Own Site, Syndicate Elsewhere — keeps the canonical copy of a post on your blog and pushes copies to social accounts ("silos") that link back. colophon does this with colophon syndicate: it walks your published posts, sends each to the configured syndicators, and records the result in a committed ledger so re-runs never double-post. The recorded silo URLs render on the post as u-syndication "Also posted on…" chips, each with the silo's brand icon and network name (e.g. "Bluesky") — the same silo icons used by responses.

This page is the full reference; the how-to guides are quick per-silo recipes.

How it works

colophon publish   --env production --allow-publish   # 1. canonical post goes live first
colophon syndicate --env production --allow-publish    # 2. push copies to the silos, record the ledger

Publish first. Syndication links back to the canonical URL, and some drivers (Bridgy) fetch the live page — so the post must be deployed before you syndicate.
syndicate gathers eligible posts (type post, not draft, not opted out), works out each one's targets, and for every (post, target) not already in the ledger, calls the driver.
Each driver returns the silo URL, which is written to .colophon/syndication.json and, on the next build, rendered as a u-syndication link.

Editing a syndicated copy when the post changes

The ledger stores a content fingerprint (title, summary, custom syndication text, link, tags) alongside each silo URL. On a later run, if a post's content has changed, colophon brings the existing silo copy up to date rather than skipping it — but how depends on what the silo allows:

Mastodon edits the status in place (PUT), preserving its likes/replies/permalink. This happens automatically on any content change.
Bluesky can't edit a card in place — its AppView ignores record edits, so an edit is invisible. The only way to change a card is an atomic swap (delete + recreate at the same rkey): the card re-indexes and the permalink is kept, but it's a new record, so the post's likes/reposts/replies reset and the timestamp updates. Because that's lossy, automatic edit-on-change skips Bluesky with a note — it's only done on an explicit --resync (below).
Bridgy / command can't edit a published copy; their copies are left as-is with a note.
An entry with no recorded silo URL (e.g. an old Bridgy post) is skipped, not failed.
A post with an unchanged fingerprint is skipped — edits only fire on a real change.
Upgrade/backfill: a ledger written by an older colophon has no fingerprints. The first run after upgrading backfills the current fingerprint for each entry without editing anything (there's nothing to compare against), so only genuine changes after that trigger an edit. The run reports backfilled=N; commit the updated ledger.
--resync: a one-shot that brings every already-syndicated copy to the post's current content, ignoring fingerprints. Use it to catch up copies created/changed before adopting this feature — the backfill deliberately won't, since it can't tell which were stale. On --resync, Mastodon re-edits in place and Bluesky does the atomic swap (so its cards refresh, accepting the engagement reset). Reports updated=N.

It performs irreversible external actions (posting to real accounts), so it's fenced:

Only an environment's syndicate: targets ever fire — a preview/draft env that omits the key never posts.
A gated env (allow_publish: false, typically production) needs --allow-publish.
--dry-run shows exactly what would post and writes nothing.
If the ledger file is missing, a real run refuses to start (it would re-post your whole back catalogue) unless you pass --allow-publish to seed it.

The ledger — commit it

.colophon/syndication.json is authoritative: it's how colophon knows a post is already syndicated. Commit it to your repo. Without it, a fresh CI runner would treat every post as new and re-post everything. It maps post → driver → {url, syndicated_at}; encoding/json sorts keys so diffs stay clean.

.gitignore gotcha: to commit the ledger out of an otherwise-ignored .colophon/, ignore the directory's contents, not the directory — git can't re-include a file under a wholly-ignored dir:
/.colophon/*                       # build trees, caches
!/.colophon/syndication.json       # …but keep the ledger
/.colophon/ (trailing slash) followed by a ! negation silently fails — the ledger stays ignored. colophon init scaffolds the correct form.

Persisting the ledger in CI (commit it back)

The catch on GitHub Actions (or any CI): colophon syndicate writes the ledger in the runner, but that runner is thrown away. Unless the workflow commits the updated ledger back to the repo, the next run checks out the old ledger and re-posts everything. So a CI syndication step is two parts — syndicate, then commit back:

permissions:
  contents: write            # needed to push the ledger back
concurrency:
  group: deploy              # serialise: two overlapping runs must not both post before committing
jobs:
  deploy:
    steps:
      # … build + publish (the post must be live before you syndicate) …
      - name: Syndicate
        env:
          MASTODON_TOKEN: ${{ secrets.MASTODON_TOKEN }}
          BLUESKY_APP_PASSWORD: ${{ secrets.BLUESKY_APP_PASSWORD }}
        run: colophon syndicate --env production --allow-publish
      - name: Commit syndication ledger
        run: |
          git diff --quiet .colophon/syndication.json && exit 0
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .colophon/syndication.json
          git commit -m "chore(syndication): update ledger [skip ci]"
          git push

Three things make this safe:

contents: write — the default workflow is read-only; the commit-back needs write.
[skip ci] in the commit message — so pushing the ledger doesn't trigger the workflow again (it would self-terminate anyway once the ledger is current, but this avoids the extra run).
concurrency: — serialises runs, so two in-flight deploys can't each syndicate before either commits, which would double-post.

colophon init scaffolds these as commented steps in the Deploy workflow. (Alternative, not yet built: keeping the ledger in the asset store like the _mentions/ pipeline, avoiding commit-back — at the cost of versioning. Commit-back is the supported path today.)

Per-post controls (frontmatter)

Frontmatter	Effect
`syndicate: false`	Don't syndicate this post at all.
`syndicate: [bsky]`	Only these targets (a subset of the env's `syndicate:` list).
(omitted)	All of the environment's targets.
`syndicate_text: "…"`	A custom blurb for the silo copy (else the driver uses the title).
`syndication: [url, …]`	Manually-added "Also posted on…" URLs, shown alongside ledger ones.

Configuration shape

Syndicators are configured like sources/publishers — {id, driver, …settings} — under the site, and each environment lists the ids it may post to:

sites:
  - id: main
    federation:
      syndication:
        - { id: mastodon, driver: mastodon, instance: https://hachyderm.io, token: "{env:MASTODON_TOKEN}" }
        - { id: bsky,     driver: bluesky,  handle: me.bsky.social, app_password: "{env:BLUESKY_APP_PASSWORD}" }
environments:
  - name: production
    syndicate: [mastodon, bsky]   # preview/draft omit this → never syndicate

Secrets (tokens, app passwords) only come from the environment via {env:VAR} — never written as literals.

Scheduling

syndicate is idempotent (the ledger guards it), so it's safe to run after every publish, or on a cron. A typical CI step runs publish then syndicate for production.

Drivers

Four drivers, picked by driver:. All share the harness above (ledger, gating, --dry-run); they differ only in how the silo post is created and where the auth lives.

`command` — run any program (you own the integration)

For: any target without a built-in driver — a silo's CLI, a webhook, an internal system, a notifier. Maximum flexibility; colophon holds no silo credentials.

How: runs your program once per post. The post is passed as environment variables (COLOPHON_POST_URL, _TITLE, _SUMMARY, _TEXT, _TAGS, _KEY, _PUBLISHED) and as JSON on stdin. The first line of stdout is taken as the silo URL (print nothing for fire-and-forget); a non-zero exit is a failure. Post content is never interpolated into the command, so it can't inject shell.

federation:
  syndication:
    - { id: silo, driver: command, command: "./bin/post-to-silo" }

#!/usr/bin/env bash
# bin/post-to-silo — receives one post via env/stdin, prints the created URL
set -euo pipefail
curl -fsS -X POST https://silo.example/api/posts \
  -H "Authorization: Bearer $SILO_TOKEN" \
  --data-urlencode "text=${COLOPHON_POST_TITLE} ${COLOPHON_POST_URL}" | jq -r .url

`mastodon` — post to a Mastodon account you control

For: cross-posting to your own Mastodon (any instance). You hold the access token.

How: POST <instance>/api/v1/statuses with Authorization: Bearer <token>. The status text is the blurb (custom text, else the title) plus the canonical link; Mastodon auto-links it and renders a preview card. The status's url is recorded. Text is trimmed to 500 chars but the link is always preserved.

federation:
  syndication:
    - id: mastodon
      driver: mastodon
      instance: https://hachyderm.io
      token: "{env:MASTODON_TOKEN}"

Set up: on your instance, Preferences → Development → New application with the write:statuses scope; copy the access token into MASTODON_TOKEN.

`bluesky` — post to a Bluesky account you control

For: cross-posting to your own Bluesky. You hold an app password.

How: AT-proto — createSession (handle + app password) gets a token, then createRecord writes an app.bsky.feed.post with an external embed card linking back to the canonical post. Returns the https://bsky.app/profile/<handle>/post/<id> permalink. Text (custom or title) is capped at 300 characters; the link-back is the card.

federation:
  syndication:
    - id: bsky
      driver: bluesky
      handle: me.bsky.social
      app_password: "{env:BLUESKY_APP_PASSWORD}"
      # service: https://bsky.social   # optional; default

Set up: Settings → Privacy and security → App passwords → Add (don't use your main password); copy it into BLUESKY_APP_PASSWORD.

`bridgy` — let Bridgy post for you (no credentials in colophon)

For: cross-posting without colophon holding any silo tokens — Bridgy holds your account auth. Good when you'd rather not manage credentials, or you syndicate to several networks through one mechanism.

How: colophon sends Bridgy a publish webmention — source = your post, target = https://brid.gy/publish/<network>. Bridgy fetches your post's microformats2 (which colophon emits) and creates the silo post on your behalf, returning its URL. The post must be live (Bridgy fetches it), and you must have connected the account at brid.gy first.

federation:
  syndication:
    - { id: mast-via-bridgy, driver: bridgy, network: mastodon }
    - { id: bsky-via-bridgy, driver: bridgy, network: bluesky }

Set up: connect your silo account(s) at https://brid.gy and follow its instructions for your domain. No tokens go in colophon.

bridgy driver vs Bridgy Fed: different things. This driver is syndication (POSSE copies to accounts you have). Bridgy Fed makes your site itself followable from the fediverse (no silo account) — that's federation, configured under webmention, not here.

Choosing a driver

You want…	Use
Direct control, own the token, one account	`mastodon` / `bluesky`
No credentials in colophon; already use Bridgy; several networks	`bridgy`
A silo with no built-in driver, a webhook, or custom logic	`command`

You can mix them — list several syndicators and put their ids in the env's syndicate:.

Analytics & telemetry

2001-12-22T00:00:00Z

colophon has two separate, independent privacy-respecting surfaces. telemetry is the app; analytics is the site. Neither switch affects the other.

	Site analytics	App telemetry
Answers	"how is my blog doing?"	"how is colophon used?"
Owner	the site owner	the colophon maintainer
Surface	a web beacon in deployed pages	the binary reporting its own runs
Destination	the site owner's statsfactory	the maintainer's (release-baked) statsfactory
Config	`sites[].analytics` (per site)	`telemetry` (top level)
Switch	each provider's own config	`telemetry.enabled` (this only)

Both are off unless configured.

Site analytics (reader beacon)

Per-site, one block per provider — your data, your instance:

sites:
  - id: main
    analytics:
      statsfactory:                       # cookieless, DNT-respecting
        server_url: "{env:STATSFACTORY_SERVER_URL:-}"
        app_key: "{env:STATSFACTORY_APP_KEY:-}"
      google_analytics:                   # GA4 — sets cookies, brings its own consent duties
        measurement_id: "{env:GA_MEASUREMENT_ID:-}"

Each provider is independent and inert until configured. The statsfactory beacon is a ~2 KB dependency-free analytics-sf.js written once to the site root and referenced by every page. It:

sends page_view on load and page_engagement (active milliseconds, as the metric value) on hide/unload;
is cookieless (session id in sessionStorage, per tab);
honours Do-Not-Track / Global Privacy Control — sends nothing when either is set.

Its public per-page dimensions are post.slug, post.type, post.author, post.tags, plus page.path and referrer. The statsfactory ingest key is a public sf_live_ key, safe to embed in pages. The hidden persona is never sent to the beacon.

Google Analytics (GA4) ships its own loader asset, analytics-ga.js, which injects Google's gtag.js. Each provider's asset is written to the site root only when that provider is enabled — analytics-sf.js for statsfactory, analytics-ga.js for GA, both if both, nothing if neither.

Every built-in and contrib theme includes the beacon by rendering {{ analytics_head|safe }} before </body>; a JS-enabled custom theme should too (see themes).

Google Analytics sets cookies and carries consent obligations the cookieless beacon does not — enable it only if that fits your privacy posture.

Injecting site credentials

Values usually come from {env:VAR} placeholders. colophon loads two dot-env files from the project root before interpolation and never overrides a variable already set in the real environment:

real environment (e.g. CI secrets)  >  .env (local, gitignored)  >  .env.defaults (committed)

So: commit your statsfactory endpoint + public key in .env.defaults, override per-machine in a local .env, and override in CI via repository Variables/Secrets.

GitHub Actions — colophon init scaffolds .github/workflows/deploy.yml. Set under Settings → Secrets and variables → Actions:

Variables (public): STATSFACTORY_SERVER_URL, STATSFACTORY_APP_KEY — the ingest key is public, so a Variable (not a Secret) is right.
Secrets (private): deploy credentials — CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY.

App telemetry (colophon's own usage)

colophon build and colophon publish report colophon's own operation — never your content — to the maintainer, so usage is understood. It is anonymous (a distinct_id that is a SHA-256 hash cached at .colophon/telemetry.id; the raw value is never stored or sent), and fire-and-forget — it never blocks or fails a command, and colophon serve previews emit nothing.

Credentials default to values baked into the binary at release, so a released colophon reports by default (opt-out); a source/dev build has no baked creds and reports nothing. To build a release with telemetry:

go build -ldflags "\
  -X github.com/jmylchreest/colophon/internal/telemetry.DefaultServerURL=https://stats.example.com \
  -X github.com/jmylchreest/colophon/internal/telemetry.DefaultAppKey=sf_live_xxxxxxxx" \
  ./cmd/colophon

colophon's release workflow (.github/workflows/build-release.yml) bakes these from the repository's COLOPHON_TELEMETRY_* secrets/variables, alongside the version (from the git tag), so tagged binaries are versioned and report by default. A project may override the destination (e.g. to self-host the maintainer role) under telemetry.statsfactory.

Event model

statsfactory dimensions are arbitrary and defined at ingest time, so these compose into pivot and breakdown views.

Surface	Event	Value	Key dimensions	Answers
Site	`page_view`	—	`post.slug`, `post.type`, `post.tags`, `post.author`	most popular posts
Site	`page_engagement`	active ms	`post.slug`	engagement time per post
App	`build`	page count	`theme`, `env`	builds over time
App	`source_indexed`	doc count	`source.type`, `source.id`, `env`	document count × source type
App	`publish`	uploaded	`publisher.type`, `publisher.id`, `status`, `env`	published docs/executions × publisher type

Opting out — summary

App telemetry and site analytics are independent — each is disabled on its own:

App telemetry: telemetry.enabled: false, COLOPHON_TELEMETRY=off, or telemetry.statsfactory.enabled: false.
A site analytics provider: omit it, or set its enabled: false.
Readers opt out of the beacon automatically via Do-Not-Track / Global Privacy Control.

Generated from docs/analytics.md — edit it there.

Agent skills & prompt packs (design)

2001-12-21T00:00:00Z

Status: design. This describes the planned authoring skills and the prompts colophon would furnish them with. The contracts they target — the frontmatter schema (SEO, tags, persona) and the markdown.Document round-trip — already exist. The skills themselves are not built yet.

The model

colophon is the context provider; the agent (LLM) does the writing. A skill is a small, deterministic wrapper that:

gathers context — the article body, the persona's style guide + retrieved corpus exemplars, and the site's facts (title, base_url, existing tags),
furnishes a prompt pack — a system prompt with a best-practice rubric and the output schema,
forces structured output — the model returns a validated object (a frontmatter block or body fragment), never free text,
merges it back via markdown.Document so the body is byte-preserved and only the intended fields change.

The frontmatter schema is the contract: because every field has exactly one rendering effect, the model can see the consequence of everything it writes, and nothing it can't set affects the output.

Shared infrastructure

Piece	Role
Persona context (`colophon persona context`)	Emits the persona's style guide + top-K corpus exemplars (BM25/embedding retrieval). Every writing skill prepends it so output matches the author's voice.
Structured output	Each skill defines a JSON Schema; the runtime validates and re-prompts on mismatch.
`markdown.Document`	Parse → patch frontmatter/body → re-marshal, preserving the body and unrelated fields.
Surface	A CLI verb (`colophon <skill> <file>`) and the matching MCP tool, sharing one implementation.

Skill catalogue

Skill	Produces	Consumes
seo	the `seo:` block	body + tags + persona
draft	body from a brief/outline	brief + persona context
outline	a heading skeleton	topic + persona
expand	fills a section	surrounding body + persona
retitle	`title` + `slug` candidates	body
tag	`tags` suggestions	body + the site's existing tag vocabulary
social	`seo.social` + syndication copy	body + target network
alt-text	`![alt]` for images/embeds	the image + nearby text
summary	`description` / TL;DR	body

All are suggest-by-default: they write a block you review, never silently overwrite editorial fields. --apply patches in place.

Prompt pack: `seo`

The flagship, since its contract (seo.md) and templating now exist.

Inputs furnished

the rendered article text (HTML stripped),
the resolved page facts: site title, base_url + slug (→ canonical), date, existing tags,
persona style guide (so the title/description sound like the author, not generic SEO mush).

Output schema — the seo: object (title, description, keywords, canonical, noindex, image, type, social{title,description}). Forced via structured output.

System prompt (sketch)

You write SEO metadata for a blog post, in the author's voice (style guide below).
Return ONLY the seo object. Follow these rules:

- title: ≤60 characters. Front-load the primary keyword. Match the post's actual content
  and search intent. Voice = the author's, not clickbait.
- description: 140–160 characters. A genuine summary that earns the click; no teasing,
  no "in this post". Unique to this page.
- keywords: 4–8 focus terms a reader would actually search; no stuffing.
- social.title / social.description: only if a punchier share-optimised version helps;
  otherwise omit and the search copy is reused.
- canonical / noindex / image / type: set only when you have a specific reason; otherwise
  omit and colophon's defaults apply.

Never invent facts not in the article. Prefer the author's existing tags as keyword seeds.

Inputs block (sketch)

## Author style guide
{{ persona.style.guide }}

## Site
title: {{ site.title }}   url: {{ canonical }}   existing tags: {{ all_tags }}

## Article
{{ body_text }}

The model returns e.g.:

seo:
  title: "Rendering math, diagrams and code from one Markdown file"
  description: "How colophon turns a single note into a page with KaTeX, Mermaid and
    highlighted code — and degrades to readable text without JavaScript."
  keywords: [static site generator, markdown, katex, mermaid, progressive enhancement]
  social:
    title: "One Markdown file → math, diagrams, code"

colophon seo --apply post.md merges that under seo:, body untouched; the next build renders the canonical/OG/Twitter/JSON-LD from it.

Prompt pack: `draft` / `outline` / `expand`

The writing skills. Each prepends persona context so output is in-voice, and takes a brief or the surrounding body.

outline — input: a topic + angle. Output: a heading tree (##/###) with one-line intents per section. Rubric: match the persona's typical structure; no body prose yet.

draft — input: an outline (or brief) + persona context. Output: the markdown body. Rubric: the author's voice and formatting conventions (callouts, code fences, length); cite only what's in the references; leave [[wikilink]] placeholders for cross-links rather than inventing URLs.

expand — input: a section heading + the surrounding body. Output: that section's prose only. Rubric: continuity with the existing voice and tense; no repetition of nearby points.

Prompt pack: `tag`, `social`, `alt-text`, `summary`

tag — input: body + the site's existing tag vocabulary. Output: 3–6 tags, reusing existing tags where they fit (avoid near-duplicate taxonomy), only proposing new ones when warranted. This keeps tag pages (content.md) coherent.
social — input: body + target (Mastodon/Bluesky/X/LinkedIn). Output: seo.social plus a per-network post for syndicate. Rubric: each network's norms (length, hashtags, link placement) and the author's voice.
alt-text — input: an image + the paragraph around it. Output: concise, descriptive alt text (not "image of"), for accessibility and image SEO.
summary — input: body. Output: a description (and optionally a longer TL;DR callout).

Why this shape

One contract, many skills. Every skill writes into the same typed frontmatter the templates already render, so adding a skill never needs a templating change.
Voice-preserving. Persona context is the common prefix, so SEO copy, drafts and social posts all sound like the same author.
Reviewable & reversible. Structured output + markdown.Document round-trip means a skill patches exactly the fields it owns and nothing else; suggest-by-default keeps a human in the loop for editorial fields.

Generated from docs/skills.md — edit it there.

How-to guides

2001-12-20T00:00:00Z

Short, zero-to-published recipes. The design behind them is in ../design/federation.md and ../design/webmention.md.

Guide	Status
Federate via Bridgy Fed — be followable from Mastodon/Bluesky	works today (uses the mf2 + feeds colophon already emits)
Show webmentions — replies/likes on your posts	shipped (`colophon webmention fetch/publish` + display modes)
Syndicate with a command — POSSE to any target	shipped (the `command` driver)
Syndicate to Mastodon	shipped (native `mastodon` driver)
Syndicate to Bluesky	shipped (native `bluesky` driver)
Syndicate via Bridgy — no-credentials POSSE	shipped (`bridgy` driver)

Syndication ships in full: the harness (ledger, env/per-post gating, --dry-run) plus the command, mastodon, bluesky, and bridgy drivers. The complete reference (every driver, how each works, when to use which) is ../syndication.md.

Generated from docs/howto/README.md — edit it there.

How to federate via Bridgy Fed

2001-12-19T00:00:00Z

Status: works today. Bridgy Fed needs only microformats2 + a feed (and rel=me), all of which colophon already emits — no colophon code beyond what's shipped.

Bridgy Fed makes your site itself followable from Mastodon and Bluesky: people follow @yourdomain, your posts federate, and replies come back as webmentions — without you running an ActivityPub server or even having a Mastodon/Bluesky account.

Steps

Publish your site with colophon as usual. It already emits:
- h-entry/h-card/h-feed microformats2, an RSS/Atom/JSON feed, and rel="me" identity links. An author's rel="me" (all of their urls:) is emitted in the <head> of their posts and their author feed page (/authors/<id>/) — your IndieWeb identity URL is that author page, not the bare domain (the home page lists every author, so it carries no single identity).
Add a webmention endpoint pointing at Bridgy Fed so it can receive interactions for you:
```
federation:
  indieweb:
    webmention:
      receiver: https://fed.brid.gy/webmention   # emitted as <link rel="webmention"> on every page
```
colophon emits the <link rel="webmention"> discovery tag site-wide when receiver is set — no manual theme edit needed.
Enrol at https://fed.brid.gy and follow its current instructions for your domain (it verifies your site, then your handle becomes @yourdomain@yourdomain). Bridgy Fed's onboarding changes over time, so use its docs as the source of truth: https://fed.brid.gy/docs.
Done. Fediverse/Bluesky users can follow you; new posts federate from your feed; replies arrive at the webmention endpoint (see Show webmentions to display them).

Notes

This is federation, not syndication: there's no separate silo account — your site is the account. For posting copies to your own Mastodon/Bluesky accounts instead, see the syndication guides.
Forward-only is fine: you can be followable without displaying replies; add webmention display when you want the conversation on your page.

Generated from docs/howto/bridgy-fed.md — edit it there.

How to show webmentions (replies, likes, reposts)

2001-12-18T00:00:00Z

Status: shipped. The full flow works: the <link rel="webmention"> tag, rel=me, microformats2, webmention send, and the receive/display layer — webmention fetch/publish, the display.mode (live/asset/disabled), the themed responses block, and a committed glob blocklist with the colophon-moderate-mentions skill. See ../design/webmention.md.

Webmentions let other sites' replies/likes/reposts appear under your posts — "comments without a database." A static site can't receive POSTs, so a hosted receiver (webmention.io) collects them and colophon pulls them in at build/refresh time.

Steps

Sign in to webmention.io via IndieAuth, which needs rel="me" on the exact URL you sign in with, linking bidirectionally to a provider it can authenticate (GitHub is the easy path). colophon emits an author's rel="me" (all of their urls:) in the <head> of their posts and their author feed page, so:
- Sign in with your author feed page — https://example.com/authors/<your-id>/ — not the bare domain (the home page lists all authors, so it has no rel="me").
- Make the link bidirectional: set your GitHub profile's website field to that same author-page URL (colophon already emits rel="me" → your GitHub from your urls:).
webmention.io then gives you:
- a receiver endpoint: https://webmention.io/yourdomain/webmention
- an API token (for reading your mentions back).

Configure it (token via env, never in config):

federation:
  indieweb:
    webmention:
      receiver: https://webmention.io/yourdomain/webmention  # emitted as <link rel="webmention"> (shipped)
      driver: jf2                                            # reader driver (read API); planned
      display:
        mode: asset                                          # live | asset | disabled (planned)
# export WEBMENTION_IO_TOKEN=...   (CI secret)

Build — colophon emits <link rel="webmention"> site-wide today; the per-post responses block (and fetch/publish below) are the planned display layer.
Pull mentions in:
```
colophon webmention fetch        # writes _mentions/<post>.json (the display data)
colophon webmention publish      # pushes only _mentions/ to your asset host (R2), on its own schedule
```
JS-rendered themes fetch that asset live, so a scheduled webmention publish keeps responses fresh without rebuilding the site. (No-JS/text themes show them as of the last build.)
Send webmentions when you link to others, so you show up in their comments (shipped):
```
colophon webmention send --env production   # run AFTER publish; the source URLs must be live
```
It scans the built output's outbound links (per page's canonical URL), discovers each target's endpoint, and POSTs. A sent-cache (.colophon/cache/webmention-sent.json) makes re-runs send only new links and re-ping removed ones. --dry-run reports without sending.
(Optional) Social replies via Bridgy — connect your silo accounts at https://brid.gy; it backfeeds replies/likes from Mastodon/Bluesky to your webmention.io endpoint, so they appear the same way. No extra colophon config.

Notes

Self-hosting: webmention.io is open source, or use a JF2-compatible receiver — point source: at its API (driver: jf2).
Privacy/spam: drop spam with a committed glob blocklist at .colophon/webmention-block.yml (by domain/url/author/content/type), applied at fetch and shipped to the browser in live mode. The colophon-moderate-mentions skill helps distill spam into small rules. Treat displayed third-party content accordingly.

Generated from docs/howto/webmentions.md — edit it there.

How to syndicate with a command (POSSE, any target)

2001-12-17T00:00:00Z

Status: shipped. The syndication harness — the ledger, gating, --dry-run, and the command driver — works today. Native mastodon/bluesky drivers are planned (../design/federation.md); the command driver lets you wire up any target now.

POSSE = Publish on your Own Site, Syndicate Elsewhere. The command driver runs a program of your choice once per new post, so you can cross-post anywhere (a silo's CLI, a webhook, a notifier) without a built-in driver. colophon records each result in a committed ledger, so re-runs never double-post.

Steps

Write a command that posts one entry. colophon passes the post as environment variables (COLOPHON_POST_URL, _TITLE, _SUMMARY, _TEXT, _TAGS, _KEY, _PUBLISHED) and as JSON on stdin. Print the created URL as the first line of stdout (or print nothing for fire-and-forget). A non-zero exit is a failure.

#!/usr/bin/env bash
# bin/post-to-silo — receives one post via env, prints the silo URL
set -euo pipefail
id=$(curl -fsS -X POST https://silo.example/api/posts \
       -H "Authorization: Bearer $SILO_TOKEN" \
       --data-urlencode "text=${COLOPHON_POST_TITLE} ${COLOPHON_POST_URL}" | jq -r .url)
echo "$id"

Configure a syndicator (driver: command) and allow it on the env that should post:

sites:
  - id: main
    federation:
      syndication:
        - { id: silo, driver: command, command: "./bin/post-to-silo" }
environments:
  - name: production
    syndicate: [silo]      # only this env cross-posts; preview/draft omit it → never post

Preview, then post (run after publish, so the canonical URL is live):

colophon syndicate --env production --dry-run        # shows what would post, writes nothing
colophon syndicate --env production --allow-publish  # posts new entries, records the ledger

Commit the ledger (.colophon/syndication.json) — it's authoritative. Without it a fresh runner would re-post everything, so a real run refuses to start with no ledger unless you pass --allow-publish to seed it.

The recorded silo URLs render on each post as mf2 u-syndication "Also posted on…" links.

Notes

Safety: only an env's syndicate: targets fire; a gated env (allow_publish: false) needs --allow-publish; --dry-run never posts or writes. Post content is passed via env/stdin, never interpolated into the command, so it can't inject shell.
Per post: syndicate: false to skip one, syndicate: [silo] to choose targets, syndicate_text: for a custom blurb.
Secrets (like SILO_TOKEN) come from the environment, never the config.
Prefer a managed native account? The mastodon/bluesky drivers (planned) will hold the auth for you; until then command covers any target.

Generated from docs/howto/syndicate-command.md — edit it there.

How to syndicate to Mastodon (POSSE)

2001-12-16T00:00:00Z

Status: shipped. The mastodon driver, colophon syndicate, and the ledger work today.

POSSE = Publish on your Own Site, Syndicate Elsewhere: the post is canonical on your blog, and a copy is cross-posted to Mastodon linking back to it.

Steps

Have a Mastodon account on any instance (e.g. hachyderm.io).
Create an access token: on your instance, Preferences → Development → New application; give it the write:statuses (and write:media for images) scope; create it; copy the access token.
Export the token as a CI secret: export MASTODON_TOKEN=...

Configure a syndicator (driver: mastodon):

sites:
  - id: main
    federation:
      syndication:
        - id: mastodon
          driver: mastodon
          instance: https://hachyderm.io
          token: "{env:MASTODON_TOKEN}"   # never a literal
environments:
  - name: production
    syndicate: [mastodon]     # only this env cross-posts; preview/draft never do

Publish, then syndicate (syndicate runs after the canonical URL is live):
```
colophon publish  --env production --allow-publish
colophon syndicate --env production --allow-publish
```
The Mastodon post URL is recorded in the syndication ledger and shown as an "Also posted on…" (u-syndication) link on your post. Re-running is idempotent (the ledger prevents double-posting).

Notes

Commit the syndication ledger (.colophon/syndication.json) — it's authoritative; a fresh CI runner without it would re-post. syndicate refuses to run blind without it.
Per post: syndicate: [mastodon] to choose targets, syndicate: false to skip, syndicate_text: for a custom blurb. Long posts are truncated with a link back.
Replies/boosts on the Mastodon copy can flow back to your post via Bridgy backfeed — see Show webmentions.
No token to manage? Use driver: bridgy with network: mastodon instead (Bridgy holds the auth).

Generated from docs/howto/syndicate-mastodon.md — edit it there.

How to syndicate to Bluesky (POSSE)

2001-12-15T00:00:00Z

Status: shipped. The bluesky driver, colophon syndicate, and the ledger work today.

POSSE = Publish on your Own Site, Syndicate Elsewhere: the post is canonical on your blog, and a copy is cross-posted to Bluesky linking back to it.

Steps

Have a Bluesky account — note your handle (e.g. me.bsky.social).
Create an app password: Settings → Privacy and security → App passwords → Add (don't use your main password). Copy it.
Export it as a CI secret: export BLUESKY_APP_PASSWORD=...

Configure a syndicator (driver: bluesky):

sites:
  - id: main
    federation:
      syndication:
        - id: bluesky
          driver: bluesky
          handle: me.bsky.social
          app_password: "{env:BLUESKY_APP_PASSWORD}"   # never a literal
environments:
  - name: production
    syndicate: [bluesky]      # only this env cross-posts; preview/draft never do

Publish, then syndicate:
```
colophon publish  --env production --allow-publish
colophon syndicate --env production --allow-publish
```
colophon authenticates (handle + app password → AT-proto session), creates the post (with a link card back to the canonical), records the Bluesky URL in the ledger, and renders it as an "Also posted on…" (u-syndication) link. Idempotent via the ledger.

Notes

Bluesky's limit is 300 characters — long posts are truncated with a link back; set syndicate_text: per post for a custom blurb.
Commit the syndication ledger (.colophon/syndication.json); without it a fresh runner would re-post, so syndicate refuses to run blind.
Replies/likes/reposts on the Bluesky copy can flow back to your post via Bridgy backfeed — see Show webmentions.
Prefer not to manage credentials? Use driver: bridgy with network: bluesky.

Generated from docs/howto/syndicate-bluesky.md — edit it there.

CLI reference

2001-12-14T00:00:00Z

The complete command surface, one page per command. Everything below is emitted by the binary itself (colophon --help), so it always matches the release it was generated from.

colophon init — Scaffold a new colophon project
colophon new — Scaffold a new post (dated, chronological) (subcommands: post, page)
colophon build — Build the site into public/ (prints next pending embargo)
colophon next-build-time — Print the next pending publish_after timestamp (for CI scheduling)
colophon serve — Serve every environment locally with live reload
colophon publish — Build and deploy/mirror to publishers (gated)
colophon themes — List the built-in themes (subcommands: list, eject)
colophon authors — List authors (the bylines) (subcommands: list, show)
colophon persona — List personas (subcommands: list, context)
colophon sources — Show where content lives and how posts are marked publishable
colophon posts — List content entries (for editing and cross-referencing)
colophon search — Search content (lexical or semantic)
colophon skills — Show which agent harnesses are present and the install status of each skill (subcommands: detect, install, list, uninstall)
colophon webmention — Notify the sites your live posts link to (run after publish) (subcommands: send, fetch, publish)
colophon syndicate — Cross-post (POSSE) to the environment's configured syndicators
colophon doctor — Validate the project config and report problems
colophon env — List the environment variables this project uses

colophon --help

Usage: colophon <command> [flags]

A themed Markdown blog generator with pluggable publishers

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Commands:
  init [<dir>] [flags]
    Scaffold a new colophon project

  new post <title> [flags]
    Scaffold a new post (dated, chronological)

  new page <title> [flags]
    Scaffold a new standing page (nav menu, no date)

  build [flags]
    Build the site into public/ (prints next pending embargo)

  next-build-time [flags]
    Print the next pending publish_after timestamp (for CI scheduling)

  serve [flags]
    Serve every environment locally with live reload

  publish --env=ENV,... [flags]
    Build and deploy/mirror to publishers (gated)

  themes list
    List the built-in themes

  themes eject <name> [flags]
    Copy a built-in theme into themes/<name>/ to customise

  authors (author) list [flags]
    List authors (the bylines)

  authors (author) show <author> [flags]
    Show one author's full details

  persona (personas) list [flags]
    List personas

  persona (personas) context [<persona>] [flags]
    Emit style guide + top-K exemplars for AI-assisted writing

  sources (source) [flags]
    Show where content lives and how posts are marked publishable

  posts (post) [flags]
    List content entries (for editing and cross-referencing)

  search [<query>] [flags]
    Search content (lexical or semantic)

  skills detect [flags]
    Show which agent harnesses are present and the install status of each skill

  skills install [flags]
    Install/update the skills into detected harnesses (or --harness/--dir)

  skills list
    List the skills embedded in this binary

  skills uninstall [flags]
    Remove colophon-managed skills from detected harnesses (or --harness/--dir)

  webmention send [flags]
    Notify the sites your live posts link to (run after publish)

  webmention fetch [flags]
    Pull received mentions from the configured receiver into the local cache

  webmention publish [flags]
    Fetch mentions and deploy only _mentions/ (refresh responses without a full
    re-upload)

  syndicate [flags]
    Cross-post (POSSE) to the environment's configured syndicators

  doctor [flags]
    Validate the project config and report problems

  env [flags]
    List the environment variables this project uses

Run "colophon <command> --help" for more information on a command.

colophon init

2001-12-13T00:00:00Z

Scaffold a new colophon project

Usage: colophon init [<dir>] [flags]

Scaffold a new colophon project

Arguments:
  [<dir>]    Target directory

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --force      Overwrite an existing colophon.yaml

Generated from the binary's --help output by tools/gendocs.

colophon new

2001-12-12T00:00:00Z

Scaffold a new post or page (validated author/persona, unique slug)

Usage: colophon new <command> [flags]

Scaffold a new post or page (validated author/persona, unique slug)

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Commands:
  new post <title> [flags]
    Scaffold a new post (dated, chronological)

  new page <title> [flags]
    Scaffold a new standing page (nav menu, no date)

colophon new post

Usage: colophon new post <title> [flags]

Scaffold a new post (dated, chronological)

Arguments:
  <title>    Entry title

Flags:
  -h, --help              Show context-sensitive help.
      --version           Print version and exit

      --author=STRING     Byline author id (validated; default: first author /
                          Anonymous)
      --persona=STRING    Writing-voice persona id (validated; optional)
      --tag=TAG,...       Tags
      --slug=STRING       Explicit slug (else derived from the title and made
                          unique)
      --unique="hash"     Slug collision strategy: hash | counter
      --in=STRING         Source id to write into (default: the first source)
      --print             Print the file to stdout instead of writing it

colophon new page

Usage: colophon new page <title> [flags]

Scaffold a new standing page (nav menu, no date)

Arguments:
  <title>    Entry title

Flags:
  -h, --help              Show context-sensitive help.
      --version           Print version and exit

      --author=STRING     Byline author id (validated; default: first author /
                          Anonymous)
      --persona=STRING    Writing-voice persona id (validated; optional)
      --tag=TAG,...       Tags
      --slug=STRING       Explicit slug (else derived from the title and made
                          unique)
      --unique="hash"     Slug collision strategy: hash | counter
      --in=STRING         Source id to write into (default: the first source)
      --print             Print the file to stdout instead of writing it

Generated from the binary's --help output by tools/gendocs.

colophon build

2001-12-11T00:00:00Z

Build the site into public/ (prints next pending embargo)

Usage: colophon build [flags]

Build the site into public/ (prints next pending embargo)

Flags:
  -h, --help           Show context-sensitive help.
      --version        Print version and exit

      --env=STRING     Build a named environment (applies its overrides)
  -v, --verbose        Log each step (sources, files, feeds)
      --generate-ai    Generate uncached AI media (gen: images and TTS audio)
                       via the configured providers
      --regenerate     Force a fresh render of generated media even if cached
                       (re-voice audio / re-roll images); implies work only with
                       --generate-ai
      --no-backoff     Don't retry rate-limited generation; fail fast and warn
                       instead of backing off

Generated from the binary's --help output by tools/gendocs.

colophon next-build-time

2001-12-10T00:00:00Z

Print the next pending publish_after timestamp (for CI scheduling)

Usage: colophon next-build-time [flags]

Print the next pending publish_after timestamp (for CI scheduling)

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --json       Output JSON

Generated from the binary's --help output by tools/gendocs.

colophon serve

2001-12-09T00:00:00Z

Serve every environment locally with live reload

Usage: colophon serve [flags]

Serve every environment locally with live reload

Flags:
  -h, --help            Show context-sensitive help.
      --version         Print version and exit

      --addr=":8080"    Address to listen on
      --open=STRING     Open a target in the browser: latest | home | sitemap |
                        atom | rss | json | robots | <slug>
      --showcase        Inject a built-in /showcase/ page (embedded in the
                        binary, never written to content) demonstrating every
                        markdown/style feature in the active theme
  -v, --verbose         Log each rebuild and attach source locations

Generated from the binary's --help output by tools/gendocs.

colophon publish

2001-12-08T00:00:00Z

Build and deploy/mirror to publishers (gated)

Usage: colophon publish --env=ENV,... [flags]

Build and deploy/mirror to publishers (gated)

Flags:
  -h, --help             Show context-sensitive help.
      --version          Print version and exit

      --env=ENV,...      Environment to publish; repeat for several
      --allow-publish    Deploy environments that set allow_publish: false
      --create           Create the destination (e.g. a Pages project) if it
                         doesn't exist
      --generate-ai      Generate uncached AI media (gen: images and TTS audio)
                         via the configured providers before deploying
      --regenerate       Force a fresh render of generated media even if cached
                         (re-voice audio / re-roll images); needs --generate-ai
      --no-backoff       Don't retry rate-limited generation; fail fast and warn
                         instead of backing off
  -v, --verbose          Log each step (sources, files, publisher actions)

Generated from the binary's --help output by tools/gendocs.

colophon themes

2001-12-07T00:00:00Z

List built-in themes or eject one to customise

Usage: colophon themes <command> [flags]

List built-in themes or eject one to customise

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Commands:
  themes list
    List the built-in themes

  themes eject <name> [flags]
    Copy a built-in theme into themes/<name>/ to customise

colophon themes list

Usage: colophon themes list

List the built-in themes

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

colophon themes eject

Usage: colophon themes eject <name> [flags]

Copy a built-in theme into themes/<name>/ to customise

Arguments:
  <name>    Built-in theme to copy (e.g. default, minimal)

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --force      Overwrite an existing themes/<name>/ directory

Generated from the binary's --help output by tools/gendocs.

colophon authors

2001-12-06T00:00:00Z

List authors (the bylines) or show one

Usage: colophon authors (author) <command> [flags]

List authors (the bylines) or show one

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Commands:
  authors (author) list [flags]
    List authors (the bylines)

  authors (author) show <author> [flags]
    Show one author's full details

colophon authors list

Usage: colophon authors (author) list [flags]

List authors (the bylines)

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --json       Output JSON

colophon authors show

Usage: colophon authors (author) show <author> [flags]

Show one author's full details

Arguments:
  <author>    Author id

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --json       Output JSON

Generated from the binary's --help output by tools/gendocs.

colophon persona

2001-12-05T00:00:00Z

List writing voices or emit write-as context

Usage: colophon persona (personas) <command> [flags]

List writing voices or emit write-as context

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Commands:
  persona (personas) list [flags]
    List personas

  persona (personas) context [<persona>] [flags]
    Emit style guide + top-K exemplars for AI-assisted writing

colophon persona list

Usage: colophon persona (personas) list [flags]

List personas

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --json       Output JSON

colophon persona context

Usage: colophon persona (personas) context [<persona>] [flags]

Emit style guide + top-K exemplars for AI-assisted writing

Arguments:
  [<persona>]    Persona id (defaults to the only persona, or 'default')

Flags:
  -h, --help            Show context-sensitive help.
      --version         Print version and exit

      --topic=STRING    Topic/outline to retrieve exemplars for (ranked by
                        relevance)
      --tag=TAG,...     Only draw exemplars tagged with this tag; repeatable
      --top-k=3         Max number of exemplars to emit
      --length=INT      Per-exemplar character cap (0 = the default); ignored
                        with --full
      --full            Emit each exemplar's full body (still bounded by
                        --budget)
      --budget=10000    Total character budget across all exemplars
      --json            Output JSON

Generated from the binary's --help output by tools/gendocs.

colophon sources

2001-12-04T00:00:00Z

Show where content lives and how posts are marked publishable

Usage: colophon sources (source) [flags]

Show where content lives and how posts are marked publishable

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --json       Output JSON

Generated from the binary's --help output by tools/gendocs.

colophon posts

2001-12-03T00:00:00Z

List content entries (for editing and cross-referencing)

Usage: colophon posts (post) [flags]

List content entries (for editing and cross-referencing)

Flags:
  -h, --help              Show context-sensitive help.
      --version           Print version and exit

      --author=STRING     Only entries with this author id
      --persona=STRING    Only entries with this persona id
      --tag=TAG,...       Only entries carrying any of these tags
      --json              Output JSON

Generated from the binary's --help output by tools/gendocs.

colophon search

2001-12-02T00:00:00Z

Search content (lexical or semantic)

Usage: colophon search [<query>] [flags]

Search content (lexical or semantic)

Arguments:
  [<query>]    Search query

Flags:
  -h, --help        Show context-sensitive help.
      --version     Print version and exit

      --limit=20    Maximum results
      --json        Output JSON

Generated from the binary's --help output by tools/gendocs.

colophon skills

2001-12-01T00:00:00Z

Install colophon's authoring skills into a detected agent harness

Usage: colophon skills <command> [flags]

Install colophon's authoring skills into a detected agent harness

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Commands:
  skills detect [flags]
    Show which agent harnesses are present and the install status of each skill

  skills install [flags]
    Install/update the skills into detected harnesses (or --harness/--dir)

  skills list
    List the skills embedded in this binary

  skills uninstall [flags]
    Remove colophon-managed skills from detected harnesses (or --harness/--dir)

colophon skills detect

Usage: colophon skills detect [flags]

Show which agent harnesses are present and the install status of each skill

Flags:
  -h, --help          Show context-sensitive help.
      --version       Print version and exit

      --dir=STRING    Inspect a specific skills directory instead of detecting
                      harnesses

colophon skills install

Usage: colophon skills install [flags]

Install/update the skills into detected harnesses (or --harness/--dir)

Flags:
  -h, --help                   Show context-sensitive help.
      --version                Print version and exit

      --harness=HARNESS,...    Install only for these harness ids
                               (claude,codex,opencode,cursor,copilot,gemini)
      --dir=STRING             Install into a specific directory instead of
                               detected harnesses
      --all                    Install for every supported harness, detected or
                               not
      --claude="ask"           How to install for Claude Code:
                               ask|marketplace|files|skip
      --force                  Overwrite locally-modified or unmanaged skills
      --dry-run                Show what would change without writing

colophon skills list

Usage: colophon skills list

List the skills embedded in this binary

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

colophon skills uninstall

Usage: colophon skills uninstall [flags]

Remove colophon-managed skills from detected harnesses (or --harness/--dir)

Flags:
  -h, --help                   Show context-sensitive help.
      --version                Print version and exit

      --harness=HARNESS,...    Uninstall only for these harness ids
      --dir=STRING             Uninstall from a specific directory
      --all                    Consider every supported harness, detected or not
      --force                  Also remove locally-modified or unmanaged skills
      --dry-run                Show what would change without deleting

Generated from the binary's --help output by tools/gendocs.

colophon webmention

2001-11-30T00:00:00Z

Send webmentions to the sites your live posts link to (run after publish)

Usage: colophon webmention <command> [flags]

Send webmentions to the sites your live posts link to (run after publish)

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Commands:
  webmention send [flags]
    Notify the sites your live posts link to (run after publish)

  webmention fetch [flags]
    Pull received mentions from the configured receiver into the local cache

  webmention publish [flags]
    Fetch mentions and deploy only _mentions/ (refresh responses without a full
    re-upload)

colophon webmention send

Usage: colophon webmention send [flags]

Notify the sites your live posts link to (run after publish)

Flags:
  -h, --help                Show context-sensitive help.
      --version             Print version and exit

      --env="production"    Environment whose built output to scan
      --dry-run             Discover endpoints and report, but do not POST
  -v, --verbose             Log each link and endpoint

colophon webmention fetch

Usage: colophon webmention fetch [flags]

Pull received mentions from the configured receiver into the local cache

Flags:
  -h, --help             Show context-sensitive help.
      --version          Print version and exit

      --domain=STRING    Domain to fetch mentions for (default: the site
                         base_url host)
  -v, --verbose          Log each post that received mentions

colophon webmention publish

Usage: colophon webmention publish [flags]

Fetch mentions and deploy only _mentions/ (refresh responses without a full
re-upload)

Flags:
  -h, --help                Show context-sensitive help.
      --version             Print version and exit

      --env="production"    Environment to refresh mentions on
      --allow-publish       Deploy environments that set allow_publish: false
      --domain=STRING       Domain to fetch mentions for (default: the site
                            base_url host)
  -v, --verbose             Log each step

Generated from the binary's --help output by tools/gendocs.

colophon syndicate

2001-11-29T00:00:00Z

Cross-post (POSSE) to the environment's configured syndicators

Usage: colophon syndicate [flags]

Cross-post (POSSE) to the environment's configured syndicators

Flags:
  -h, --help                Show context-sensitive help.
      --version             Print version and exit

      --env="production"    Environment to syndicate
      --allow-publish       Run for environments gated by allow_publish:
                            false (required to post)
      --dry-run             Show what would be syndicated; post nothing,
                            write no ledger
      --resync              Re-edit every already-syndicated copy to the post's
                            current content, ignoring fingerprints (one-shot;
                            only drivers that can edit, e.g. mastodon/bluesky)
  -v, --verbose             Log each candidate

Generated from the binary's --help output by tools/gendocs.

colophon doctor

2001-11-28T00:00:00Z

Validate the project config and report problems

Usage: colophon doctor [flags]

Validate the project config and report problems

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

      --prune      Delete orphaned generated assets (AI images/audio no content
                   references)

Generated from the binary's --help output by tools/gendocs.

colophon env

2001-11-27T00:00:00Z

List the environment variables this project uses

Usage: colophon env [flags]

List the environment variables this project uses

Flags:
  -h, --help       Show context-sensitive help.
      --version    Print version and exit

Generated from the binary's --help output by tools/gendocs.

Configuration reference

2001-11-26T00:00:00Z

Every colophon.yaml option in one annotated file. It is not a starter config — colophon init writes a lean one — but the single place where every knob, default and shape is written down. Copy the bits you need.

Any string value may interpolate the environment with {env:VAR} or {env:VAR:-fallback}; deploy secrets are always read from the environment and never stored in the file.

# ─────────────────────────────────────────────────────────────────────────────
# colophon.yaml — ANNOTATED REFERENCE
#
# Not a starter config (`colophon init` writes a lean one). This shows every
# option in one place, with a few list entries set side-by-side so the shapes
# are clear. Copy the bits you need.
#
# Markers used in comments below:
#   [required]   must be set; no default
#   [optional]   may be omitted; the shown value is the default
#   [inherits]   only meaningful inside a profile — when omitted, the value is
#                taken from that modality's default block (see "generation")
#
# Any string may interpolate the environment: {env:VAR} or {env:VAR:-fallback}.
# Deploy secrets are read from the environment at build time and are NEVER stored
# in this file.
# ─────────────────────────────────────────────────────────────────────────────


# ═══ sites ═══════════════════════════════════════════════════════════════════
# One or more sites built from the shared content. Most projects have exactly one.
sites:
  - id: main                                   # [required] stable id, used in URLs/serve paths
    title: "My Blog"                           # [required]
    base_url: "{env:SITE_URL:-http://localhost:8080}"  # [required] canonical origin
    theme: press                               # [optional] default: the bundled "default" theme
    lang: en                                   # [optional] site default BCP-47 language (default "en")
    languages: [en, es]                        # [optional] enable multi-language posts. A file
                                               #   <slug>.es.md is the Spanish translation of <slug>.md,
                                               #   published at /es/<slug>/, linked by hreflang + a
                                               #   theme language selector. The default lang stays at /.
    personas: [default]                        # [optional] writing voices available to the agent
    federation:
      feeds: [rss, atom, json]                 # [optional] default: none; emit at least one
    # search accepts a bare mode string OR a block. Bare form: `search: lexical`.
    search:
      mode: lexical                            # [optional] lexical | semantic | off (default off)
      fuzzy: true                              # [optional] default false; trigram+Levenshtein typo tolerance
    # Derived slide decks. Site defaults; a post overrides either key in its `slides:`
    # frontmatter (shallow/by-key — a key replaces this value, omitted keys inherit).
    slides:
      enabled: false                           # [optional] default off; a post opts in with `slides: true`
      split: [h2]                              # [optional] slide boundaries (a list). default: every heading.
                                               #   targets: h1..h6, hr, splitslide, image, table, code,
                                               #   math, diagram, audio, video, text:<match>
    # Reader analytics for THIS site. One block per provider; inert until configured.
    analytics:
      statsfactory:
        server_url: "{env:STATSFACTORY_SERVER_URL:-}"
        app_key: "{env:STATSFACTORY_APP_KEY:-}"
      # google_analytics:                      # GA4 — sets cookies, brings its own consent duties
      #   measurement_id: "{env:GA_MEASUREMENT_ID:-}"
    # Routing rewrites matching output paths to a publisher's object store instead of
    # shipping them with the page host (which has a file/size budget). Inert until that
    # publisher resolves a public URL, so local builds keep assets co-located.
    routing:
      - match: "**assets/**"                   # co-located post assets + the root /assets tree
        publisher: r2
      - match: "_search/**"                    # keep the search index off the page-host budget
        publisher: r2


# ═══ sources ═════════════════════════════════════════════════════════════════
# Where content comes from. Driver selects the implementation; the rest is
# driver-specific. List several and their content is merged.
sources:
  - id: content                                # [required]
    driver: md-dir                             # [required] a plain Markdown directory
    path: ./content
  - id: vault                                  # a second source, merged with the first
    driver: obsidian
    vault: "{env:OBSIDIAN_VAULT:-}"            # vault root; empty → contributes nothing
    path: "{env:BLOG_PATH:-}"                  # vault-relative folder(s); empty → whole vault
    tag: "{env:BLOG_TAGS:-}"                   # publish by tag(s); empty → use publish_required
    publish_required: false


# ═══ publishers ══════════════════════════════════════════════════════════════
# Pure mechanism: HOW to deploy. WHAT/WHERE is decided by environments below.
# Deploy credentials always come from the environment, never from these fields.
publishers:
  - id: local                                  # offline build target, for diffing output
    driver: local
    path: ./dist
  - id: cf                                     # HTML/static host
    driver: cloudflare-pages
    project: "{env:CF_PAGES_PROJECT:-my-blog}"
    account_id: "{env:CLOUDFLARE_ACCOUNT_ID}"
  - id: r2                                     # S3-compatible object store (routing target above)
    driver: cloudflare-r2
    bucket: "{env:R2_BUCKET:-my-blog-assets}"
    account_id: "{env:CLOUDFLARE_ACCOUNT_ID}"
    public_url: "{env:R2_PUBLIC_URL:-}"        # empty → auto-discovered on publish


# ═══ environments ════════════════════════════════════════════════════════════
# Named build+deploy profiles. No name is privileged. An environment picks
# publishers, toggles drafts, and may override a few site fields + select
# generation profiles (see "generation"). Build/deploy with --env <name>.
environments:
  - name: production                           # [required]
    publish: [cf, r2]                          # [required] publisher ids to deploy to
    allow_publish: false                       # [optional] default true; false → require --allow-publish
    base_url: "{env:BASE_URL:-}"               # [optional] override the site base_url here
    overrides:                                 # [optional] per-publisher Settings overrides, keyed by id
      cf: { branch: main }

  - name: preview
    publish: [cf, r2]
    include_drafts: true                       # [optional] default false
    title: "My Blog (preview)"                 # [optional] override the site title
    image_profile: draft                       # [optional] use the cheap image profile in this env
    speech_profile: minimax                    # [optional] use the minimax voice profile in this env
    slides:                                    # [optional] override the site slides defaults here
      enabled: true                            #   e.g. decks on in preview, off in production
    overrides:
      cf: { branch: preview }

  - name: dist                                 # local copy; ungated, no creds
    publish: [local]
    include_drafts: true

  - name: text                                 # preview an alternate theme before promoting it
    publish: [local]
    include_drafts: true
    theme: minimal                             # [optional] override the site theme
    overrides:
      local: { path: ./dist-text }


# ═══ generation ══════════════════════════════════════════════════════════════
# Optional AI media generation. Two modalities: image (satisfies `gen:` refs) and
# speech (reads posts with `audio: true`). Empty → the feature is off.
#
# Each modality has a DEFAULT block plus named PROFILES (a map). A profile inherits
# every field from the default block and overrides only what it lists. The default
# block is the implicit profile named "default".
#
# Which profile renders a given asset (narrowest scope wins):
#
#   default block
#     ◀ environment   speech_profile: / image_profile:
#       ◀ post         audio_profile: / image_profile:   (frontmatter)
#         ◀ per-ref    <gen:hero?profile=…>              (image refs only)
#           ◀ post scalar overrides (audio_voice, …)
#
# Merge rule: scalars REPLACE, maps DEEP-MERGE (e.g. image `defaults`). Voice/model
# ids are provider-specific, so a profile that changes provider should also set them.
generation:
  enabled: true                                # [optional] default true; master off-switch for all AI gen

  # ── images ──────────────────────────────────────────────────────────────────
  image:
    enabled: true                              # [optional] default true; per-modality switch
    provider: google                           # [required] google|minimax|openai|xai|together|deepinfra|custom
    model: gemini-3.1-flash-image              # [optional] default: the provider profile's default model
    api_key: "{env:GEMINI_API_KEY}"            # [optional] default: the provider's env var (kept out of config)
    base_url: ""                               # [optional] override endpoint (required for `custom`)
    api_path: ""                               # [optional] override request path (OpenAI-compatible hosts)
    output_dir: content/assets/generated       # [optional] default shown; cache + sidecars (committed)
    concurrency: 5                             # [optional] default 5; max parallel generations
    reuse: exact                               # [optional] exact (re-render on provider/model change) | content
    system_prompt: ""                          # [optional] house style; default: the theme's
    defaults:                                  # [optional] tuning params applied to every request
      aspect: "16:9"
    postprocess:
      trim_letterbox: true                     # [optional] default true; strip baked-in letterbox bars
    profiles:                                  # [optional] named alternates; each inherits the block above
      draft:                                   # cheap/fast — e.g. for previews
        provider: together                     # [inherits] all other fields from the default image block
        model: black-forest-labs/FLUX.1-schnell
      poster:                                  # premium — e.g. for hero art
        provider: openai
        model: gpt-image-1
        defaults: { quality: high }            # deep-merged over the default `defaults` (aspect kept)

  # ── speech ──────────────────────────────────────────────────────────────────
  speech:
    enabled: true                              # [optional] default true; also the per-post `audio:` default
    provider: elevenlabs                       # [required] elevenlabs | minimax
    voice: "{env:ELEVENLABS_VOICE:-Ee4WTXzxagFpoj4PUkHV}"  # [optional] default: provider profile's default voice
    model: ""                                  # [optional] default: provider profile's default model
    api_key: "{env:ELEVENLABS_API_KEY}"        # [optional] default: the provider's env var
    base_url: ""                               # [optional] override endpoint
    api_path: ""                               # [optional] override request path
    output_dir: content/assets/generated       # [optional] default shown; clip cache + sidecars
    concurrency: 5                             # [optional] default 5; max parallel clips
    reuse: exact                               # [optional] exact | content (reuse a prior voice's reading)
    pronunciation_dict: en_GB                  # [optional] built-in name (contrib/pronunciation: en_GB, es_ES) or a
                                               #   YAML path. A naked ref applies to the SITE DEFAULT LANGUAGE only;
                                               #   per-language: {en: en_GB, es: es_ES} (BCP-47 keys, es-MX → es).
                                               #   A language with no entry gets no dictionary.
    transcript:                                # [optional] how post content becomes spoken text
      wrap_up: true                            # [optional] default true; append a closing "visit the post" note
      expand_acronyms: true                    # [optional] default true; read SSH as "Secure Shell"
      blocks:                                  # [optional] per block-type handling: cue|drop|keep|spell
        code: cue                              #   (defaults: code/table/diagram/math_display→cue,
        table: cue                             #    math_inline→drop, inline_code→spell, else keep)
    profiles:                                  # [optional] named alternates; each inherits the block above
      minimax:                                 # a different provider needs its own voice
        provider: minimax
        voice: English_Trustworth_Man          # [inherits] pronunciation_dict/transcript/etc from default
      narrator-fast:                           # same provider, faster/cheaper model + a different voice
        model: eleven_turbo_v2_5
        voice: "{env:ELEVENLABS_NARRATOR_VOICE:-}"


# ═══ telemetry ═══════════════════════════════════════════════════════════════
# The colophon APP's own anonymous usage reporting (build/source/publisher TYPES —
# never your content), separate from the site analytics above. Governs only itself.
telemetry:
  enabled: true                                # [optional] default true; false (or COLOPHON_TELEMETRY=off) disables


# ═══ per-post selection (frontmatter — NOT this file) ════════════════════════
# Posts pick a profile in their own frontmatter. The selector keys are identical
# at every scope (config block, environment, frontmatter): speech_profile /
# image_profile.
#
#   ---
#   audio: true
#   speech_profile: minimax          # → generation.speech.profiles.minimax
#   audio_voice: SomeOtherVoiceId    # still wins over the profile's voice
#   image_profile: poster            # → generation.image.profiles.poster (hero + inline images)
#   ---
#
#   ![cover](<gen:hero?profile=poster>)   # per-image override, beats image_profile

Generated from docs/colophon.reference.yaml — edit it there.

Changelog

2001-11-25T00:00:00Z

User-facing changes by release. Each entry points at the guide where the feature is documented in full (or where it should be, when end-user docs catch up).

v0.0.33

xAI (Grok Imagine) image provider. generation.image.provider: xai targets xAI's OpenAI-compatible images endpoint (default model grok-imagine-image-quality, key from XAI_API_KEY); the standard aspect param is sent as xAI's aspect_ratio. See Image & audio generation → Providers.
Per-language pronunciation dictionaries. pronunciation_dict: now takes either a naked ref (en_GB) — which applies to the site default language only, no longer to every language — or a map keyed by BCP-47 tag: pronunciation_dict: {en: en_GB, es: es_ES} (matched exact-then-base, so es-MX uses es). A language with no entry gets no dictionary, so an English dict never rewrites a Spanish reading. A Spanish dict (es_ES) is now bundled alongside en_GB. For ElevenLabs, each dict syncs as its own account dictionary (named colophon:<site>/<ref>); a previously-synced dictionary is adopted when its rules are unchanged. Spoken block cues ("Here, the post shows a code example…") now also follow a translation's language detected from its <slug>.<lang>.md filename, not just an explicit frontmatter lang:. Default-language readings keep their content identity — no re-render.
Multi-language posts (translations). Set languages: on the site and add a <slug>.<lang>.md file (e.g. my-post.es.md) to publish a translation at /<lang>/<slug>/, linked to the original by its base slug. Translations emit hreflang alternates (with x-default); the press theme shows a language selector in the post header and a dismissible "available in your language" banner driven by the browser's preference (no forced redirect). Each translation is a normal post with its own reading/feeds/glossary/deck. See Authoring content → Multiple languages.
Slide decks: styled by the site theme + a fuller reader. A published deck now links the active theme's stylesheet and renders content in the theme's .prose class, so quotes, callouts, code, tables and Mermaid look like the site and theme authors can style .slide* themselves. The reader gained: touch/swipe navigation and on-screen prev/next buttons; on-screen presenter and fullscreen toggles (so they work without a keyboard); a light/dark toggle (reusing the theme's data-theme); a large mobile presenter card (the notes fill the phone as a teleprompter while the slide shows on the big screen); and an autocue that auto-scrolls each slide's notes and auto-advances at a reading pace — adjustable live with +/− (or the on-screen slower/faster buttons), shown in the counter and remembered. Stop with Back, restart from the button. Mermaid renders lazily per slide (it can't measure a hidden one), and a <base href> fixes co-located asset URLs in the deck.

v0.0.32

Slide decks render the post's content well by default. A cover slide (title, description, author avatar/initials) leads; content is paginated to fit (blocks pack onto a slide, overflow spills to a continuation slide, an oversized code block truncates with a link back to the post, images/video scale to fit); math, diagrams and syntax highlighting hydrate from the published /vendor assets; media (images/audio/video) stays on the slide, not in notes; callouts and pull-quotes are styled. Prose paragraphs become the presenter notes (shown in presenter mode); everything else is on the slide — never both. The Downloads-box Slides link opens the deck in a new tab. New keys: Enter plays/pauses the slide's media, Esc closes the deck (back to the post).
Slide decks (slides:). A post can be projected into a themed slide deck, published at …/<slug>/slides/, linked from the Downloads box, and flagged with a marker in the listing. It's derived from the post (headings → slides/bullets, prose → speaker notes, other blocks on the slide); with JS it's a keyboard/swipe presentation (presenter notes, fullscreen), and with JS off the same file reads as a long-form document. Configure with slides.enabled/slides.split at the site level and override per post (slides: true/false or the block form; overwrites by key). Split targets: h1–h6, hr, splitslide, image/table/code/math/diagram/audio/ video, and text:<match>. Inline markers <splitslide>, <slide>…</slide> and <noslide>… </noslide> mirror the <tts> family. See Authoring content → Slide decks.

v0.0.31

Bluesky: refresh a card via an atomic swap, only on --resync. The earlier "edit in place" for Bluesky (v0.0.29) was a no-op — Bluesky's AppView ignores record edits, so the public card never changed. colophon now refreshes a Bluesky card by atomically deleting and recreating the record at the same rkey (applyWrites): the card re-indexes and the permalink is kept, but it's a new record so likes/reposts/replies reset and the timestamp updates. Because that's lossy, it runs only on --resync (an explicit opt-in); automatic edit-on-change now skips Bluesky with a note. Mastodon still edits in place automatically (no engagement loss).
Accessibility: a sweep toward WCAG AAA (see the wcag-aaa-compliance decision). Engine: code blocks, Mermaid and display math are keyboard-focusable scroll regions (2.1.1); tables are wrapped in a focusable .table-scroll (semantics preserved, no display:block hack); GFM task-list checkboxes get an aria-label. Press theme: a visible keyboard-focus indicator on every control; role="img" on the audio/attachment markers; the home page hero moved inside <main>; and a contrast pass — --muted/--faint raised to ≥7:1 and a new --link token (≥7:1) for accent text (links, inline code, badges, pull-quote attribution), with --accent kept for decoration.

v0.0.30

Syndication card descriptions fall back to a body excerpt. A post with no description: frontmatter previously syndicated with an empty summary (a bare Bluesky/Mastodon card); build.Entries now mirrors the page — explicit description:, else a short excerpt of the rendered body. Also fixes empty descriptions in feeds for such posts. Re-run colophon syndicate --resync once to push the new descriptions onto existing cards.
syndicate skips, doesn't fail, an entry with no recorded silo URL. Ledger entries posted via a fire-and-forget driver (Bridgy) have no editable handle; --resync now reports them as skipped with a note instead of erroring the whole run non-zero.

v0.0.29

Content & themes

Pull-quotes / epigraphs. A > [!quote] Attribution callout renders as a semantic <figure class="pullquote"> with the attribution as <figcaption> (omit it for an unattributed quote); the press theme styles it as a large display quote. See Authoring content → Markdown support.
Glossary reference links. A glossary.yaml term can carry reference links, rendered as citation-style superscripts after the decorated term. See Authoring content → Glossary.
Tables are styled in press (borders, padding, header underline, row hover, horizontal scroll on narrow screens). goldmark's per-column alignment is preserved.
colophon serve --showcase. Injects a built-in /showcase/ page — embedded in the binary, never written to your content — that renders every content feature (callouts, pull-quotes, tables, maths, diagrams, image/video/audio embeds, attachments, glossary, post hero/description/ audio reading) in your active theme, with the source shown alongside. The single living reference for what a theme can style.

Generation (image & speech)

Named generation profiles. Each modality (generation.image / generation.speech) takes a default block plus named profiles: that inherit it and override only what they set. Select a profile with the same key at every scope — image_profile: / speech_profile: — on an environment, in a post's frontmatter, or per image via <gen:…?profile=name>; narrowest scope wins. Fully annotated in colophon.reference.yaml; see also Image & audio generation.
Provider-agnostic pronunciation dictionaries with a bundled British dict (pronunciation_dict: en_GB): ipa: entries render to each provider's phoneme mechanism (ElevenLabs uploads a versioned dictionary; MiniMax sends them inline), say: entries substitute as plain text.
Speech: headings pause. A heading now ends on a sentence boundary in the spoken reading, so it no longer runs into the next paragraph.
Speech: the waveform is precomputed from the same audio (no second render) and shipped as the <audio>.json sidecar; the in-browser visualiser is the fallback when it's absent.

Syndication (POSSE)

Edit a syndicated copy when the post changes. The ledger stores a content fingerprint; a later run edits the existing silo copy in place (Mastodon PUT, Bluesky putRecord) instead of skipping — keeping its permalink/likes/replies. Bridgy/command can't edit and are left as-is. The first run after upgrading backfills fingerprints without editing.
colophon syndicate --resync. A one-shot that re-edits every already-syndicated copy to its current content, ignoring fingerprints — to catch up copies created before the feature. Entries with no recorded silo URL (e.g. posted via Bridgy) are skipped, not failed.

See Syndication (POSSE) → Editing a syndicated copy.

Generated from docs/changelog.md — edit it there.

Internals & design notes

2001-11-24T00:00:00Z

Design documents for the systems behind colophon. These are engineering notes, kept for the curious and for contributors — they explain why the subsystems are shaped the way they are, and can run ahead of or behind the shipped code.

Static search — the fully static lexical engine, index shards and the browser reader.
Federation — IndieWeb, POSSE and syndication architecture.
Webmention — sending, receiving, caching and displaying mentions.
Obsidian — publishing straight from a vault.

The roadmap itself lives in the repository: docs/PLAN.md.

Design: federation (IndieWeb, POSSE, syndication)

2001-11-23T00:00:00Z

Internal design note

This is an engineering design document — it describes how colophon works inside, and may run ahead of (or behind) the shipped code. The user-facing guides are the source of truth for behaviour.

Status: substrate shipped, the rest designed. Built: microformats2 (h-entry/h-card/h-feed), rel=me, RSS/Atom/JSON feeds, and aliases redirects (URL stability). Webmention is detailed in webmention.md; this is the umbrella — the posture, the reader/syndicator abstractions, POSSE, WebSub, and the cross-cutting concerns. No POSSE/WebSub code yet. Relates to PLAN §10.

Goal: let a colophon blog participate fully in the social web — be followable, get replies/likes back, and cross-post to silos — while staying a static site. The organising principle:

Posture: be a source, not a server

Be a…	Means	Static-friendly?
Source	emit mf2 + feeds + discovery tags; thin post-publish "notify"/"syndicate" steps; let hosted relays do the rest	✅ our lane
Server	run an ActivityPub/AT actor, a receiving endpoint, a reader/Microsub	❌ needs a live server

Bridgy Fed needs only mf2 + webmention, or an RSS/Atom feed — both already emitted — to make the site itself followable from Mastodon/Bluesky. The heavy lifting is offloaded to relays; we emit standards and run small, decoupled senders.

Abstractions only where mechanisms diverge

colophon has two existing naming conventions, split by shape: a list of pluggable destinations uses driver (publishers and sources are both {id, driver, settings}), while the single external service that produces/serves content for a modality uses provider (generation). Federation adds one of each — and matches the convention by shape:

1. Reader (`driver`) — reading webmentions back

There's one receiver per site, so this is the single-service shape → provider, like generation. The Webmention spec standardises receiving, not reading back, so each receiver exposes a different read API. Model it as a Reader interface + a driver (default jf2, plus a custom JF2 source for self-hosted/compatible), selected by config. Bridgy backfeed arrives in your receiver as ordinary webmentions, so it is read through the same Reader driver — not a separate abstraction. Full detail in webmention.md.

2. Syndicator (`driver`) — POSSE (cross-posting)

POSSE matters for anyone with real social reach, and Bridgy-only POSSE gives little control over per-network formatting/threading and depends on a relay — so native syndication is a first-class goal. Each target is a Syndicator:

type Syndicator interface { Syndicate(ctx, post) (siloURL string, err error) }
//   drivers (mirroring publishers/sources):
//     mastodon – instance URL + access token (env); statuses + media API
//     bluesky  – handle + app password (env); AT-proto createRecord + blob upload
//     bridgy   – POST to brid.gy/publish, parse the created silo URL from the response
//     command  – run a user command; stdout = silo URL (empty stdout = fire-and-forget webhook)

Syndication is the list-of-destinations shape, so it uses driver — each entry is { id, driver, …settings }, byte-for-byte the PublisherConfig/SourceConfig shape (id + driver + remaining settings). driver is the concrete mechanism (mastodon, bluesky, bridgy, command); id is an arbitrary handle that syndicate: (per-env and per-post) references. A site may configure many syndicators (the syndication: list, like the publishers list). Bridgy is simply driver: bridgy with a network: field naming the silo to publish to — not a special "via". (It really is "publishers, for silos.")

The command syndicator is also a publish webhook. Mirroring the command publisher, it runs a user-defined command per post with interpolated placeholders ({url} canonical, {title}, {slug}, {summary}, {tags}, {json} = path to a metadata file) and env for secrets — so a user can wire up anything (a Discord/Slack webhook, a Bluesky CLI, an n8n flow, a custom API). The trick that makes it both a syndicator and a generic hook: stdout is the silo URL. If the command prints a URL it's recorded in the ledger and rendered as u-syndication; if it prints nothing it's a fire-and-forget publish webhook. No separate hook system — the same interface covers both.

Bridgy is transparent for receiving, a syndicator for sending — the two are unrelated:

Backfeed (inbound): Bridgy polls your connected silo accounts on its own schedule and POSTs webmentions to your receiver. colophon never calls Bridgy; replies arrive and are read via the Reader. Not modeled — it's invisible infrastructure.
POSSE (outbound): Bridgy does not auto-publish new posts, so automating cross-posting means colophon actively POSTs to brid.gy/publish and records the returned silo URL. That's an explicit syndication action → it's a Syndicator driver like the rest. (Implementation note: Bridgy verifies the source links to brid.gy/publish/{silo}, so the driver includes that link in the source it sends.)

So driver: bridgy buys cross-posting to networks without a native driver (or without holding their API tokens yourself), at the cost of per-network formatting control.

Syndication runs as a post-publish step (colophon syndicate, after the canonical URL is live), decoupled and best-effort like webmention send — it never blocks the deploy.

The syndication ledger — and why it's different from the webmention cache

A sidecar ledger (e.g. .colophon/syndication.json) maps post → {network: {url, time}}. It is the idempotency key (don't repost on rebuild), the u-syndication data ("Also posted on…"), and the backfeed-pairing key.

Crucial contrast with webmentions: the webmention export is regenerable (re-fetch from the receiver), so an empty CI runner is fine. The syndication ledger is authoritative and NOT regenerable — you cannot reliably re-derive "which Mastodon post is the copy of this entry." So:

The ledger must be durable — committed to the repo (it's small and append-mostly) or kept in persistent storage. A fresh runner without it would re-POSSE everything (double-post).
Therefore syndicate must refuse to run, or run dry, when the ledger is absent/stale unless explicitly forced — the opposite of the webmention "graceful when empty" rule.

This is the single biggest operational gotcha in the whole federation surface; the design must make double-posting structurally hard (commit the ledger; idempotent against it; --dry-run default in CI without a ledger).

What does NOT need an abstraction

Piece	Why
Webmention send	one spec-standard algorithm (discover endpoint, POST)
`rel=webmention`, `rel=hub` tags	config strings
Bridgy backfeed	lands in your receiver → read via the Reader
WebSub ping	one protocol; the hub is a config URL

WebSub (instant feed push)

Emit <link rel="hub" href="…"> in the feeds and ping the hub on publish so readers and aggregators update immediately instead of polling. Thin: a discovery tag + one POST in the post-publish step. Hubs are hosted (Superfeedr, websubhub.com). No provider abstraction.

Cross-cutting considerations (apply regardless of which pieces ship)

Where work runs. Static = no server; every action is a build/CI step or a hosted relay.
State & idempotency. The syndication ledger (durable, committed) and webmention sent-cache; never repeat actions on a rebuild; a rebuild is not a new post.
Loops & dedup. Don't webmention-loop; dedup backfed responses; u-syndication ties copies to the canonical.
Edits/deletes. Default: post-once; silo copies are point-in-time and don't track edits (optional propagation later). Canonical is the source of truth; aliases keep old URLs resolving.
Identity & SEO. rel=me, u-syndication, canonical URLs; copies cite the canonical to avoid duplicate-content problems.
Secrets. Per-network tokens, Bridgy OAuth (their side), webmention.io token, WebSub — all env-only; more features = more CI-secret surface.
Privacy/moderation. Displaying backfed third-party content (avatars, replies) → block/allow lists, avatar caching/proxying, opt-in, spam handling.
Failure/decoupling. Network steps flake/throttle → best-effort, non-blocking, retryable, and decoupled from the content build (the separate publish pipeline).
Per-network formatting. Char limits (Mastodon ~500 instance-variable, Bluesky 300), link-back, hashtags, media + alt, threading long posts; per-post custom syndication text.
Selective syndication. syndicate: frontmatter chooses targets (opt-in/out) per post.
Display freshness. JS-rendered mentions are not tied to page regeneration: the browser fetches the _mentions/ asset live, so a scheduled webmention publish (refresh that asset, no site rebuild) updates them near-live. Only the no-JS bake path is as-fresh-as-the-last-build.

Environments: read everywhere, write only where enabled

Federation splits cleanly across environments, and the split is a safety property:

Webmention reading is site-domain-scoped, so it's shared. webmention.io keys mentions by your production target URLs, so the webmention config lives at the site level and every environment inherits it. A preview build reads the same production mentions (previewing how real responses look) — no separate receiver, no extra config.
Syndication is environment-gated and off by default, like allow_publish. Which syndicators fire is an environment decision (environments[].syndicate: [ids]); an env that omits it — notably preview/draft — never cross-posts. colophon syndicate also takes the same kind of deploy latch. This makes double-posting (or POSSEing a draft) structurally impossible from preview.

So: read in every environment, write only where explicitly enabled.

Config sketch

sites:
  - id: main
    federation:
      feeds: [rss, atom, json]
      websub:
        hub: https://pubsubhubbub.superfeedr.com     # rel=hub + ping on publish
      indieweb:
        webmention:
          endpoint: https://webmention.io/blog.example.com/webmention   # advertised rel=webmention
          source:   https://webmention.io/api/mentions.jf2              # read API (JF2 reader)
      syndication:                             # a list — many syndicators per site (id + driver + settings)
        - { id: mastodon, driver: mastodon, instance: https://hachyderm.io }   # token from env MASTODON_TOKEN
        - { id: bluesky,  driver: bluesky,  handle: me.bsky.social }           # app password from env
        - { id: discord,  driver: command,  command: "curl -sf -X POST $DISCORD_WEBHOOK -d @{json}" }  # webhook: no stdout → fire-and-forget
        - { id: twitter,  driver: bridgy,   network: twitter }                 # via brid.gy/publish/twitter

environments:
  - name: production
    publish: [cf, r2]
    syndicate: [mastodon, bluesky, discord, twitter]   # which syndicators fire here
  - name: preview
    publish: [cf-preview]
    # no `syndicate:` → preview never cross-posts, but still reads the production webmentions above

Per post: syndicate: [mastodon, bluesky] (else all the env's configured ids), syndicate: false to opt out, and an optional custom blurb (syndicate_text:). Resolved silo URLs are written to the ledger and rendered as u-syndication links on the post; manually-added syndication: frontmatter is honoured too. (webmention sits at the site level, so every environment — preview included — reads the same production mentions; syndicate: is per-environment, so only the envs that list it ever post.)

Phasing

Tier 1 — cheap static + thin send: rel=webmention tag, u-syndication, WebSub rel=hub + ping, webmention send. Unlocks Bridgy + Bridgy Fed + instant feeds with little stateful code.
Tier 2 — receive/display: webmention fetch + _mentions/ assets (webmention.md).
Tier 3 — POSSE: the Syndicator abstraction + sidecar ledger + colophon syndicate, with bridgy, mastodon, bluesky, command drivers and per-network formatting.

Out of scope

Running an ActivityPub/AT actor or a reader/Microsub (delegate to Bridgy Fed / hosted readers).
A self-hosted webmention receiver (use webmention.io hosted or self-host it).
Propagating edits/deletes to silo copies (point-in-time by default).

Generated from docs/design/federation.md — edit it there.

Design: publishing from Obsidian

2001-11-22T00:00:00Z

Internal design note

This is an engineering design document — it describes how colophon works inside, and may run ahead of (or behind) the shipped code. The user-facing guides are the source of truth for behaviour.

Status: thin design · relates to PLAN §7 (Sources)

Goal: a "publish / preview" flow from an Obsidian vault with the smallest integration footprint, keeping colophon a plain CLI that reads markdown and publishes.

Key constraint: CI cannot see the live vault

A vault lives on your machine (and Obsidian Sync). A CI/CD runner has no access to it. So any CI-based publish requires the publishable content to reach a git repo the runner can clone. The important realization:

colophon's obsidian source reads .md files from a directory — it does not require the Obsidian app. A checked-out repo folder is just as readable as a live vault.

So "give CI access to the vault" = "commit the publishable markdown to a repo." The Obsidian → colophon normalization (publish-flag filter, wikilink resolution) then runs in CI, at build time, by colophon — on the committed .md files.

Two deployment models (same source driver)

	Local	Git + CI
Where colophon runs	your machine	CI runner
Reads	the live vault path	the committed repo snapshot
Secrets (`CLOUDFLARE_API_TOKEN`)	on the device	CI secret
Devices	desktop only	any (mobile Obsidian Git can push)
History	none implicit	every publish is a commit
Trigger	a button / `colophon publish`	`git push`

Both use the same obsidian source (reads a folder of .md). The only difference is where colophon runs and where the files are. serve (local, hot-reload) is the instant-preview path in both models.

The chain (git + CI)

Obsidian (write, publish: true)
   │  commit + push the publishable subset   ← Obsidian Git plugin (existing)
   ▼
Git repo  ──on push──▶  CI: colophon publish --env <production|preview>
                              (secrets in CI; obsidian source reads committed md)
   ▼
Cloudflare Pages   (PR/branch → preview env; main → production)

This composes with existing colophon pieces: environments→branches→CF environments, publish_after + next-build-time (a scheduled CI run publishes embargoed posts when due), and per-deploy prune.

The "button"

No custom plugin (recommended start): use the existing Obsidian Git plugin's commit+push. colophon needs nothing.
Thin status plugin (polish, later): a small plugin that triggers commit+push then shows the resulting deploy URL/status. It never touches secrets or runs colophon.

What colophon provides

obsidian source (done): folder read + publish: true whitelist; folder structure → slug; deletes/renames flow through build reconciliation.
A documented CI workflow (~15 lines) — to add.
next-build-time (done) for scheduled embargo publishing.

Open / dependencies

Vault privacy: commit only a Blog/ subfolder or rely on the publish-flag; private vaults → private repo.
Wikilinks ([[note]], [[note|alias]]): resolved at build via a cross-document link map. In progress.
Embeds (![[image.png]], ![[note]]): image embeds depend on the asset pipeline (PLAN §6a) to copy/host the file; note transclusion is a later step. Until then, note links resolve and embeds are left untouched.

Generated from docs/design/obsidian.md — edit it there.

Design: static search

2001-11-21T00:00:00Z

Internal design note

This is an engineering design document — it describes how colophon works inside, and may run ahead of (or behind) the shipped code. The user-facing guides are the source of truth for behaviour.

Status: v1 implemented · relates to PLAN §8 (search), §9 (publishers). The lexical engine (module github.com/jmylchreest/colophon/search), the browser reader, the build emit, the colophon search CLI, and the press theme box are built; fuzzy and semantic remain designed seams. Replaced the SearchCmd stub (SyncCmd still stubbed).

Goal: public-site search that is fully static (no server, no external service), low bandwidth (never load the whole index into the browser), and incremental-friendly (a content edit rewrites a handful of files, not the index). The same engine powers the colophon search CLI and persona exemplar retrieval.

The design borrows its architecture from Pagefind (MIT — reviewed, not vendored) — build-from-output, a sharded word index, per-page fragments, two-stage fetch — but uses our own format and a vanilla-JS reader, so we own every byte and track no private binary spec.

Why not just use Pagefind

Pagefind is excellent but is a Rust/WASM toolchain — bundling it breaks colophon's single-binary principle, and there is no Go port of its indexer (even Hugo, a Go SSG, shells out to the Rust binary). Targeting Pagefind's on-disk format from Go is worse: it's an internal, versioned, CBOR layout with an index↔WASM version handshake — we'd be the sole maintainer of a reverse-engineered emitter chasing every release. So: borrow the ideas, own the format.

One analyzer + one BM25 definition, three surfaces:

Surface	Where	Consumes
Public site search	browser, vanilla JS	the static sharded index we emit
`colophon search`	Go CLI	the same in-memory inverted index, server-side
Persona exemplars (§8)	Go	the same analyzer + BM25 (zero-config default)

The browser never runs Go/Bleve/WASM — it reads our static files with a small JS scorer. Bleve's on-disk (Scorch) format has no JS reader and isn't shippable; if Bleve is used at all it stays build/CLI-side only. The reusable core is hand-rolled and stdlib-only (see Packaging) so the inverted index is the shared structure across all three surfaces.

The one hard correctness rule: the analyzer must be identical in the Go builder and the JS reader, or a query for "running" won't match an indexed "run". The analyzer is therefore specified once (below) and implemented twice against that spec.

Packaging & module boundary

A separate Go module in this repo, colophon-branded, wired with a root go.work:

github.com/jmylchreest/colophon            (the SSG — application module)
github.com/jmylchreest/colophon/search     (the engine — its own go.mod)

Separate module, not an in-colophon package: gives the engine its own lean go.mod (a go get …/search must not drag in pongo2 / goldmark / koanf / go-git) and independent version tags (search/vX.Y.Z).
Not under internal/ — that's compiler-private; reuse needs a public path.
go.work (committed at the repo root, listing . and ./search) so colophon builds against the local copy with no published tag, while co-development stays one-repo / one-PR.
Hand-rolled, zero-dependency core — the engine ships its own inverted index + analyzer, stdlib only. This is what makes it attractive to adopt. (colophon may still use Bleve separately, CLI-side, but the published engine does not depend on it.)

The reusable unit is three artifacts bound by one spec:

Go builder/query module (…/colophon/search).
JS reader — a single dependency-free ES module (search.js), also publishable to npm.
The format + analyzer spec — the real public contract. This document is the rationale; the normative, language-neutral specification lives in search/SPEC.md (with search/README.md as the adopter entry point), precise enough to implement a conformant reader or builder in any language against the committed test vectors.

Engine API (source- and FS-agnostic)

package search

// A Doc is anything indexable — the engine knows nothing about colophon pages.
type Doc struct {
    ID    string            // stable, caller-provided (colophon uses the page URL/slug)
    URL   string            // result link
    Title string
    Body  string            // already-extracted plain text
    Meta  map[string]string // shown in the result card; not indexed unless requested
}

type BuildOptions struct {
    Analyzer  Analyzer      // default: SimpleAnalyzer (below)
    ShardFunc ShardFunc     // default: fixed lexical ranges
    BM25      Params        // k1, b
}

// Build writes the static index (manifest + shards + fragments) to dst. dst is an
// abstraction (a dir on disk for most users; colophon routes it through a publisher).
func Build(docs iter.Seq[Doc], dst Writer, opts BuildOptions) (Manifest, error)

// Open mounts an emitted index for server-side querying (the CLI surface).
func Open(fsys fs.FS) (*Index, error)
func (*Index) Search(q string, limit int) ([]Result, error)

Writer is a minimal Put(name string, b []byte) error — the same shape as the publisher FileWriter, so colophon can emit straight through routing, and a standalone user can write to a directory.

The analyzer (the contract)

Specified once; implemented identically in Go and JS. v1 is deliberately trivial to make parity self-evident and keep the core stdlib-only:

Lowercase (Unicode-aware: Go unicode.ToLower / JS toLowerCase).
Split on any run of non-(letter|number) → tokens (Go unicode.IsLetter/IsNumber via strings.FieldsFunc / JS /[^\p{L}\p{N}]+/u).
No NFC normalization, no stop-words, no stemming in v1.

That's it — two implementations of one pure function Analyze(string) []string. A shared golden-vector fixture (testdata/analyzer.json: input → expected tokens) is run by both the Go and JS test suites, so drift is caught mechanically.

NFC is deferred deliberately: stdlib Go has no NFC, and adding it would pull in x/text — against the zero-dep goal. The consequence is that decomposed Unicode (e.g. e+combining accent) tokenizes differently from composed (é); content from normal editors is composed, and the golden fixture stays ASCII to avoid encoding ambiguity. NFC + a matched Go/JS stemmer arrive together behind an analyzer-id bump (simple-1 → …-2), which a stale reader can detect.

Stemming (e.g. a matched Go+JS Snowball/Porter2 pair) and stop words are deferred — added only as a matched pair, behind a version bump of the analyzer id recorded in the manifest.

Index format

Emitted as plain static files under a configurable base (default /_search/):

_search/
  manifest.json                 # the mutable root — small, short-TTL
  index/<range>.<hash>.json.gz  # postings shards — immutable, content-addressed
  fragment/<docid>.<hash>.json  # per-result cards — immutable, content-addressed

manifest.json — routing + scoring constants, loaded once (a few KB):

{
  "v": 1,
  "analyzer": "simple-1",
  "bm25": { "k1": 1.2, "b": 0.75 },
  "docs": 412,
  "avgdl": 680.4,
  "shards": [
    { "lo": "a",  "hi": "cz", "url": "index/a-cz.7c1e9b.json.gz" },
    { "lo": "d",  "hi": "gz", "url": "index/d-gz.2f4a01.json.gz" }
  ],
  "fragments": { "...": "docid → fragment/<docid>.<hash>.json" }
}

A postings shard — term → [[docId, termFreq]] (positions omitted in v1 → no phrase search):

{ "tiger": [[7,1],[88,2]], "tigris": [[7,3]] }

DocIds in postings are small integers interned from the stable string ID via a table in the manifest — compact in postings, while the interning is deterministic from sorted stable IDs (see below). Fragments are keyed by the string docId.

A fragment — everything needed to render one result, fetched only for shown hits:

{ "url": "/posts/tigris/", "title": "Publishing to Tigris", "excerpt": "…", "meta": {"type":"post"} }

Extensibility: shared substrate + pluggable index types

The format separates a substrate (shared by every search mode) from index types layered over it. This is the seam that lets fuzzy and semantic search be added later as additive artifacts, never a reformat.

Substrate (always present):

Doc identity — the stable string ID ↔ interned int table (in the manifest).
Fragments — per-doc result cards (fragment/…).
Manifest — the mutable root, listing which index types are present and where their shards live.

Index types (each optional; each sharded + content-addressed + deterministic the same way):

Type	Maps	Status	Adds
`lexical`	term → [docId, tf] (BM25)	v1	`index/` shards
`fuzzy`	trigram → [termId]	opt-in, additive	`trigram/` shards
`semantic`	docId/chunk → vector (+ ANN)	future, additive	`vector/` shards

The manifest gains one optional section per present type; the Go query layer and JS reader dispatch on what's there. Turning a type on is a build flag plus more emitted files — the substrate, the postings format, and existing files are untouched. BuildOptions gains Fuzzy bool (and later Semantic …) accordingly.

Fuzzy / typo-tolerance (n-gram + Levenshtein)

The optional fuzzy type is a character-trigram index (trigram → terms), sharded by trigram range like everything else. Query path, when enabled and an exact match yields too few hits: decompose the query term into trigrams → fetch those trigram shards → gather candidate terms by trigram overlap → keep those within a bounded Levenshtein distance (computed in JS over the small candidate set) → fetch the candidates' postings shards → BM25, optionally down-weighted by edit distance. Trigrams derive from the same analyzer output, so there's no new analysis contract. Opt-in because it roughly doubles index size.

Two near-free relatives of lexical-range sharding: prefix/autocomplete (shards are sorted, so a prefix hits one/few shards via binary search) and substring (falls out of the trigram index).

Sharding — fixed lexical ranges

Shards are bucketed by fixed, stable lexical term ranges (a–cz, d–gz, …), not Pagefind's fixed-count chunks. Rationale: fixed-count chunks shift their split points as vocabulary grows, cascading rewrites across many shards; fixed ranges mean a new term lands in its existing bucket and only that bucket changes. Cost: uneven shard sizes — handled by a deterministic rule that sub-splits only over-large ranges (e.g. a → aa–am, an–az), which is itself stable given the same vocabulary.

Determinism & incrementality

The point: an edit should rewrite as few files as possible, so the incremental publisher (content-hash diff + orphan prune, already built) uploads almost nothing and the CDN caches the rest forever. Five composing rules:

Content-addressed filenames — every shard and fragment is named by a hash of its bytes. Unchanged content → identical name → publisher sees no change → no upload; and the file can be served Cache-Control: immutable, max-age=1y. The manifest is the only mutable file (it maps logical keys → current hashes): a mutable root over an immutable, content-addressed tree (git's model).
Stable doc IDs, never positional. Postings key off a stable per-doc ID (colophon: the page URL). Adding/removing a post must not renumber the others. Integer interning for compactness is assigned by sorted stable-ID order recorded in the manifest — deterministic and stateless (no committed id-map; honors §8 "regenerable, not committed"). (Note: a pure insert still renumbers ints after it; if that churn proves costly we revisit with a prev-manifest-seeded allocator. v1 keeps it stateless.)
Stable shard boundaries (fixed lexical ranges, above) — vocabulary growth doesn't reshuffle.
Canonical serialization — sorted keys, stable number formatting, fixed field order, and gzip with mtime=0 + fixed level. Without this, "unchanged" content re-hashes every build (gzip embeds a timestamp by default). This is what makes the content-addressing actually hold.
Postings/presentation split — volatile display data (excerpt, title styling, meta) lives in fragments; postings are just term → [id, tf]. A cosmetic edit touches one fragment and zero shards; a body edit touches that fragment plus only the shards for the terms that actually changed.

Inherent churn (accepted): the manifest (small, by design); hot-term shards (the, and) on most edits (a few files, not the index). Orphans (superseded content-addressed files) are removed by the publisher's existing delete_orphaned; the manifest is marked Protected so it is never deleted mid-swap.

Typical "edit one post" outcome: 1 new fragment + 1 changed manifest + a few hot-term shards, everything else byte-identical and skipped.

Several deployments (sites × environments) can publish to one object store. Only the manifest is per-deployment — its name is a short hash of (siteID, env) (manifest-<hash>.json; the bare manifest.json is the no-site/no-env default) — so the mutable roots don't collide. The content-addressed shards/fragments are shared: identical content across deployments dedupes to one object, and each deployment's reader loads its own manifest (told via data-search-manifest).

To make that safe, the whole _search/ prefix is exempt from orphan-deletion: each publisher's Protected(name) returns true for it, and the incremental planner deletes a deployed object only when it is both absent from the current build and not protected. So a deployment never prunes another's shards or manifest — it only writes its own manifest and adds shards.

TODO (revisit): garbage collection for _search/. The cost of the protection is that superseded shards/fragments (and the pre-hash manifest.json) accumulate, never auto-pruned — tiny (~200 B each) and deduped, but unbounded over time. A proper fix is a mark-and-sweep GC: read every live manifest-*.json in the store, union the shards/fragments they reference, and delete the _search/ objects nothing references. This can't be the per-publish delete_orphaned (which only sees one deployment's set); it wants to be an explicit pass (e.g. colophon search gc / publish --gc). Related: the protected-prefix list is currently hardcoded and duplicated across the r2/s3/local Protected methods — worth centralizing (and possibly making configurable) at the same time.

Browser query flow

The whole reader is ~a screen of dependency-free JS:

Fetch manifest.json once (cache in memory).
analyze() the query (the shared analyzer).
For each term, binary-search shards for its range, fetch only that shard (dedupe + cache).
BM25 over the loaded postings: idf = ln(1 + (N − df + 0.5)/(df + 0.5)), score += idf · tf·(k1+1) / (tf + k1·(1 − b + b·dl/avgdl)) (N, avgdl, per-shard df, per-doc dl all come from the manifest/shard).
Sort, take top-limit, fetch only those fragments, render.

Memory at any instant = manifest + the shards the query touched + the visible fragments. Never the whole index.

Progressive enhancement & theme integration

Search ships only when enabled (like the glossary ships only when used) and is a progressive enhancement (consistent with the raw-block contract): the search box degrades to a plain link to an archive/index page without JS, and enhances to live search when search.js loads. The search.js + CSS are theme/engine-emitted assets; the index files are emitted by the build (and routable like any other output — so the index can even live on an object store while HTML is on Pages).

Semantic — a future index type over the same substrate

v1 is lexical only, but semantic is designed-in as the semantic index type (above), not a parallel system. It emits per-chunk embedding vectors as content-addressed, sharded files reusing the same doc identity and fragments — added alongside lexical, never instead.

The only genuinely new cost is query-time embedding: the browser needs a model or a query endpoint; the index slots into the existing file model. Scaling options that fit the sharded design: small corpora load all vectors (brute-force cosine); larger ones use IVF-style centroid prefiltering (centroids in the manifest → fetch only the nearest clusters' vector shards), or the §8 pure-Go HNSW behind the Retriever interface. The CLI semantic path (§8 vectors.f32) is the same vectors consumed in Go. None of this is in v1 — but the substrate makes it additive.

Embedder-parity contract (the embedding analog of the analyzer contract): the build-side embedder (Go) and the query-side embedder (browser) must be the same model, or query vectors won't share the doc vectors' space. The recommended future embedder is therefore static embeddings (Model2Vec / potion-*): a token→vector lookup table that is implementable identically in Go and JS from one shared weights file (golden-vector tested, like the analyzer), runs in pure code with no ONNX/WASM runtime on either side, and is a few MB rather than ~30MB. It trades ~10–20% quality vs a MiniLM transformer — acceptable because semantic is used as a hybrid recall/rerank assist over lexical BM25, not a replacement. A full transformers.js MiniLM stays the higher-quality opt-in fallback.

Key decisions

Decision	Choice	Rationale
Build vs runtime	Build-time static index	Fully static, no server (§8)
Format	Our own JSON(.gz)	Own every byte; no Pagefind-format/version coupling
Browser runtime	Vanilla JS scorer	No WASM; fine at blog/medium scale; ours to maintain
Architecture	Substrate + pluggable index types	Fuzzy/semantic become additive, not a reformat
Index shape	Sharded inverted (BM25)	Never load the whole index; low bandwidth
Fuzzy	Opt-in trigram index + Levenshtein filter	Typo tolerance without bloating the default index
Sharding	Fixed lexical ranges	Stable boundaries → minimal rewrites on edit
Filenames	Content-addressed	Incremental publish + immutable CDN caching
Doc IDs	Stable (URL-derived)	Edits don't renumber → postings stay stable
Serialization	Canonical, gzip mtime=0	Identical content → identical bytes (determinism)
Analyzer	Simple (no stemming) v1	Trivial Go/JS parity; golden-vector tested
Packaging	Separate module, same repo, `go.work`	Dep isolation + own tags; co-dev stays cheap
Engine deps	Hand-rolled, stdlib-only	Adoptable library; Bleve (if any) stays CLI-side
Semantic	CLI-side only	Public semantic needs a model at query time (§8)

Acceptance criteria

search.Build emits manifest + shards + fragments to a Writer; re-running on unchanged input produces byte-identical shard/fragment files (determinism).
Editing one doc changes only its fragment, the manifest, and the shards for its changed terms — all other files byte-identical.
A query loads the manifest + only the shards for its terms (verified by fetch count), and fetches fragments only for displayed results.
BM25 ranking from the JS reader matches the Go Index.Search ranking on a shared fixture.
The shared analyzer golden-vector fixture passes in both Go and JS suites.
colophon search --json returns ranked results from the same engine (replaces the stub).
With JS disabled, the search UI degrades to a working archive link.
go get github.com/jmylchreest/colophon/search pulls a lean module (no SSG deps).

Files to create

search/go.mod, root go.work — the module + workspace.
search/analyzer.go (+ testdata/analyzer.json) — the analyzer spec + golden vectors.
search/index.go — inverted index, BM25, Build, sharding, canonical serialization.
search/query.go — Open / Index.Search (CLI surface).
search/format.go — manifest/shard/fragment types + content-addressing.
search/search.js (+ test) — the browser reader; shares the analyzer + golden vectors.
colophon side: internal/build/search.go (extract page text → Docs → Build via a routed Writer), wire SearchCmd to search.Open(...).Search, theme assets + a search partial.

Releasing / using it elsewhere

./search is its own Go module (github.com/jmylchreest/colophon/search) kept in this repo; colophon builds against it locally via the go.work workspace, so it needs no published tag for development. For external consumers it's published from the monorepo as a nested module: the release workflow tags search/v<colophon-version> whenever ./search has changed since its last tag (mirroring the colophon release version — gaps are expected). Others then go get github.com/jmylchreest/colophon/search@search/v<version>. Those search/v* tags don't trigger the binary-release workflow (its trigger is v*). If the engine ever warrants a standalone identity (e.g. github.com/jmylchreest/n), it would move to its own repo, since a module's path must match its repository URL.

Out of scope (future)

Stemming/stop-words (matched Go+JS pair, analyzer-id bump); positions → phrase/proximity; filters/facets + sorts; sub-splitting heuristics tuning; in-browser semantic; a published npm package for search.js.

Generated from docs/design/search.md — edit it there.

Design: webmention

2001-11-20T00:00:00Z

Internal design note

This is an engineering design document — it describes how colophon works inside, and may run ahead of (or behind) the shipped code. The user-facing guides are the source of truth for behaviour.

Status: built · relates to PLAN §10 (Federation & IndieWeb), §6 (build pipeline). The whole design ships: the <link rel="webmention"> tag; webmention send (sent-cache); webmention fetch (jf2 reader → _mentions/ cache); per-site display.mode (live/asset/disabled) with the themed responses block + mentions.js; webmention publish (decoupled _mentions/-only deploy); and the committed glob blocklist + colophon-moderate-mentions skill. Code in internal/webmention/, internal/build/{mentions,webmention}.go, internal/cli/webmention.go. Deferred: semantic moderation and searchable mentions (see those sections).

Goal: let a colophon site participate in Webmention — the W3C standard for "site A notified site B that it linked to / replied to / liked B's post" — while staying fully static (no server, no database) and keeping received data in clean, separate assets rather than mixed into the author's content. Two halves: sending (we tell others we linked them) and receiving + display (others' mentions appear under our posts).

It deliberately reuses five patterns colophon already has, rather than inventing new ones — see Fit with existing design.

Why a separate command (not part of build)

The two operations run at different points in the lifecycle, so neither belongs inside build:

Operation	When	Why
`colophon webmention send`	after `publish`	the source URL must be live so the receiver can fetch it back and verify the link
`colophon webmention fetch`	before `build`, or standalone/scheduled	pulls received mentions into the local cache so a bake build can read them
`colophon webmention publish`	on its own cadence (e.g. cron)	`fetch` + push only the `_mentions/` prefix to the object store, decoupled from the site build — see Separate publish pipeline

So webmention is a command group alongside build/publish. A typical CI flow:

colophon webmention fetch     # refresh received mentions → committed cache
colophon build                # emit _mentions/ assets (+ bake for no-JS themes)
colophon publish --env production --allow-publish
colophon webmention send      # now that the new post is live, notify the sites it links to

fetch is also fine to run on a schedule (cron) to keep mentions fresh without a content change.

Receiving: data as a separate asset

We don't run a server, so we can't accept inbound POSTs. Mentions are received by a hosted receiver — webmention.io (free; the page advertises it via <link rel="webmention">). fetch reads them back through its JSON API (token in {env:…}, never config) and normalises them into one JSON file per post, served as its own asset namespace — exactly mirroring the _search/ index:

_mentions/<post-path>.json     e.g. _mentions/posts/hello-world.json

Each file is a small, normalised list (not the raw webmention.io payload):

{
  "target": "https://blog.example.com/posts/hello-world/",
  "updated": "2026-06-22T10:00:00Z",
  "mentions": [
    { "type": "like",   "author": {"name": "Ada", "url": "https://ada.example", "photo": "https://…/ada.jpg"},
      "url": "https://ada.example/likes/1", "published": "2026-06-21T09:00:00Z" },
    { "type": "reply",  "author": {"name": "Bob", "url": "https://bob.example", "photo": "…"},
      "url": "https://bob.example/notes/2", "published": "…", "content": "Nice post!" }
  ]
}

type is normalised to like | repost | reply | mention (from the sender's mf2 / wm-property).
author fields come from the sender's h-card — which is why mf2 shipped first.
The build emits these to the output tree under _mentions/, routed to R2 like _search/, and they get CORS for free from publish --create (same GET/HEAD rule the JS search index already relies on for cross-origin fetch).
fetch writes a local cache (.colophon/cache/webmentions/). This cache is not treated like the generated-image cache — see below.

One JSON-per-post (no sharded manifest like search) because a post page already knows its own key.

Not reproducible — and that's fine

Unlike the gen-image cache (a deterministic function of the prompt, committed for reproducible builds), received mentions are external, time-varying state — other people's posts. The local .colophon/cache/webmentions/ is therefore a derived export, not preserved state: webmention.io is the source of truth and fetch fully regenerates the export from it every run.

fetch queries the whole domain — GET /api/mentions.jf2?domain=<domain>&token={env:…} returns the complete current set (JF2, newest-first), paged via per-page+page — then buckets by target and writes one JSON per post, replacing whatever was there. Properties of that:

Stateless / idempotent. A fresh CI runner with an empty cache just rebuilds it from the API (needs only network + token). "Empty" means "rebuild it," never "lost data."
Self-reconciling. Because each run takes the full current set, deleted/edited mentions correct themselves — no stale entries to prune. (since/since_id enable delta fetches later if volume ever warrants; full-regenerate is the simple default.)
Graceful when empty. Until fetch runs, a missing _mentions/<post>.json renders nothing and never fails the build — mentions are always additive chrome.
The JS path removes the build dependency entirely. A JS-rendering theme ships only a placeholder; the browser fetches the separately-published _mentions/ from R2 (see Separate publish pipeline), refreshed out-of-band.

So committing the JSON to the repo is optional (it only helps a baked build show mentions with no network, at the cost of churny commits); the default is "regenerated by fetch in CI / on a schedule," not "committed."

Deletions & pruning (full-replace, not merge)

"Self-reconciling" only holds if regenerate is a full replace of the _mentions/ namespace, not a per-post upsert — otherwise a mention webmention.io has deleted lingers in a stale file. Concretely:

A deleted mention isn't in the next fetch result, so the rewritten per-post file omits it.
Zero-mentions edge: when a post loses all its mentions there's nothing to write for it. fetch must therefore clear the namespace and rewrite wholesale so that post ends up with no file (not a leftover from a prior run), and publish must prune objects no longer present from the store — which the existing incremental publisher already does (the Pruner: "only changed files upload, orphans are pruned"). The stale object is deleted from R2.
The JS path then 404s → renders nothing; a baked rebuild finds no file → renders nothing.
This is eventually consistent: a deletion persists until the next fetch+publish (JS) or rebuild (bake). The scheduled webmention publish keeps that window short without a site build.

Implication for publish: it must apply orphan pruning scoped to the _mentions/ prefix so a mentions refresh never deletes content objects (and vice versa).

Display: a per-site `mode` (`live` / `asset` / `disabled`)

How responses reach the page is a per-site setting (federation.indieweb.webmention.display.mode). There are exactly three values — there is no separate "baked" mode (baking is a theme choice within asset, see below). The mode decides where the browser fetches from and whether the engine ships anything at all; both active modes use the same mentions.js + the same moderation pipeline.

Mode	What ships per page	Browser fetches from	Build-time data?	Freshness	Privacy
`live`	placeholder + JS	the receiver directly	no	next page load	visitor hits the receiver
`asset`	placeholder + JS (+ optional bake)	our `_mentions/` on R2	yes (synced list)	the refresh cron	self-hosted
`disabled`	nothing (zero counts)	—	—	—	—

Per-page toggle. When the mode is active (live/asset), webmentions are on by default for every post, opt-out per page via frontmatter (webmentions: false). In disabled the page setting is ignored — nothing is embedded or shipped anywhere, has_mentions is false and mentions is empty.

`live` — JS straight to the receiver (no fetch/publish/build)

The engine ships, on each enabled page, an engine-provided placeholder + the shared mentions.js; the browser calls the receiver's read API directly (webmention.io exposes a public, CORS-enabled, token-free read endpoint). A new mention shows on the next page load — no fetch, no publish, no rebuild, no asset to host. Lowest-infra, most realtime.

Crucially, in live the engine has no build-time data — so has_mentions/count are not known at build. The placeholder ships whenever the page is enabled (not gated on a count), and JS fills in the count (and hides the section if it resolves to zero). So themes cannot bake in live mode.

Because a reader speaks a specific read API, the JS is parameterised by the reader driver: the driver declares a small client descriptor (endpoint URL template, query params, and the mapping from its response → our normalised shape). One shared mentions.js consumes the descriptor and handles any JF2-shaped endpoint (webmention.io and compatibles — all one jf2 driver); a service with an exotic API would be a different driver shipping its own client module. So "the fetch JS is provided by the specific driver" — yes, via the descriptor, without forking the renderer per service.

Moderation still applies: the distilled glob blocklist is shipped to the client (it's spam-hiding, not a secret) and filtered in-browser. Semantic rules can't run client-side (no embeddings in the browser), so a site that needs semantic moderation should use asset. Trade-offs to accept: every visitor's browser hits a third party (their uptime/rate-limits become yours; a privacy leak), and no-JS/RSS readers see nothing.

`asset` — JS against our published `_mentions/`, with optional build-time bake

The default is the same placeholder + mentions.js, but pointed at our server-curated _mentions/<key>.json on R2. Freshness comes from a scheduled webmention publish — fetch + push of only the _mentions/ prefix, no site build (see Separate publish pipeline) — near-realtime to whatever cron cadence you pick, with full server-side moderation (glob + semantic), self-hosting, and driver-neutrality.

Because the synced mentions list already exists at build time in this mode, the engine also exposes it to the template (mentions/mentions_html/has_mentions) so a theme that wants to hard-code / bake them into the HTML can — instead of, or alongside, the JS placeholder. This is plausible precisely because we already have the built/synced list; it's a theme capability, not a mode. Baked output is then as-of-last-build (the JS placeholder is what stays cron-fresh), and it's the no-JS escape hatch for text-first themes like minimal.

Template surface

Rendering remains a template responsibility — the engine only exposes the data, exactly as attachments/attachments_html do:

Var	`live`	`asset`	`disabled`
`has_mentions`	unknown at build → `false` (JS fills count)	accurate (from synced list)	`false`
`mentions`	empty (no build-time data)	structured `[{type, author{name,url,photo}, url, content, published}]` — bake your own	empty
`mentions_html`	empty	engine-rendered drop-in block (empty when none)	empty
`mentions_src`	driver client-descriptor endpoint	our `_mentions/<key>.json`	unset
`mentions_enabled`	`true` unless page opted out	`true` unless page opted out	`false`

Bundled themes drop the placeholder + mentions.js for the JS modes; minimal (no-JS) uses asset + the baked mentions_html. The mode is overridable per site.

Audio / TTS: mentions are never spoken

A real hazard for the bake path — handled by an invariant. The TTS reading is generated from the post's markdown body (registerTTS(slug, html, …), where html is the converted content) before the theme runs. Mentions are theme chrome rendered as a sibling of {{ content }} — like the author card, downloads and tags, none of which are spoken. So:

Invariant: mentions render outside the content / e-content body the TTS extractor reads. Themes must keep the mentions block a sibling of the content element, never inside it.

This means baked mentions are excluded from audio for free (the TTS source predates theming); the guard just stops a theme from accidentally nesting them into the content element.

Sending

colophon webmention send works off the built output (or the deployed URLs):

Scan each published post's HTML for outbound links (http(s):// to other origins).
For each target, discover its endpoint — an HTTP Link: rel="webmention" header, else a <link rel="webmention"> / <a rel="webmention"> in the body.
POST source=<post URL>&target=<their URL> to the endpoint.
Maintain a per-post sent-cache of the link set last sent. On re-run, send only new targets — and re-send to dropped targets so that if you edit a post to remove a link, the receiver re-checks, sees the link gone, and removes its mention (the spec's update/delete path).

The sent-cache is what makes "we changed the context after sending" correct rather than silent.

The mutability question (and how it plays with existing choices)

Three cases, by what changes:

Post content changes → fine. Received mentions target the URL, not the prose; edits are normal. Senders replied to the address.
Post URL/slug changes → the real gotcha. webmention.io holds mentions under the old URL; the new page finds none; inbound links rot. Mitigations: (1) keep slugs stable (link-rot discipline); (2) once the backlog aliases: / redirects feature lands, fetch queries the old keys too and the old URL 302s to the new; (3) doctor warns when a post that has cached mentions changes slug. This makes aliases: a soft prerequisite for robust webmention and is the main cross-feature dependency.
A sender deletes/edits a mention, or we drop a sent link → reconciled by re-running: fetch always returns the current set (deletions vanish); send's sent-cache re-pings dropped targets. JS display is always-current; baked display reconciles on the next fetch+build.

Spam/moderation: inbound mentions can be junk — handled by a declarative, committed blocklist plus an optional moderation skill; see Moderation.

Moderation: a distilled, committed blocklist

Inbound mentions are third-party content, so the author needs a way to drop spam/abuse — and it has to survive fetch's full regenerate (editing the generated _mentions/ JSON is pointless; the next fetch overwrites it). So moderation is declarative and committed, applied as a filter step over the normalised list, and reused by every display mode.

The blocklist is rules over normalised mention attributes, glob-matched. Matchable fields: domain, url, author.name, author.url, content, type. A bare string is shorthand for domain/author.url; the structured form targets a field:

# .colophon/webmention-block.yml  (committed)
- "*.spam.example"            # shorthand: domain/author.url glob
- author.url: "https://troll.example/*"
- content: "*free crypto*"
- domain: "*.cn.example"

One filter pipeline, two execution sites. Applied server-side in fetch (full power) for asset/baked; for live the distilled blocklist is shipped to the client and the same glob rules run in mentions.js (it's spam-hiding, not a secret). Glob rules run in both places; semantic rules (below) are server-only.
Semantic moderation (future). When the semantic subsystem lands, a rule kind scores a mention's content against a concept ("spam"/"abuse") via embeddings + a threshold, slotting into the same server-side pipeline. Not available client-side, so semantic-moderated sites use asset/baked. (Ties into [decision search] — the shared embedding subsystem.)
A moderate-mentions skill (an agent skill alongside the other authoring skills) scans the current mention set, flags likely spam/abuse, and either auto-filters or presents a decision list for the author to confirm. Crucially it distills confirmed cases into generalised glob (and later semantic) rules appended to the blocklist — so the list stays small and effective rather than an ever-growing pile of individual URLs.
Receiver-side delete (e.g. webmention.io's dashboard) remains the quick one-off: delete there, the next fetch won't return it. The committed blocklist is the version-controlled, reproducible path; per-mention approval queues are deferred.

Separate publish pipeline

The _mentions/ assets are published independently of the content build/deploy, so you can update one without the other. colophon already partitions output by path at publish time (the router sends _search/** to the R2 publisher while content goes to Pages); the same machinery publishes only the _mentions/** prefix.

colophon webmention publish --env production    # fetch + write _mentions/ + push ONLY that prefix to R2

So the two cadences are decoupled:

Content pipeline (build → publish): ships HTML + JS placeholders. Never depends on the mentions cache; a fresh runner is fine.
Webmention pipeline (webmention publish, e.g. hourly cron): refreshes _mentions/ on R2. The JS path picks it up in the browser with no site rebuild.

This is the strongest reason JS is the default render path — it's the only one that benefits from the decoupling (a baked theme still needs a content rebuild to reflect new mentions, so baking suits low-frequency / no-JS sites). Implementation reuses the per-publisher routing (router.Owns/Keep) plus a publish that only materialises the _mentions/ tree.

Search: mentions as down-ranked results (optional, `asset` mode)

Replies carry real text ("someone said X about post Y"), so indexing them into the site's lexical search is sensible — and plausible, because we already hold the normalised list. Design:

Only asset mode. A static index needs the data at build time; live has none. So search-indexed mentions are an asset-mode / fetch-driven feature (off in live/disabled).
Only text-bearing kinds. Index reply/mention (they have content); skip like/repost (nothing to match). Each indexed doc carries content, author, the target post it lives under, and kind: mention.
A separate, down-ranked shard. Rather than mixing mention docs into the content index (which would churn it on every mentions refresh), emit a second search shard for mentions, merged client-side. This keeps it on the webmention publish cadence (consistent with _mentions/ decoupling) and lets the UI treat it differently: a rank penalty plus grouping so mention hits sort below content hits — or render in a distinct "Mentions" group appended to the bottom of the results list. Configurable; default down-ranked-and-grouped.
A hit links on-site: to the post's responses anchor (keeps the reader on the site), citing the mention's source URL. Freshness is as-of-last index refresh.
Blocklist-gated. Mentions are filtered through the same moderation pipeline before indexing — blocked mentions are neither displayed nor searchable.

This reuses the internal pure-Go BM25 index (decision search): add a kind field + a rank weight, emit the extra shard, and teach the search UI to group/penalise kind: mention. Marked a later enhancement (after Tier 2 display), gated by an explicit search_index: true under webmention.

Fit with existing design

Concern	Reused pattern
Separate JSON asset, R2-routed, cross-origin	`_search/` index + `publish --create` CORS
Browser fetch + render, no-JS fallback	`search-ui.js` / `player.js` progressive enhancement
Template data exposure (`mentions`/`mentions_html`)	`attachments`/`attachments_html`
Per-path publish partitioning	the router's `_search/**` → R2 split (`router.Owns`/`Keep`)
Read token from environment, not config	all secrets via `{env:…}`
Config wiring	`federation.indieweb.webmention.receiver` (already present, unread)
Parsing mention authors	the mf2 `h-card`/`h-entry` just shipped

Config

sites:
  - id: main
    federation:
      indieweb:
        webmention:
          receiver: https://webmention.io/blog.example.com/webmention  # the rel=webmention endpoint
          # token read from env, e.g. WEBMENTION_IO_TOKEN, never written here
          driver: jf2                  # reader driver (read API + client descriptor); default jf2
          display:
            mode: asset                # live | asset | disabled   (see Display)
          # blocklist lives in .colophon/webmention-block.yml (committed), not inline

mode: live needs nothing else; asset uses the webmention fetch/publish pipeline (and can be baked at build by the theme); disabled ships nothing. Per page: webmentions: false opts a post out when the mode is active.

<link rel="webmention" href="{{ receiver }}"> is emitted in every page <head> when a receiver is configured (the discovery tag senders look for).

Key decisions

Separate webmention command (send after publish, fetch before build, publish on its own cadence) — not folded into build/publish, because of the live-URL ordering constraint and the decoupled-refresh goal.
Received data is a separate _mentions/ asset (R2-routed, CORS via --create), never mixed into content — mirrors _search/. The cache is not reproducible (external state); builds are graceful when it's empty, and freshness comes from fetch/publish, not the repo.
One JSON per post, normalised (type/author/url/content), not raw receiver payload.
Display is a per-site mode — live | asset | disabled (there is no separate baked mode). live = browser→receiver direct (most realtime, client-side glob blocklist, no build-time data so no count/bake, no no-JS); asset = browser→our R2 asset refreshed by a cron publish (full moderation, self-hosted) and the synced list is exposed at build so a theme may bake it (baking is a theme capability within asset, not a mode); disabled = nothing ships, zero counts, page toggle ignored. Per-page opt-out via webmentions: false. The engine exposes mentions/mentions_html/has_mentions/mentions_src/mentions_enabled; the theme renders. live mode's fetch JS is parameterised by the reader driver's client descriptor. 4b. Moderation is a declarative, committed blocklist of glob rules over mention attributes (.colophon/webmention-block.yml), re-applied every fetch (and shipped to the client in live mode). Future semantic rules run server-side; a moderate-mentions skill distills confirmed spam into small, general rules. Survives full-regenerate because it's declarative.
TTS invariant: mentions live outside the content body the speech extractor reads, so they're never spoken — true for both paths.
Separate publish pipeline: webmention publish pushes only _mentions/ to the store, so mentions and content update independently (reuses per-publisher path routing).
Sent-cache drives correct re-send on link changes; aliases: is the soft dependency for surviving URL changes.
webmention.io as the receiver (no self-hosted endpoint) — per PLAN §10/§14.

Acceptance criteria

colophon webmention send discovers endpoints and POSTs for outbound links; re-run is a no-op unless links changed; dropped links trigger a delete-style re-send.
colophon webmention fetch writes normalised JSON into the local cache; webmention publish pushes only _mentions/** to the store, independent of a content deploy.
A build with an empty cache succeeds and shows no mentions (graceful); a build with the cache present exposes mentions/mentions_html to templates and emits _mentions/ assets.
A mention deleted on webmention.io disappears after the next fetch+publish; a post that drops to zero mentions has its _mentions/<post>.json removed and the orphan pruned from the store (JS path 404s → renders nothing). Pruning is scoped to the _mentions/ prefix.
A JS-enhanced theme shows likes/reposts/replies; with JS off the post is unaffected; minimal bakes them statically. Mentions never appear in a post's TTS audio.
display.mode: live renders mentions with no fetch/publish/rebuild (browser → receiver), honouring the shipped glob blocklist client-side, with no build-time count; asset renders from the published _mentions/ (and exposes the synced list so a theme may bake it at build); disabled ships nothing (zero counts, webmentions: page setting ignored). webmentions: false opts a single post out when the mode is active.
A blocklisted mention (glob over domain/url/author/content) never appears in any mode; the blocklist survives a full fetch regenerate (it's committed, not edited into the export).
Secrets come only from the environment; a site with no webmention config emits nothing.

Files to create (when built)

internal/webmention/ — endpoint discovery + sender (sent-cache) + reader driver (server fetch + client descriptor) + normaliser + the blocklist filter pipeline.
internal/cli/webmention.go — the webmention {send,fetch,publish} command group; publish supports the incremental (changed-mention-posts-only) re-render for baked.
build: expose mentions/mentions_html/has_mentions/mentions_src to templates, emit _mentions/ assets + the <link rel="webmention"> head tag; in live mode emit the driver client descriptor + the distilled blocklist for client-side filtering.
internal/render/themes/*/… — a data-mentions placeholder + engine-emitted mentions.js (parameterised by the driver descriptor; applies glob blocklist in live) and a pongo-baked block (text themes), kept outside the content/e-content element.
contrib/skills/ (+ wiring) — a moderate-mentions skill that flags spam/abuse and distills confirmed cases into blocklist rules.

Out of scope (future)

Self-hosted webmention receiver (PLAN §14 leaves this open; webmention.io is the v1 choice).
Rich moderation UI / per-mention approval.
Sending as specific post types (replies/likes from colophon itself) — colophon publishes articles; it links, it doesn't (yet) author reply-posts.
Fediverse/Bridgy Fed backfeed — a later layer that reuses this send/receive + mf2 substrate.

Generated from docs/design/webmention.md — edit it there.

colophon docs

colophon documentation

Authoring content

Frontmatter fields

Page types

Post series

Markdown support

The raw-block contract (progressive enhancement)

Links, wikilinks and images

Images and object storage

Embedding video and audio

Attachments (downloads)

Slide decks

Multiple languages (translations)

How file references resolve

Redirects (aliases)

Glossary

Sources

Publishing

Publishers

Configuration and interpolation

Secrets and permissions

Provisioning with --create

Generic S3 / MinIO / Backblaze / Wasabi

Tigris (Fly.io)

Git-based hosting (GitHub / GitLab / Codeberg Pages)

GitHub Pages

GitLab Pages

Codeberg Pages

Any git remote

Run any CLI: the command publisher

Per-environment overrides

Redirects (aliases)

WebSub (real-time feeds)

On-site search

Routing assets to an object store

Routing the search index

Themes

Selecting a theme

Inspecting and ejecting themes

Supplying your own theme

Base themes (inheriting another theme)

Community themes (contrib/themes/)

Theme files

Page types

The templating language

Template variables

page.html (a single post)

index.html (the post list, and per-tag pages)

Enhancing rich blocks

Audio, video & downloads

Microformats2 (IndieWeb)

Webmentions (responses)

Silo icons

Analytics

Glossary

Build a theme — step by step

SEO & social metadata

The seo: block

What gets emitted (page <head>)

Defaults vs. overrides

Listing pages (home, tags, authors)

Image & audio generation

Writing a gen: reference

Tuning a single image

Reuse

Configuration

Providers

API keys

House style (theme system prompt)

Audio readings (podcasts)

What gets read aloud

Turning generation on/off

Cleaning up the cache

Image post-processing

Generating images

Good to know

Authors & personas

Authors

Personas (the writing voice)

Provisioning with `--create`

Run any CLI: the `command` publisher

Community themes (`contrib/themes/`)

`page.html` (a single post)

`index.html` (the post list, and per-tag pages)

The `seo:` block

What gets emitted (page `<head>`)

Writing a `gen:` reference

`command` — run any program (you own the integration)

`mastodon` — post to a Mastodon account you control

`bluesky` — post to a Bluesky account you control

`bridgy` — let Bridgy post for you (no credentials in colophon)

Prompt pack: `seo`

Prompt pack: `draft` / `outline` / `expand`

Prompt pack: `tag`, `social`, `alt-text`, `summary`