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.