shard-wiki/research/260614-ikiwiki-deep-dive/findings.md

# ikiwiki — deep dive (findings)

**Date:** 2026-06-14 · **Source:** SHARD-WP-0003 T4 · **Subject:** ikiwiki, Joey Hess's
VCS-backed wiki compiler.

## Why this dive

The forge-wiki dive (T5) established *git-IS-the-store* for hosted Markdown wikis. ikiwiki
takes the same git-canonical source but adds two ideas shard-wiki cares about directly:
**compile-to-static** (the wiki is *built*, not served from a DB) and **git-distributed
federation** (wiki instances clone, pull, push, and **ping** each other). It is referenced
in `research/260608-federation-concepts/`; here we go into the model.

## 1. The wiki-compiler model

ikiwiki is fundamentally a **compiler**: input is a directory of **source pages** (Markdown
by default; also other formats) held in a **version-control repo**; output is a tree of
**static HTML**. A rebuild is triggered by a **VCS post-commit/post-update hook**, so:

- **The VCS repo is canonical**; the HTML is *derived build output* (regenerable, disposable).
- **Web edits are commits.** The CGI edit interface writes the change *into the repo* (a
  commit) and triggers a rebuild — so browser edits and `git push` edits converge on one
  history. (Same convergence as forge wikis, but here the canonical store is *your* git repo,
  not a forge's.)
- **VCS-agnostic**: git is usual, but svn/bzr/mercurial/darcs are supported via a VCS
  plugin layer — an early "pluggable backend behind a stable interface" (adapter-contract
  echo).
- **Plugins** (Perl) provide directives, feeds, auth (`openid`), and the federation hooks
  below.

## 2. Git-distributed federation + the pinger

Because the source is an ordinary VCS repo, ikiwiki instances federate the way *git* does:

- **Clone-and-diverge**: you can `git clone` a wiki, edit offline, and `push`/`pull` between
  instances — **multiple wiki clones that reconcile via git merge**. A wiki is a branch-space
  (UC-33).
- **`pinger` / `pingee` plugins**: an instance can send an **XML-RPC ping** to another
  ikiwiki when it changes, prompting the other to **pull and rebuild** — a lightweight
  **subscribe/notify** primitive over the git-distributed mesh (UC-31).
- **`aggregate` plugin**: pulls external **RSS/Atom feeds** into the wiki as pages — an
  inbound projection of remote content.

So ikiwiki is *federation by git plus a ping* — distinct from fedwiki's fork/journal
(UC-72) and from Wikibase's query-time `SERVICE` (UC-74): a **third federation flavor**,
*VCS-replication federation with change notification*.

## 3. Static output as a publish/projection target

The compiled static HTML is a **read-only, regenerable projection** of the source:

- It is a natural **outbound publish target** (UC-56): render the union (or a shard) to a
  static site for hosting/backup, no server needed.
- It is also the **read-only backup** end (UC-37): a static snapshot that survives the engine.

The key shard-wiki framing: **source (git Markdown) is the attachable shard; static HTML is a
derived projection** — never confuse the build output for the canonical content.

## 4. Capability profile

| Dimension (synthesis spectrum) | ikiwiki |
|--------------------------------|---------|
| Attachment mode | **file-store** (VCS-backed git Markdown source) |
| Addressing granularity | page = source file; path = identity |
| Content identity | path/filename (placement-bound) |
| Structure | directory tree of Markdown source + directives |
| History | **native VCS (git) history** |
| Merge model | **git** (clone/pull/push/merge across instances) |
| Native query | none; directives + plugins compute derived pages at build |
| Translation | Markdown source → static HTML (build-time render) |
| Write granularity | **file (page)** per commit |
| Operational envelope | a compiler + VCS hook; static hosting for output |
| Access grant | VCS/file perms; `openid` for web edits |
| Content opacity | transparent Markdown |
| Provenance | git author/timestamp; aggregated feeds carry source |
| Federation | **git replication + XML-RPC ping**; RSS aggregation |

## 5. INTENT mapping

### Reinforcements

- **Git-canonical Markdown source** = the home case (shared with forge wikis UC-76/40):
  attach the source repo, adopt its git log as the journal, write by commit.
- **Coordination layer is git** (INTENT): ikiwiki's whole federation *is* git replication +
  a ping — the most literal realization of "Git-addressable coordination layer."
- **Projection vs canonical**: compile-to-static cleanly separates **canonical source** from
  **derived output** — exactly shard-wiki's projection principle (static HTML = a lazy/cache
  projection that is regenerable, never the source of truth).
