Skip to content
Get packs

Guide · Open source

How to use Metrics: GitHub stats cards for your profile README

Updated · written with AI from the project's own documentation and checked against our catalogue data

Metrics is an open-source infographics generator that builds visual summaries of a GitHub account, organization or repository, such as languages used, commit activity, stars and contributors. This guide is for developers and maintainers who want an automatically updated stats image on a profile README or another page. By the end you will know what Metrics produces, how the project is set up from its README, and where the README stops so you know what to check next.

Metricslowlighter/metrics · ★ 17.4k · MIT

Quick start

  1. 1Read the README. Open the lowlighter/metrics repository and read the full README, including plugin and option docs.
  2. 2Clone the repository. Run git clone https://github.com/lowlighter/metrics in your terminal to get the source.
  3. 3Pick your plugins. Choose a small set of plugins, such as languages or stargazers, that match what you want to show.
  4. 4Configure the GitHub Action. Set up the action using the configuration in the full documentation, since the excerpt does not include it.
  5. 5Embed the output. Reference the generated image from your profile README.
  6. 6Review the result. Check the card against the example images and adjust options as needed.

What Metrics generates

Metrics renders its output as an image or report that you can embed on your profile README or other pages. The README says it supports user accounts, organization accounts and repositories.

The project describes more than 40 plugins and a large number of display options. Examples in the README include an isometric commit calendar, languages activity, stargazers, lines of code changed, starred topics, repository licenses, coding habits, repository contributors and comment reactions.

  • Stats for user accounts, organizations and repositories
  • Plugins such as languages, stargazers, licenses and contributors
  • The README lists output formats as SVG, Markdown, PDF and JSON

Get the Metrics source code

The README's install section gives a clone command as the starting point. Run it in the terminal where you want the project folder to be created.

The README excerpt provided here does not include the rest of the setup, such as the GitHub Action workflow file or configuration keys. Read the full README in the cloned repository before you configure anything.

git clone https://github.com/lowlighter/metrics

Choose plugins and options for your card

Metrics is built around plugins. The README links a separate page for each plugin, for example the languages, stargazers and habits plugins. Each plugin page lists its own options.

Pick the plugins that match what you want to show. Start with one or two so the output is easy to check, then add more.

  • Open the plugin links in the README's plugin table
  • Check each plugin's options before enabling it
  • Preview the generated SVG before placing it on a public profile

Run Metrics as a GitHub Action

The README says Metrics runs as a GitHub Action. It renders the result as an image that you can place on your profile README. The README excerpt does not show the workflow file, so take the exact action configuration from the full documentation.

Once the action has run, the output image can be referenced from your README. Because it is regenerated by the action, the card updates without manual edits.

  • Metrics runs as a GitHub Action
  • Output is an image you reference from your README

Check the output and fix common problems

If a card looks wrong, the first thing to check is which plugin produced it and which options were set. The README shows example images for each plugin, which helps you compare your result with the expected layout.

The truncated README does not describe troubleshooting steps. For errors, consult the project's full documentation and the continuous integration badge on the repository page.

  • Compare your output with the example images in the README
  • Turn plugins off one at a time to find the one causing a problem

What people use it for

  • Showing languages used and commit activity on a GitHub profile README
  • Summarizing stars and contributors for a maintainer's repository
  • Producing an activity overview for an organization account
  • Displaying recent starred repositories or topics on a personal page

Frequently asked questions

Is Metrics free to use?

The README excerpt lists the project licence as MIT. Check the LICENSE file in the repository for the full terms before reuse.

What are the requirements for Metrics?

The source does not list specific prerequisites. Read the full README for requirements before you set it up.

How do I install Metrics?

The README's install section starts with git clone https://github.com/lowlighter/metrics. The rest of the setup, including running it as a GitHub Action, is in the full documentation.

Can I use Metrics for an organization or a repository?

Yes. The README says Metrics supports users, organizations and repositories, and it shows organization example output.

Is there a hosted version I can use without setup?

The truncated README centers on running Metrics yourself and does not describe a hosted-only path. If you want no setup, check the project homepage at metrics.lecoq.io.

How does Metrics compare to github-readme-stats?

Metrics is known for its large plugin set, with the README citing more than 40 plugins. Other projects such as github-readme-stats, github-profile-trophy and github-readme-activity-graph cover similar profile-stat use cases. Compare the outputs and setup effort before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Metrics suits developers and maintainers who want a self-run, automatically updated GitHub stats image with many plugins and options. It is a poor fit if you want a no-setup hosted service or a quick PDF or JSON export, since the README excerpt does not explain those paths.

Install options & downloads