docpack Docs
Ctrl K
Decisions / Why docs are plain files in git
✓ UP TO DATE Reviewed Aug 7, 2026 Edit this page

Why docs are plain files in git

decision · docs/why-plain-files.md

Contents 5 sections · ~516 tokens whole page · every section is individually addressable
  1. 1 Status ~5
  2. 2 Context ~88
  3. 3 Options considered ~101
  4. 4 Choice ~49
  5. 5 Consequences ~271

Token figures are estimates — chars/4 (estimate — docpack has no tokenizer). Section run receipts are not shown: docpack’s runs: ledger records a run against a PAGE, never a section, so a per-section outcome would be invented.

1Status

Accepted.

2Context

Every documentation system this project studied died of collapsed reader trust or migration lock-in. Database-backed wikis cannot be grepped, diffed, blamed, or exported losslessly — and coding agents live in files and terminals. This decision ends that argument; the operational consequence is the build runbook.

3Options considered

  1. Database-backed wiki (Confluence/Notion shape) — rich editing, but the agent write path is structurally blocked and export is lossy.
  2. Static site generator with a build service — good output, but the source of truth drifts from the rendered artifact and needs CI to exist.
  3. Plain Markdown + YAML frontmatter in git, one binary, rebuildable artifacts — chosen.

4Choice

Option 3. Git provides history, blame, review, and merge for free; agents read the tree with zero integration; the bundle is a build artifact anyone can regenerate from the files alone.

5Consequences

Easier: agent reads/writes, PR review of docs, lossless export, offline use. Foreclosed: real-time collaborative editing — two people typing into one page at once needs a server owning the document, which is the thing this decision declined.

WYSIWYG authoring was listed as foreclosed too, and that turned out to be wrong. The editor is a browser block editor with real formatting controls; what plain files actually forced was not the absence of one but its shape — it edits a lossless partition of the Markdown and serializes back to it, so a save re-emits only the segments that changed and leaves fences, {{vars}}, and output regions byte-identical. A database-backed editor would not have needed that discipline, and would not have produced a diff a human can review in a PR.

The regenerable-artifact claim above is the one worth re-checking over time, and it currently holds exactly: on 2026-08-07 a local docpack build --public produced build id b521c1d5f2a8, and the hosted rebuild of the same commit produced the identical id.