- **Graceful degradation / publish**: static output is the trivial read-only backup and
  outbound publish target (UC-37/UC-56).
- **Subscribe/notify mechanism, not policy**: the pinger is a *mechanism* (notify a peer to
  pull); *which* peers, when, and conflict policy stay configurable.

### Divergences (boundaries / notes)

- ikiwiki is mostly a **reinforcement** of git-canonical-Markdown (UC-76) — its *new*
  contributions are (a) **compile-to-static** as a distinct projection/publish direction and
  (b) the **git-distributed-clone + ping** federation flavor. The static output is *not* a
  shard to attach (it's derived); attach the **source repo**.
- VCS-agnostic backend layer is an interesting adapter-contract echo, but for shard-wiki the
  git case dominates.

### What to keep

1. **Source-repo-as-shard, static-output-as-derived-projection** — never attach the build
   output as canonical (UC-79; relates UC-37/UC-56).
2. **Git-replication + change-ping** as a named federation flavor beside fork/journal
   (fedwiki) and query-SERVICE (Wikibase) — a **subscribe/notify over a git mesh** (UC-31/UC-33).
3. **Inbound feed aggregation** (RSS/Atom → pages) as an inbound projection pattern.

## 6. UC seed

| # | Seed | Disposition |
|---|------|-------------|
| UC-79 | Attach a git-backed **compile-to-static** wiki — the **git Markdown source is the shard**, compiled **static HTML is a derived publish/projection**; participate in **git-distributed clone federation** with change-**pings** | **new** |
| — | XML-RPC pinger = subscribe/notify over a git mesh | enrich **UC-31** |
| — | render union/shard to a static site (publish) | enrich **UC-56** |
| — | static HTML as read-only regenerable backup | enrich **UC-37** |
| — | wiki as a git branch-space; clones reconcile via merge | enrich **UC-33** |

## 7. Architecture notes for SHARD-WP-0002

- **T4 (federation):** record **git-replication + change-ping** as a federation flavor — peers
  hold git clones, reconcile via merge, and notify with a ping to pull/rebuild. Distinct from
  fedwiki fork/journal and Wikibase `SERVICE`; complements the "Git-addressable coordination
  layer" mandate most literally.
- **T6 (publish/projection):** **compile-to-static** is the canonical *outbound* projection —
  source (git) is canonical, static HTML is a regenerable derived view (publish/backup
  target). Reinforces projection-vs-canonical separation.
- **Attach binding (T14):** attach the **source repo** (git Markdown), not the build output;
  shares the forge-wiki / `wiki/`-subdir git+Markdown adapter (parameterized by repo/path).

## 8. Open questions

1. Is the **pinger** (notify-peer-to-pull) modeled as shard-wiki's own subscribe/notify
   primitive, or only recognized when bridging two ikiwiki instances?
2. Does shard-wiki ever *drive* a compile-to-static **publish** of the union (act as the
   ikiwiki-like compiler), or only attach existing ikiwiki source repos? (UC-56 scope.)
3. Is **feed aggregation** (RSS→pages) an inbound projection mode shard-wiki offers generally
   (a feed-shard), or an ikiwiki-internal feature?

## 9. Sources

- ikiwiki.info — *ikiwiki* overview, *rcs* (VCS backends), *plugins* (`pinger`/`pingee`,
  `aggregate`, `openid`), *setup* / post-commit hooks
- prior: `research/260608-federation-concepts/` (ikiwiki reference);
  `research/260614-forge-wikis-deep-dive/` (git-canonical Markdown contrast)

## 10. Traceability

New UC **UC-79** carries the marker **⊟** in the wikiengines column of
`spec/UseCaseCatalog.md`. Enriched: UC-31, UC-56, UC-37, UC-33. Architecture cross-refs:
SHARD-WP-0002 T4 (git-replication+ping federation), T6 (compile-to-static publish), T14.