artob/readmer
🦀 Readmer composes README.md files from Liquid or Jinja2 templates: authoring READMEs made simple without need for AI slop! - artob/readmer
6 stars · 1 forks · Rust Topics: markdown, readme, jinja2, liquid, codegen
README
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 TipFor 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
NoteThe 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