Readmer: READMEs Made Simple™

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

✨ Features

Available both as the command-line tool readmer and a Rust 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.
Supports opting out of any feature using comprehensive feature flags.
Adheres to the Rust API Guidelines in its naming conventions.
Polyglot software also (soon!) available for Dart, Python, Ruby, and TypeScript.
Cuts red tape: 100% free and unencumbered public domain software.

🛠️ Prerequisites

Rust 1.88+ (2024 edition)

⬇️ Installation

Installation of the CLI

Installation via Cargo Binstall

cargo binstall -y readmer

Installation via Cargo

cargo install readmer --locked --features=cli

Downloading Release Tarballs

wget https://github.com/artob/readmer/releases/download/0.1.0/readmer-aarch64-apple-darwin.tar.xz
wget https://github.com/artob/readmer/releases/download/0.1.0/readmer-aarch64-unknown-linux-gnu.tar.xz
wget https://github.com/artob/readmer/releases/download/0.1.0/readmer-x86_64-apple-darwin.tar.xz
wget https://github.com/artob/readmer/releases/download/0.1.0/readmer-x86_64-pc-windows-msvc.zip
wget https://github.com/artob/readmer/releases/download/0.1.0/readmer-x86_64-unknown-linux-gnu.tar.xz

Installation of the Library

Installation from Crates.io

cargo add --dev readmer

Configuration in `Cargo.toml`

Enable all default features:

[dev-dependencies]
readmer = { version = "0" }

Enable only specific features:

[dev-dependencies]
readmer = { version = "0", default-features = false, features = ["alloc"] }

👉 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

Importing the Library

use readmer::*;

📚 Reference

docs.rs/readmer

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

👨‍💻 Development

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

readmer 0.1.0