Upgrade Your GitHub README.md 2.0
Tags: github, tutorial, design, beginners
Published: 2022-05-07 18:50:23

## Table of Contents <a name"TOC">
1. [What is lowlighter/metrics](#what-is-metrics)
2. [How to Get Started](#how-to-get-started)
3. [Setting Up Your Workflow](#setting-up-your-workflow)
3. [Customizing the Widgets](#customizing-the-widgets)
4. [Placing Everything into Your README.md](#placing-everything-into-your-readme)

### What is Metrics
[lowlighter/metrics](https://github.com/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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ljlowvengim2u0zqqet3.png)

Remember this post? 

{% embed https://dev.to/tmchuynh/upgrade-your-github-readmemd-1m0b %}

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

### How to Get Started
[Metrics v3.22.0](https://metrics.lecoq.io/) 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jrn9fr6e4szruc83wunv.png)

*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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/equh4e05jgy3cw4xv9iu.png)

#### Getting Set Up
Option 1: [Using GitHub Actions](https://github.com/lowlighter/metrics/blob/master/.github/readme/partials/documentation/setup/action.md)

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

Option 2: [Using a shared instance](https://github.com/lowlighter/metrics/blob/master/.github/readme/partials/documentation/setup/shared.md)

- Easily configurable
- Limited features

Option 3: [Deploying a web instance](https://github.com/lowlighter/metrics/blob/master/.github/readme/partials/documentation/setup/web.md)

- Create another shared instance
- Requires sysadmin knowledge

Option 4: [Using command line with docker](https://github.com/lowlighter/metrics/blob/master/.github/readme/partials/documentation/setup/docker.md)

- Suited only for on-time rendering

Option 5: [Local setup for development](https://github.com/lowlighter/metrics/blob/master/.github/readme/partials/documentation/setup/local.md)

[Back to TOC](#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*

6. Click `Generate token`
7. Put your GitHub personal token in the respective repository secrets with the name `METRICS_TOKEN`

![file your github PAT](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tbrv1iuo4xfairzhi2ez.png)

[Back to TOC](#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%">`:

![repo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mot2wlhn71rm2yiwzumz.png)

[Back to TOC](#TOC)

### Customizing the Widgets
There are [preset themes](https://github.com/lowlighter/metrics/tree/presets) you can use quickly and easily OR you can [add additional CSS and JavaScript](https://github.com/lowlighter/metrics/blob/master/source/plugins/core/README.md#-custom-css-styling) 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](#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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hxobsjn3aadnq07zr0o3.png)

The example workflows for the [isometric commit calendar](https://github.com/lowlighter/metrics/blob/master/source/plugins/isocalendar/README.md), many user's favorite, can be found [here](https://github.com/lowlighter/metrics/blob/master/source/plugins/isocalendar/README.md#%E2%84%B9%EF%B8%8F-examples-workflows):

```
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](https://github.com/lowlighter/metrics/blob/master/source/plugins/isocalendar/README.md#%EF%B8%8F-available-options). How easy and simple!

[Back to TOC](#TOC)