Readmint

Design your README. Any font, any data, any style.

Readmint renders README graphics from designs you make yourself: your own layout, your own fonts, GIFs and animation, bound to live data through placeholders — including a contribution calendar you can shape any way you like. A GitHub Action in your own repository renders them as SVG, PNG, animated WebP, APNG or GIF and keeps them current.

The Year ring section of the Year Ring profile template, in its light and dark variant (your browser picks one). It is a plain design in the public format, rendered by the same renderer as everything else, bound to the GitHub data of the account the Action runs for. Status: early development.

What it does

• A design format of your own: layers, groups, assets, animation, all in a versioned YAML or JSON file (design format, renderer). Nothing is predefined: every built-in visual is a template in this format (components and templates).
• Data through placeholders: GitHub first, private contributions through your own token, with safe expressions and no eval (expressions, data sources, GitHub data).
• Your fonts: bring your own; a font whose licence forbids embedding is never embedded (fonts and licensing).
• Outputs GitHub shows: self-contained SVG without scripts or external references, or PNG, animated WebP, APNG and GIF (output formats, asset loading).
• A GitHub Action that renders in your repository on a schedule (GitHub Action).
• A visual editor and a CLI that preview with the very same renderer, so the preview is the output (editor, CLI).

Quick start

1. Copy a design, with its fonts, from the examples repository (ready-to-copy workflows for the Year Ring, Horizon and Pinscreen profiles) or from the starter templates.

2. Save a workflow as .github/workflows/readmint.yml, with an exact release tag instead of vX.Y.Z:

   name: Readmint
   on:
     schedule:
       - cron: "17 3 * * *"
     workflow_dispatch:
   permissions:
     contents: write
   concurrency:
     group: readmint
     cancel-in-progress: false
   jobs:
     render:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - uses: MrLarkyy/Readmint@vX.Y.Z
           with:
             designs: |
               readmint/designs/card.yaml

3. Run it once with Run workflow, and paste the <picture> snippet from the log group README snippet into your README.

Every input, the permissions and the errors are in the GitHub Action page; the full path is in getting started, and troubleshooting lists what goes wrong.

Documentation

The user guide is the wiki, generated from docs/ (how it is published):

start	design	run
Getting started	Design format, Expressions, Components and templates	GitHub Action, CLI, Editor
Troubleshooting	Fonts and licensing, Data sources, GitHub data	Renderer, Output formats, Asset loading

Contributors: golden tests and wiki publishing.

Licence

Readmint is released under the MIT licence. The fonts bundled with it keep their own licences (SIL Open Font License), which sit next to the font files in their folders.

The Unicode tables in packages/fonts and the CLDR locale tables in packages/expr are under the Unicode License v3.