As a somewhat prolific open-source author over the past 25 years, I maintain hundreds of Rust crates, Ruby gems, Python packages, and so on. One of the painful aspects of large projects consisting of dozens of packages has been the individual READMEs for each package, with lots of repetitive elements but also a great deal of necessary package-specific variation.

Now, before anyone asks, I don't want to just have an LLM generate my READMEs. People are increasingly sensitive to AI slop, and that certainly starts with a project's README: slop is readily recognizable through LLMs' lack of good judgment on README contents. More isn't always better: "If I had more time, I would have written a shorter letter" and all that.

I believe that at this point given widespread, complex formatting of READMEs, what with CI badges, headers, footers, tables, images, inline HTML, etc, etc, we've in any case realistically drifted quite far from the original human-readable vision of Markdown as such. Perhaps, then, we ought to consider whether README.md files really should not best be treated just as built documentation outputs, not as sacred artisanal relics to be read on a 80×24 monochrome screen?

Along these lines, I present Readmer, a first attempt at a proper README compiler. Readmer composes README.md files from Liquid or Jinja2 templates stored in an unobtrusive .config/readmer/ project directory, with lots of nifties such as support for rendering CSV files as Markdown tables. I hope it comes useful to someone!

    $ cargo binstall -y readmer

    $ cargo new myproject && cd myproject
    $ mkdir -p .config/readmer/
    $ echo '# {{ package.name | capitalize }}' > .config/readmer/README.md.liquid
    $ readmer render > README.md

RIP tech journalist John C. Dvorak (1946–2026)

Comments