readme-gen
Documentation that cannot quietly lie about its numbers.
- Language
- Rust 2021
- Size
- ≈7.7k LOC
- Tests
- 48
- Dependencies
- 0
- Commits
- 25
- Updated
- Oct 2026
System
How it fits together.
A simplified view of the moving parts, not a full architecture diagram.
- 01Scanfiles, languages, deps, git
- 02Facts + hashone reviewable JSON
- 03readme.ymlhuman-authored meaning
- 04Renderdeterministic output
- 05checkfail on drift
Context
Why it exists.
README numbers are typed by hand and decay silently. Structure drifts the same way. readme-gen splits the document into scanned facts, reviewable meaning, and deterministic rendering, then turns drift into a failed check.
Approach
- 01Scan the repository for counts, sizes, languages, directories, dependencies, entry points, tests, and git metadata.
- 02Read human-authored meaning from readme.yml — prose, section order, annotations — instead of guessing it.
- 03Render deterministically from the same facts and configuration, so a rebuild produces the same document.
- 04Embed a SHA-256 facts hash in the generated README; `check` fails when the repository no longer matches the text.
Inside the repository
What is actually in there.
Six subcommands
scan, plan, build, check, init, and help. The CLI is the whole product; there is no service to run.
Five presets
Library, CLI, App, Dataset, and Showcase share one section graph, so structure is not reinvented per project.
Zero external crates
The crate compiles with no third-party dependencies; the Cargo lock file contains only itself.
48 tests
Forty unit tests and eight integration tests cover scanning, rendering, validation, and the facts hash.
Constraints & notes
The repository's own README is generated by the tool — the most honest demo available. The bundled legacy Python template is retired, and benchmark figures in the docs are author-measured rather than independently reproduced.