readwright

Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers.

• Installation
• Quick start
• Template helpers
• Configuration
• pre-commit and GitHub Actions
• Agent skill
• Contributing
• License

Installation

pip install readwright

Or with uv:

uv tool install readwright

Quick start

cd my-repo
readwright init      # writes readme.yaml + README.md.j2 (autodetects owner/repo, name, license, ...)
readwright render    # writes README.md (--watch to re-render on change, -o - for stdout)
readwright check     # exit 1 with a diff if README.md is stale (use as a pre-commit hook / in CI)
readwright badges    # list badge presets
readwright blocks    # list overridable blocks and partials
readwright show partials/install.md.j2   # print a packaged template to copy and tweak

Already have a README? readwright init --from-readme moves its body into the template so nothing is lost, then takes over README.md. Prefer pyproject.toml? readwright init --pyproject writes the config to [tool.readme].

README.md.j2 extends the packaged base.md.j2 and overrides only what it needs:

{% extends "base.md.j2" %}

{% block usage %}
## Usage

{{ screenshot("main", width=600) }}

Run `{{ project.name }} --help`.
{% endblock %}

See examples/ for a kitchen-sink project using every helper, plus Rust, Go, .NET and Node examples showing how the install section adapts per language.

Template helpers

To add a badge to the top row without touching the config list, fill the badges_extra hook (there is a donate_extra too):

{% block badges_extra %} {{ shield("docs", "latest", "success", link=gh_link("wiki")) }}{% endblock %}

Badge presets: pypi, pypi-downloads, python, license, ci, codecov, npm, github-release, github-stars, pre-commit, ruff, version, modrinth, curseforge, hacs, ha-version, plus donation presets kofi, buymeacoffee, github-sponsors, patreon, paypal. Add your own under badges_custom; set badges_style: flat-square (or pass style= to any badge helper) to restyle them all.

Blocks in base.md.j2: header, badges, donate, toc, screenshots, install, usage, extra, contributing, license. Any packaged partial can be shadowed by a file of the same name under templates/partials/ in the repo (or ~/.config/readwright/templates/ for all your repos).

Image helpers emit plain markdown by default (dark/light pairs use GitHub's #gh-light-mode-only/#gh-dark-mode-only fragments instead of <picture>), and only fall back to HTML when you ask for something markdown can't do, like a width=. Set screenshots.style: html to always get <img>/<picture>/<table> output, or pass html=True to unsplash()/banner:.

Configuration

readme.yaml in the repo root (or [tool.readme] in pyproject.toml); see examples/config-only/readme.yaml for every key, annotated. Everything is optional; metadata is autodetected from the git remote, the LICENSE file and whichever manifest the project has: pyproject.toml, package.json, Cargo.toml, go.mod, *.csproj, Gradle (gradle.properties mod metadata for Minecraft mods), hacs.json or a Flow Launcher plugin.json. The install section adapts to the project type.

template: README.md.j2
templates: [../shared-readme-templates, "pkg:my_org_templates"]   # extra template search paths
output: README.md
strict: false                     # missing screenshot -> error instead of warning
allow_exec: false                 # let cli_help() run commands during render
badges_style: flat-square         # optional shields.io style for every badge
related: [{repo: other-tool, description: Sibling project}]   # for related_repos()
banner: {unsplash: photo-1518770660439-4636190af475, credit: Alexandre Debiève, user: alexkixa}
screenshots: {dir: docs/screenshots, width: 720, style: markdown}   # style: html for width/alignment
badges: [pypi, python, license, {preset: ci, workflow: test.yml}, {shield: {label: Docs, message: latest, color: success}}]
badges_custom:
  discord: {label: Discord, message: chat, color: 5865F2, link: https://discord.gg/xyz}
donate: [kofi, github-sponsors]
donate_handles: {kofi: yourname, github-sponsors: yourname}
project: {name: ..., owner: ..., repo: ..., tagline: ..., pypi: ..., npm: ..., license: ..., ci_workflow: ...}
vars: {anything: you like}

Put the values you repeat across repos (donation handles, owner, custom badges) in ~/.config/readwright/config.yaml; readwright init bakes them into each new readme.yaml so rendering stays reproducible in CI. readwright render --user-config merges them ad hoc.

pre-commit and GitHub Actions

# .pre-commit-config.yaml
- repo: https://github.com/Garulf/readwright
  rev: v0.4.0
  hooks:
    - id: readwright-check

# .github/workflows/ci.yml
- uses: Garulf/readwright@v0.4.0
  with:
    mode: check     # or render

Agent skill

The repo ships an agent skill at .agents/skills/readwright/ that teaches coding agents (Claude Code, Codex, Copilot CLI, Gemini CLI, ...) the render/check workflow, the config keys and every template helper, so they edit README.md.j2 instead of the generated README.md. Claude Code picks it up from this repo automatically via .claude/skills/readwright; the same directory is bundled inside the wheel, so any project can install it:

readwright skill --install                       # copies it to ./.agents/skills/readwright
readwright skill --install --dest ~/.claude/skills   # or a user-level skills directory
readwright skill                                 # just print where the bundled copy lives

Contributing

Issues and pull requests are welcome at Garulf/readwright.

License

MIT