Readmer: READMEs Made Simple^™

Readmer composes README.md files from Liquid or Jinja2 templates.

_{[Features] |
[Prerequisites] |
[Installation] |
[Examples] |
[Reference] |
[Development]}

✨ Features

Available both as the command-line tool readmer and a polyglot library.
Build README.md from Liquid/Jinja2/etc templates in .config/readmer/.
Keeps you in charge: use as little or as much code generation as you like.
Ingests package metadata from Dart, NPM, Python, Ruby, and Rust projects.
Embeds {% render 'table.csv' %} partials as Markdown tables.
Embeds {% render 'data.json' %} as pretty-printed JSON code blocks.
Embeds {% render 'example.rs' %} as syntax-highlighted code blocks.
Supports syntax highlighting for 800+ file types recognized by Linguist.
Includes numerous builtin partials for rendering e.g. header/footer badges.
Polyglot software ^_(soon!) available for Dart, Python, Ruby, Rust, and TypeScript.
Cuts red tape: 100% free and unencumbered public domain software.

⬇️ Installation

Installation of the CLI

Installation via Cargo Binstall

cargo binstall -y readmer

Installation via Cargo

cargo install readmer --locked --features=cli

Installation of the Library

Installation for Rust from Crates.io

Installation from Crates.io

cargo add --dev readmer

Installation for JavaScript/TypeScript from NPM

Installation from NPM

npm install --save-dev readmer.js
bun add --dev readmer.js
pnpm add --save-dev readmer.js
yarn add --dev readmer.js

Installation for Dart from Pub.dev

Installation from Pub.dev

dart pub add dev:readmer
flutter pub add dev:readmer

Installation for Python from PyPI

Installation from PyPI

pip install -U readmer
uv add --dev readmer
poetry add --group dev readmer
pdm add -d readmer

Installation for Ruby from RubyGems

Installation from RubyGems

gem install readmer
bundle add readmer --group development

👉 Examples

Tip

For a concrete showcase example, refer to the Edky repository.

Initializing the Template

Execute this in your project's workspace (aka top-level) directory, to create an initial .config/readmer/README.md.liquid template:

mkdir -p .config/readmer/
echo '# {{ package.name | capitalize }}' > .config/readmer/README.md.liquid

Building the `README.md` File

In your project's workspace directory, this will render the .config/readmer/README.md.liquid template and write the output to ./README.md. In subdirectories under your workspace, it will render the corresponding .config/readmer/.../README.md.liquid template if one exists.

readmer render > README.md

Examining Template Variables

In any project directory, you can examine the template variables available to you using readmer describe:

readmer describe

📚 Reference

Command-Line Interface

$ readmer
Readmer composes README.md files from Jinja2 or Liquid templates

Usage: readmer [OPTIONS] [COMMAND]

Commands:
  describe  Describe the current project's metadata in JSON format
  render    Render a template file to standard output
  help      Print this message or the help of the given subcommand(s)

Options:
      --color <COLOR>  Set the color output mode [default: auto] [possible values: auto, always, never]
  -d, --debug          Enable debugging output
      --license        Show license information
  -v, --verbose...     Enable verbose output (may be repeated for more verbosity)
  -V, --version        Print version information
  -h, --help           Print help (see more with '--help')

`readmer describe`

$ readmer describe --help
Describe the current project's metadata in JSON format

Usage: readmer describe [OPTIONS] [PROJECT] [PROPERTY]

Arguments:
  [PROJECT]   The project directory to use [default: $PWD]
  [PROPERTY]  The project property to output [default: all properties]

Options:
      --color <COLOR>          Set the color output mode [default: auto] [possible values: auto, always, never]
  -W, --workspace <WORKSPACE>  The workspace directory to use [default: $WORKSPACE]
  -d, --debug                  Enable debugging output
  -o, --output <OUTPUT>        The output format to use [default: json]
  -D, --define <DEFINES>       Define a variable and value to pass to the templating engine
  -v, --verbose...             Enable verbose output (may be repeated for more verbosity)
  -h, --help                   Print help

`readmer render`

$ readmer render --help
Render a template file to standard output

Usage: readmer render [OPTIONS] [INPUTS]...

Arguments:
  [INPUTS]...  The template files to render [default: $WORKSPACE/.config/readmer/.../README.md.liquid]

Options:
      --color <COLOR>          Set the color output mode [default: auto] [possible values: auto, always, never]
  -W, --workspace <WORKSPACE>  The workspace directory to use [default: $WORKSPACE]
  -d, --debug                  Enable debugging output
  -e, --engine <ENGINE>        The templating engine to use [default: auto]
  -D, --define <DEFINES>       Define a variable and value to pass to the templating engine
  -v, --verbose...             Enable verbose output (may be repeated for more verbosity)
  -h, --help                   Print help

Template Languages

Readmer currently supports two template languages, with Liquid being the default as well as the more featureful implementation:

Liquid, using @cobalt-org's liquid engine written in Rust
Jinja2, using @mitsuhiko's minijinja engine written in Rust

Template Syntax

Outputting Properties

The title of this project is "{{ project.title }}"

Rendering Builtin Partials

{% render 'badge/unlicense' %}

