Upgrade Your GitHub README.md 2.0

Table of Contents

1. What is lowlighter/metrics
2. How to Get Started
3. Setting Up Your Workflow
4. Customizing the Widgets
5. Placing Everything into Your README.md

What is Metrics

lowlighter/metrics is a GitHub repo you will fall in love with if you adore easy-to-use upgrading capabilities for your GitHub README.md through GitHub Actions.

Generate metrics that can be embedded everywhere, including your GitHub profile readme! Supports users, organizations, and even repositories!

Remember this post?

Upgrade Your GitHub README.md

Tina Huynh ・ Mar 18 '22

#github #tutorial #design

Think of this as the 2.0 version. Let's get started!

How to Get Started

Metrics v3.22.0 has a wonderful io website that allows you to quickly toggle multiple widgets and preview a classic layout to see the capabilities of Metrics.

Note: Even though this site will give you a copy of workable action code as well as markdown code, there are plugins that are not available through the web instance. In those cases, you will get the following subtle notification:

Getting Set Up

Option 1: Using GitHub Actions

• Gets you all the features
• No downtime
• Configuration can be a bit time-consuming (but worth it)

Option 2: Using a shared instance

• Easily configurable
• Limited features

Option 3: Deploying a web instance

• Create another shared instance
• Requires sysadmin knowledge

Option 4: Using command line with docker

• Suited only for on-time rendering

Option 5: Local setup for development

Back to TOC

Creating and Setting Up Your Personal Access Token

In order to use Metrics' plugins, you will have to create a personal access token (PAT), which are an alternative to using passwords for authentication to GitHub when using the GitHub API or command line.

1. Go to your profile photo and click Settings
2. Navigate to Developer Settings
3. Click Personal access tokens
4. Click Generate new token
5. For Metrics, the following scopes may be required:

- `public_repo`
- `read:org`
- `repo`
- `read:packages`
- `gist`

Note: For security reasons, it is advised to always use the least amount of scopes. It is possible to prevent security issues by forking the Metrics repository and using it in your workflow instead

1. Click Generate token
2. Put your GitHub personal token in the respective repository secrets with the name METRICS_TOKEN

Back to TOC

Setting Up Your Workflow

Create a new workflow that looks something like this:

name: Metrics
on:
  # Schedule daily updates
  schedule:
    - cron: "0 0 * * *"
  # (optional) Run workflow manually
  workflow_dispatch:
  # (optional) Run workflow when pushing on master/main
  push:
    branches:
      - master
jobs:
  github-metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: lowlighter/metrics@latest
        with:
          token: ${{ secrets.METRICS_TOKEN }}

All your rendered metrics will appear in your repository on each run and can be added to your README.md with ![Metrics](/github-metrics.svg), <img align="center" src="/github-metrics.svg" alt="Metrics" width="400">, or <img src="/github-metrics.svg" alt="Metrics" width="100%">:

Back to TOC

Customizing the Widgets

There are preset themes you can use quickly and easily OR you can add additional CSS and JavaScript using extras_css and extras_js options.

For example:

- uses: lowlighter/metrics@latest
  with:
    base: header
    extras_css: |
      h2 {
        color: red;
      }

- uses: lowlighter/metrics@latest
  with:
    base: header
    extras_js: |
      document.querySelectorAll("h2")?.forEach(h2 => h2.remove())

Back to TOC

Placing Everything into Your README

As you click through the different plugins for Metric, each will have example workflows that create a separate svg file within your repository. You have the option to either use the separate svg method or combine all your workflows into one unified svg for easy importing.

In my opinion, I like having separate svg files in order to easier format my preferred layout.

The example workflows for the isometric commit calendar, many user's favorite, can be found here:

name: Half-year calendar
uses: lowlighter/metrics@latest
with:
  filename: metrics.plugin.isocalendar.svg
  token: ${{ secrets.METRICS_TOKEN }}
  base: ""
  plugin_isocalendar: yes

name: Full-year calendar
uses: lowlighter/metrics@latest
with:
  filename: metrics.plugin.isocalendar.fullyear.svg
  token: ${{ secrets.METRICS_TOKEN }}
  base: ""
  plugin_isocalendar: yes
  plugin_isocalendar_duration: full-year

Alongside the example workflows, the documentation for each plugin also displays available options. How easy and simple!

Back to TOC