colophon-skills

colophon

Write it once. Own it forever. Publish anywhere.

A static site generator for bloggers — a simple CLI that turns a folder of Markdown (or any other supported source, such as an Obsidian vault) into a fast, themed blog. Built on a principle of freedom: own your words, host them anywhere (Cloudflare Pages, an S3/R2 bucket, a git branch, or any command), and federate them (RSS/Atom/JSON feeds, IndieWeb microformats) so your writing is never tied to a platform.

Features

• Markdown in, static site out — md-dir and Obsidian-vault sources; code highlighting, maths (KaTeX), diagrams (Mermaid), callouts, wikilinks, embeds, series, tags and a glossary.
• Themes — embedded press (with broadsheet/gazette variants), default and minimal, plus community themes in contrib/themes/; per-environment overrides; progressive enhancement, so every theme works with JavaScript off.
• Static search — a fully static, sharded index (no server, no third party) with a tiny browser reader and optional fuzzy matching. A reusable module under search/.
• Rich media — embed video/audio with plain image syntax (![](demo.mp4) → a player) and attach downloadable files (scripts, datasets, PDFs) to a post — copied/routed like images.
• AI media generation (opt-in) — generate images from a gen:<prompt> reference and spoken (TTS) audio readings of posts, via configured providers (Google, OpenAI-compatible, MiniMax). Results are content-addressed and cached; secrets stay in the environment.
• Feeds & SEO — RSS, Atom and JSON feeds (podcast-style enclosures for audio/attachments); canonical / Open Graph / Twitter / JSON-LD metadata; sitemap and robots.
• Authors & personas — a shown author (byline + h-card, Gravatar supported) vs a hidden persona (a reusable writing voice); persona context emits write-as context for an AI.
• AI authoring skills — optional Claude Code / opencode skills that drive colophon to write, edit, cross-link and publish — the engine supplies the voice, never an LLM or your secrets.
• Pluggable publishers — Cloudflare Pages, Cloudflare R2 / S3 (SigV4), local mirror, git branch, or any command. Incremental: only changed files upload, orphans are pruned.

Install

Download a prebuilt binary — grab the archive for your OS/arch from the Releases page, extract it, and put colophon on your PATH:

# example: Linux x86-64 (swap in your platform's asset name)
curl -sSL https://github.com/jmylchreest/colophon/releases/latest/download/colophon_VERSION_linux_amd64.tar.gz | tar -xz
sudo mv colophon /usr/local/bin/

Prebuilt for Linux, macOS and Windows on amd64/arm64; each release lists checksums.txt.

Or with Go (1.26+): go install github.com/jmylchreest/colophon/cmd/colophon@latest, or build from a clone — git clone … && cd colophon && go build -o colophon ./cmd/colophon.

Quick start

colophon init mysite && cd mysite
colophon new post "Hello World"   # scaffold a post in content/
colophon serve                    # preview at http://localhost:8080 with live reload
colophon build                    # render the static site to ./public

colophon init writes an annotated colophon.yaml. Run colophon <command> --help for any of: init, new, build, serve, publish, themes, authors, persona, sources, posts, search, doctor, env.

Configure & publish

A minimal colophon.yaml — a site, a theme, a feed, and where to deploy:

sites:
  - id: main
    title: "My Site"
    base_url: "https://example.com"
    theme: press
    search: lexical
    federation:
      feeds: [rss, atom, json]

publishers:
  - id: cf
    driver: cloudflare-pages
    project: my-site
    account_id: "{env:CLOUDFLARE_ACCOUNT_ID}"   # non-secrets can interpolate the environment

environments:
  - name: production
    publish: [cf]
    allow_publish: false        # safety latch — deploying requires --allow-publish

Deploy credentials are never written in config — they're read from the environment, so a token never passes through the YAML (or an AI agent). Set the ones your publisher needs, then:

export CLOUDFLARE_API_TOKEN=…        # Account → Cloudflare Pages → Edit
colophon publish --env production --allow-publish --create   # --create provisions the target

Credentials by publisher: