github-cool-readme

Animated SVG cards for a GitHub profile README, generated by a scheduled GitHub Action and published on a cards branch of your profile repo, so they don't add to its history:

• Summary: commits, pull requests created and reviewed, issues and stars, for the last 12 months and all time; share of active days.
• Languages: each repo's language mix weighted by your commits there.
• Weekly rhythm: your contributions per weekday over the last 12 months, with your busiest and quietest day and how much is on weekdays.
• Notable contributions: your merged (and open) pull requests to other people's public projects, by stars.
• Streaks (streaks, disabled by default): your current and longest streak, active days, and your best day and month, over the last 12 months.
• About (about, disabled by default): a headline, a few lines and a few facts of your own, from the settings. Words between asterisks, as in "Hi, I'm *Pedro*", are in the accent colour. A card can't hold working links, so put those under it.

Private and organization work is counted (it can be turned off). Only totals appear on the cards; private repo names never do. The cards come in three styles.

Quick Setup

bash <(curl -fsSL https://raw.githubusercontent.com/pedrocatalao/github-cool-readme/v1/setup.sh)

Everything runs and stays on your account, this setup only creates everything there. For details see Setup.

Classic cards

GitHub's own look: its fonts, colours and icons on a transparent background, following the viewer's light or dark theme. The default.

show: [about, languages, summary, contributions]
look:
  style: classic

The summary's ring is your share of active days; ring: github under cards: summary: puts the GitHub logo there instead.

With color: amber, green, purple, cyan, red or blue, the weekly bars, the streaks highlight, the summary's ring and the about card's marked words take that colour.

show: [streaks, weekly]
look:
  style: classic
  color: amber

Dot matrix and OLED cards

The same numbers as pinball-style displays: big readable text in a dot font, one item at a time with pinball transitions. style: dotmatrix draws them in round LEDs over a faint grid of unlit ones; style: oled in square pixels. Their colour is GitHub's (the default), amber, green, purple, cyan, red or blue, on a transparent background or a colour of your own.

Amber, on a dark panel: the orange of a plasma display.

look:
  style: dotmatrix
  color: amber
  background: 0d0b07    # a colour of your own, without #; leave out for none

GitHub: GitHub's own text and blue, on a transparent background, following the viewer's light or dark theme.

look:
  style: dotmatrix

Green, on a transparent background: bright on a dark page, darker on a light one.

look:
  style: dotmatrix
  color: green

OLED: square pixels, in any colour; here purple on a dark panel.

look:
  style: oled
  color: purple
  background: 0b0710

Where the numbers come from

• Commits, pull requests, issues, reviews: GitHub's contributions API, with the same rules as the contribution graph on your profile. Without the token's read:user scope it hides private work.
• Notable contributions: your list of pull requests.
• Stars: the current total on your repos (forks left out), and how many of those were given in the last 12 months.
• Active days, weekly rhythm, streaks: your contribution calendar. The count settings can't filter it.

Repos you can no longer access (e.g. a former employer's) can't be counted.

Setup

bash <(curl -fsSL https://raw.githubusercontent.com/pedrocatalao/github-cool-readme/v1/setup.sh)

The command above needs gh logged in. It asks before each change (--dry-run changes nothing), and does the steps below. Run it again any time to change which cards are shown and in what order, the style, colour, background or what's counted; your other settings stay as they are. Settings from before v1.5 are moved to the new layout.

To turn the cards off, run it and turn every card off. They're taken out of your README, but the marked block stays, so they come back in the same place. The workflow loses its schedule but can still be started by hand. Your token, settings and the cards branch are kept. To bring them back, run it again and turn a card on.

By hand

1. Create a classic personal access token with the repo, read:org and read:user scopes. If an organization uses SAML SSO, authorize the token for it.
2. In your profile repo, add it as the secret CARDS_TOKEN, copy examples/profile-workflow.yml to .github/workflows/cool-readme.yml, and optionally add a cool-readme.yml (see below).
3. Run the workflow once (it creates the cards branch), then put the cards in your README, with your login for you:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/you/you/cards/summary-dark.svg">
  <img src="https://raw.githubusercontent.com/you/you/cards/summary-light.svg" width="400" alt="GitHub stats">
</picture>

Same for contributions, languages, weekly, streaks and about. Show every card at width="400": two fit a row, and on a narrow screen they stack. Every card then shows as 400 by 195: classic ones are that size, dot matrix and OLED ones are 450 by 219, scaled to fit.

Settings

cool-readme.yml, all optional. Defaults:

user: null                # defaults to the token's owner

show: [summary, languages, contributions, weekly]   # the cards, in README order; [] for none
                          # also: streaks, about

count:
  private: true           # private repos in the numbers
  orgs: true              # repos of organizations you belong to

look:
  style: classic          # classic, oled (square pixels) or dotmatrix (round LEDs)
  color: github           # GitHub's blue and greens; amber, green, purple, cyan, red or blue: what highlights
  animations: true        # false: still cards
  background: none        # the page shows through (amber and green go darker on light pages), or a colour
                          # without #, like 030506: the same for every viewer, the text in shades that suit it
  border: false           # classic only: a thin outline, like GitHub's boxes

cards:
  summary:
    title: null           # small, on the header line
    ring: percent         # or github: the GitHub logo in the ring, the percentage in the title
  languages:
    title: Most used languages   # null hides it
    count: 6
    hide: []              # language names; their share is dropped
    repos: {}             # weight per repo, "repo" for your own, "owner/repo" otherwise; 0 leaves it out
    other: true           # fold the rest into "Other"; false: the shown ones share 100%
  contributions:
    title: Notable contributions
    count: 6              # 3 in view at a time; the rest scroll past in a loop
    open: true            # open pull requests count too, not only merged ones
    pin: []               # shown first; pull requests closed without merging never count
    hide: []
  weekly:
    title: Weekly rhythm
  streaks:
    title: Streaks
  about:
    title: About
    headline: null        # shown large; *words* like these in the accent colour, here and below
    lines: []             # a line each, wrapped; more than fit scroll past, the facts taking turns under them
    facts: {}             # label: text, a line each under the lines

A card that's not in show keeps its settings under cards, for when it's back. Unknown settings are an error, so typos don't go unnoticed.

Settings from before v1.5, with everything at the top (cards: [...], style, include, theme...), still work, and look the same: running setup again moves them to this layout.

Local development

Needs Node 22.18 or newer (TypeScript runs directly, no build step).

GITHUB_TOKEN=$(gh auth token) npm run dev   # fetch, render to out/, write out/preview.html
npm run dev:offline                          # re-render from the saved data, no API calls
npm run preview                              # every look in preview/*.yml, light and dark, in out/preview/index.html
npm run examples                             # the README's cards in examples/, from the saved data
npm test

npm run dev saves the raw data to .cache/snapshot.json. It names private repositories, so keep it out of anything public (it is gitignored).

License

MIT