Documentation

Documentation drifts because it is updated by hand, separately from the code, by whoever remembers. @katforge/imp is already standing at the moment a change is made, and it has already worked out what the change means to write the commit and the changelog. Documentation sync reuses that understanding to keep the prose docs honest.

Why imp is the right place

A standalone job that checks docs against code has to reconstruct the hard part from cold: what changed, and what it means. @katforge/imp already holds both. So the check runs where the change is authored, the author is present to review it, and drift is caught before it merges rather than a day later.

Running it

imp docs analyzes a range of commits and updates the documentation the .imp file points at:

shell

imp docs                    # analyze commits since the last tag
imp docs --since v1.2.0      # from a specific tag or commit
imp docs --yes               # write every proposed edit without prompting

It runs in three passes:

Read the change. It collects the diffs for the range and summarizes what changed that could touch documentation — a new command, a renamed flag, a changed default.
Find the pages. Given that summary and the headings of every candidate page, it selects the ones the change could make inaccurate. Finding nothing is a normal result, and it says so instead of manufacturing an edit.
Propose the edit. For each selected page it proposes a change, shows the diff, and — once you confirm — writes it into the docs tree.

What it changes

docs:mode sets how far it may go:

reconcile (default) — add documentation for new surface and correct statements the change contradicts (a renamed field, a changed status code, a dropped flag). Bounded to what the diff proves.
additive — only add documentation for genuinely new surface; never touch existing prose.

Neither mode restyles or reflows prose that is still accurate — documentation sync verifies, it does not rewrite for taste. A page that is already correct comes back as NO CHANGE.

Where edits land

Edits are written into the docs tree and left uncommitted for your review — the same posture as the changelog imp release proposes before you accept it. Nothing is committed on your behalf.

Docs commonly live in a different repo from the code — a project ships its source in one repo and its reference under a docs site in another. docs:path is resolved relative to the repo root and may point at a sibling repo, so @katforge/imp stages the doc edits there and you commit them alongside the code change (or ship both with imp fleet).

Configuration

Documentation sync is driven entirely by the .imp file. A project points at its documentation and @katforge/imp does the rest.

JSON

{
  "docs:include": [ "reference", "hearth" ],
  "docs:mode": "reconcile",
  "docs:path": "../docs.example.com/content",
  "docs:release": true
}

Key	Purpose
`docs:path`	Where the documentation lives, relative to the repo root. Required. May point at a sibling repo.
`docs:include`	Subfolders under `docs:path` to consider. Omit to scan every markdown file.
`docs:mode`	`reconcile` (default) or `additive` — see above.
`docs:release`	When `true`, `imp release` runs the docs pass over the released commits, before the squash, so the pass sees the real changes.

Run imp setup to fill these in interactively. See Configuration for the full key reference.

When it runs

By default documentation sync runs only when you invoke imp docs. Set docs:release to true to also run it during imp release — batched, infrequent, and paired with the changelog, so the documentation pass is not a tax on every commit.

← PreviousChangelog Next →Comparison