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 Rust library.
• Build README.md from Liquid/Jinja2/etc templates in .config/readmer/.
• 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 all file types recognized by Linguist.
• 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.88+ (2024 edition)

⬇️ Installation

Installation of the CLI via Cargo

cargo install readmer --locked --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 render > README.md

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