Readmer

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

[Features] | [Prerequisites] | [Installation] | [Examples] | [Reference] | [Development]

✨ Features

• Available both as the command-line tool readmer and a Rust library.
• Build README.md from Jinja2/Liquid/etc templates in .config/readmer/.
• 100% pure and safe Rust with minimal dependencies and no bloat.
• Designed for #![no_std] environment compatibility from the get-go.
• Supports opting out of any feature using comprehensive feature flags.
• Adheres to the Rust API Guidelines in its naming conventions.
• Polyglot software also available for Dart, Python, Ruby, and TypeScript.
• Cuts red tape: 100% free and unencumbered public domain software.

🛠️ Prerequisites

• Rust 1.85+ (2024 edition)

⬇️ Installation

Installation of the CLI via Cargo

cargo install readmer --features=cli

Installation of the Library via Cargo

cargo add --dev readmer

Installation of the Library 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

Building the README.md File

readmer build

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:
  build     Build ./README.md from templates in $WORKSPACE/.config/readmer/
  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 build

$ readmer build --help
Build ./README.md from templates in $WORKSPACE/.config/readmer/

Usage: readmer build [OPTIONS] [OUTPUTS]...

Arguments:
  [OUTPUTS]...  The output files to build [default: ./README.md]

Options:
      --color <COLOR>  Set the color output mode [default: auto] [possible values: auto, always, never]
  -d, --debug          Enable debugging output
  -v, --verbose...     Enable verbose output (may be repeated for more verbosity)
  -h, --help           Print 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]
  -o, --output <OUTPUT>  The output format to use [default: json]
  -d, --debug            Enable debugging output
  -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.j2]

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: minijinja]
  -D, --define <DEFINE>        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