DEV Community

Cover image for Upgrade Your GitHub README.md 2.0
Tina Huynh
Tina Huynh

Posted on

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!

metric plugins

Remember this post?

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.

metrics io

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:

not available notif

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`
Enter fullscreen mode Exit fullscreen mode

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

file your github PAT

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 }}
Enter fullscreen mode Exit fullscreen mode

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%">:

repo

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;
      }
Enter fullscreen mode Exit fullscreen mode
- uses: lowlighter/metrics@latest
  with:
    base: header
    extras_js: |
      document.querySelectorAll("h2")?.forEach(h2 => h2.remove())
Enter fullscreen mode Exit fullscreen mode

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.

isometric calendar

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
Enter fullscreen mode Exit fullscreen mode
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
Enter fullscreen mode Exit fullscreen mode

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

Back to TOC

Discussion (0)