Rendering Custom Partials

This will look for a custom partial at mydir/myfile.md in your workspace:

{% render 'mydir/myfile.md' %}

Rendering Code Blocks

{% render 'example.rs' %}

Rendering JSON Data

{% render 'data.json' %}

Rendering CSV Tables

{% render 'table.csv' %}

Template Variables

Variable	Type	Sample
`{{ project.label }}`	`string`	`"Readmer"`
`{{ project.title }}`	`string`	`"Readmer: READMEs Made Simple"`
`{{ project.summary }}`	`string`	`"Readmer composes README.md files from templates."`
`{{ subproject.label }}`	`string`	`"Readmer.py"`
`{{ subproject.title }}`	`string`	`"Readmer.py: Readmer for Python"`
`{{ subproject.summary }}`	`string`	`"Readmer composes README.md files from templates."`
`{{ github.account.handle }}`	`string`	`"artob"`
`{{ github.account.link }}`	`string`	`"https://github.com/artob"`
`{{ github.repository.slug }}`	`string`	`"artob/readmer"`
`{{ github.repository.link }}`	`string`	`"https://github.com/artob/readmer"`
`{{ github.repository.url }}`	`string`	`"https://github.com/artob/readmer.git"`
`{{ package }}`	`object`	See package properties
`{{ package.language }}`	`object`	See language properties

Package Properties

Property	Type	Rust	Dart	JS/TS	Python	Ruby
`package.name`	`string`	`name`	`name`	`name`	`name`	`name`
`package.version`	`string`	`version`	`version`	`version`	`version`	`version`
`package.author`	`string`	`authors[0]`	N/A	`author`	`authors`	`authors[0]`
`package.authors`	`[string]`	`authors`	N/A	`[author]`	`authors`	`authors`
`package.description`	`string`	`description`	`description`	`description`	`description`	`description`
`package.homepage`	`string`	`homepage`	`homepage`	`project.urls.Homepage`	`homepage`	`homepage`
`package.keywords`	`[string]`	`keywords`	`topics`	`keywords`	`keywords`	N/A
`package.categories`	`[string]`	`categories`	N/A	N/A	`classifiers`	N/A
`package.license`	`string`	`license`	TODO	`license`	`license`	`licenses[0]`
`package.licenses`	`[string]`	`[license]`	TODO	`[license]`	`[license]`	`licenses`
`package.repository`	`string`	`repository`	`repository`	N/A	`project.urls.Repository`	`metadata.source_code_uri`
`package.metadata`	`object`	`metadata`	TODO	TODO	TODO	`metadata`
`package.language`	`object`	`{...}`	`{...}`	`{...}`	`{...}`	`{...}`

Language Properties

Property	Type	Rust	Dart	JS/TS	Python	Ruby
`package.language.name`	`string`	`"rust"`	`"dart"`	`"js"`	`"python"`	`"ruby"`
`package.language.label`	`string`	`"Rust"`	`"Dart"`	`"JavaScript"`	`"Python"`	`"Ruby"`
`package.language.version`	`string`	`"1.88"`	`"3.11"`	`null`	`"3.14"`	`"4.0"`
`package.language.minimum_version`	`string`	`"1.88"`	`"3.11"`	`null`	`"3.14"`	`"4.0"`
`package.language.maximum_version`	`string`	`null`	`null`	`null`	`null`	`null`

Note

The language versions shown above are Readmer's own requirements. When building your own README.md, Readmer will populate these properties from your own project's specified language version requirements.

Builtin Partials

Partial	Summary
`{% render 'badge/unlicense' %}`	A 'Public Domain' badge that links to unlicense.org
`{% render 'footer/share' %}`	A set of badges for sharing to X, Reddit, HN, Facebook, and LinkedIn
`{% render 'header/badges/dart' %}`	Some common above-the-fold badges for Dart projects
`{% render 'header/badges/js' %}`	Some common above-the-fold badges for JavaScript projects
`{% render 'header/badges/python' %}`	Some common above-the-fold badges for Python projects
`{% render 'header/badges/ruby' %}`	Some common above-the-fold badges for Ruby projects
`{% render 'header/badges/rust' %}`	Some common above-the-fold badges for Rust projects
`{% render 'header/badges/ts' %}`	Some common above-the-fold badges for TypeScript projects
`{% render 'header/toc' %}`	Quick jump links to common Table of Contents (ToC) sections
`{% render 'section/development' %}`	A shrink-wrap 'Development' section with Git instructions

👨‍💻 Development

git clone https://github.com/artob/readmer.git

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
.config		.config
.github		.github
dart		dart
data		data
js		js
python		python
ruby		ruby
rust		rust
.gitattributes		.gitattributes
.gitignore		.gitignore
AUTHORS		AUTHORS
CHANGES.md		CHANGES.md
CITATION.cff		CITATION.cff
CREDITS.md		CREDITS.md
Makefile		Makefile
README.md		README.md
Rakefile		Rakefile
UNLICENSE		UNLICENSE
VERSION		VERSION
dist-workspace.toml		dist-workspace.toml

Folders and files

Latest commit

History

Repository files navigation

Readmer: READMEs Made Simple™