diff --git a/README.md b/README.md index c08617cd..0417e52b 100644 --- a/README.md +++ b/README.md @@ -10,186 +10,186 @@ But there's more with [plugins](https://github.com/lowlighter/metrics/tree/maste - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + @@ -241,14 +241,14 @@ But there's more with [plugins](https://github.com/lowlighter/metrics/tree/maste Try it now at [metrics.lecoq.io](https://metrics.lecoq.io/) with your GitHub username! -Because some plugins require additional configuration and setup, some of them are not available at [metrics.lecoq.io](https://metrics.lecoq.io/). +Because certain plugins require additional configuration and setup, some of them are not available at [metrics.lecoq.io](https://metrics.lecoq.io/). For a fully-featured experience, consider using this as a [GitHub Action](https://github.com/marketplace/actions/github-metrics-as-svg-image) instead! # 📜 How to use? ## ⚙️ Using GitHub Action on your profile repository (~5 min setup) -Setup a GitHub Action which runs periodically and pushes your generated metrics image on your repository. +Set up a GitHub Action which runs periodically and pushes your generated metrics image on your repository. See all supported options in [action.yml](action.yml). Assuming your username is `my-github-user`, you can then embed your metrics in your repository readme like below: @@ -266,7 +266,7 @@ Create a repository with the same name as your GitHub username if it's not alrea ![Setup personal repository](.github/readme/imgs/setup_personal_repository.png) -The `README.md` of it will be displayed on your user profile: +Its `README.md` will be displayed on your user profile: ![GitHub Profile Example](.github/readme/imgs/example_github_profile.png) @@ -355,7 +355,7 @@ Edit your repository readme and add your metrics image: ## 💕 Using the shared instance (~1 min setup, but with limitations) -For conveniency, you can use the shared instance available at [metrics.lecoq.io](https://metrics.lecoq.io) without any additional setup. +For convenience, you can use the shared instance available at [metrics.lecoq.io](https://metrics.lecoq.io) without any additional setup. Assuming your username is `my-github-user`, you can embed your metrics in your repository readme like below: @@ -380,7 +380,7 @@ If you're appreciating this project, consider using it as a GitHub Action instea ## 🏗️ Deploying your own web instance (~15 min setup, depending on your sysadmin knowledge) -It is possible to setup your own instance if you don't want to use GitHub Actions or if you want to allow others users on your instance. +It is possible to set up your own instance if you don't want to use GitHub Actions or if you want to allow others users on your instance. When sharing an instance, it is advised to restrict the number of users which can use it through the rate limiter or the access list, to avoid reaching the requests limit of GitHub APIs. @@ -391,7 +391,7 @@ See all supported options in [settings.example.json](settings.example.json). ### 0. Prepare your server -You will need a server where you can setup and run a NodeJS application. +You will need a server where you can set up and run a NodeJS application. ### 1. Create a GitHub token @@ -448,8 +448,8 @@ Edit your repository readme and add your metrics image from your server domain: ### 6. (optional) Setup as service on your instance -To ensure that your instance will be restarted in case of reboots or crashs, you should setup it as a service. -This is described below for linux-like systems which supports *systemd*. +To ensure that your instance will restart if it reboots or crashes, you should set it up as a service. +This is described below for Linux-like systems which support *systemd*. Create a new service file `/etc/systemd/system/github_metrics.service` and paste the following after editing paths inside: @@ -482,7 +482,7 @@ systemctl status github_metrics
⚠️ HTTP errors code -The following errors code can be encountered on a web instance: +The following error codes may be encountered on a web instance: | Error code | Description | | ------------------------- | -------------------------------------------------------------------------- | @@ -498,14 +498,14 @@ The following errors code can be encountered on a web instance:
🔗 HTTP parameters -Generated metrics images from a web instance can be configured through url parameters. +Generated metrics images from a web instance can be configured through URL parameters. #### Configuring base content Base content is enabled by default, but passing `?base=0` will disable all base content. You can choose to selectively enable or disable a specific `
` with `?base.
=<1|0>`. -For example, to opt-out from `activity`, `community` and `metadata`, append `?base.activity=0&base.community=0&base.metadata=0` to your metrics url. +For example, to opt out from `activity`, `community` and `metadata`, append `?base.activity=0&base.community=0&base.metadata=0` to your metrics url. #### Configuring plugins @@ -522,12 +522,12 @@ Basically, most of [action.yml](action.yml) options can actually be used by web ## 🖼️ Templates -Templates allows you to change the general appearance of your metrics images. +Templates allow you to change the general appearance of your metrics images. Some metrics may be displayed differently, and all plugins may not be supported or behave the same from one template to another. Consider trying them at [metrics.lecoq.io](https://metrics.lecoq.io)! -Used template defaults to the `classic` one. +The default template is `classic`. ### 🧰 Template/plugin compatibily matrix @@ -629,7 +629,7 @@ Used template defaults to the `classic` one. To use `repository` template, you'll need to provide a repository name in `query` option. -If repository owner is different from `token` owner, use `user` option to specify it. +If the repository owner is different from the `token` owner, use the `user` option to specify it. Add the following to your workflow: ```yaml @@ -651,19 +651,19 @@ In return, they may require additional configuration and consume additional API ### 🗃️ Base content Generated metrics contains a few sections that are enabled by default, such as recent activity, community stats and repositories stats. -This can be configured by explicitely opt-out from them. +This can be configured by explicitly opting out from them.
💬 About -By default, generated metrics contains the following sections: +By default, generated metrics contain the following sections: * `header`, which usually contains your username, your two-week commits calendars and a few additional data * `activity`, which contains your recent activity (commits, pull requests, issues, etc.) * `community`, which contains your community stats (following, sponsors, organizations, etc.) * `repositories`, which contains your repositories stats (license, forks, stars, etc.) * `metadata`, which contains informations about generated metrics -You can explicitely opt-out from them, which can be useful if you only want to keep a few sections or to use a plugin as standalone. +You can explicitely opt out from them, which can be useful if you only want to keep a few sections or to use a plugin as standalone. For example, to keep only `header` and `repositories` sections, add the following to your workflow: ```yaml @@ -675,12 +675,12 @@ For example, to keep only `header` and `repositories` sections, add the followin #### 🏦 Organizations memberships -By default, the `community` section only counts public organizations memberships. +By default, the `community` section only counts public organization memberships. You can change your membership visibility in the `People` tab of your organization: ![Publish organization membership](.github/readme/imgs/setup_public_membership_org.png) -To include private organizations memberships, you'll need to add the `read:org` scope to your personal token. +To include private organization memberships, you'll need to add the `read:org` scope to your personal token. ![Add read:org scope to personal token](.github/readme/imgs/setup_token_org_read_scope.png) @@ -690,7 +690,7 @@ You may also need to [authorize your personal token](https://docs.github.com/en/ ### ⏱️ PageSpeed -The *pagespeed* plugin adds the performances of the website attached mentioned on your account: +The *pagespeed* plugin adds the performance statistics of the website attached on your account: ![Pagespeed plugin](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.pagespeed.svg) @@ -701,7 +701,7 @@ These are computed through [Google's PageSpeed API](https://developers.google.co Although not mandatory, you can generate an API key for PageSpeed API [here](https://developers.google.com/speed/docs/insights/v5/get-started) to avoid 429 HTTP errors. -The website attached to the GitHub profile will be the one to be audited. +The website attached to the GitHub profile will be the one audited. Expect 10 to 30 seconds to generate the results. Add the following to your workflow: @@ -741,7 +741,7 @@ Add the following to your workflow: plugin_pagespeed_screenshot: yes ``` -It is possible to audit a different website from the one linked to your GitHub account by using `plugin_pagespeed_url` option. +It is possible to audit a different website from the one linked to your GitHub account by using the `plugin_pagespeed_url` option. Add the following to your workflow: ```yaml @@ -803,7 +803,7 @@ Select a music provider below for instructions.
Apple Music -Extract the *embed* url of the playlist you want to share. +Extract the *embed* URL of the playlist you want to share. To do so, connect to [music.apple.com](https://music.apple.com/) and select the playlist you want to share. From `...` menu, select `Share` and `Copy embed code`. @@ -833,7 +833,7 @@ Finish the plugin setup by adding the following to your workflow:
Spotify -Extract the *embed* url of the playlist you want to share. +Extract the *embed* URL of the playlist you want to share. To do so, Open Spotify and select the playlist you want to share. From `...` menu, select `Share` and `Copy embed code`. @@ -864,7 +864,7 @@ Finish the plugin setup by adding the following to your workflow: #### Recently played mode -Display tracks you played recently. +Display tracks you have played recently. ![Music plugin (recently played)](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.music.recent.svg) @@ -878,7 +878,7 @@ Select a music provider below for additional instructions. This mode is not supported for now. -I tried to find a way with *smart playlists*, *shortcuts* and other stuff but could not figure a workaround to do it without paying the 99$ fee for developper program. +I tried to find a way with *smart playlists*, *shortcuts* and other stuff but could not figure a workaround to do it without paying the $99 fee for the developer program. So unfortunately this isn't available for now. @@ -889,7 +889,7 @@ So unfortunately this isn't available for now. Spotify does not have *personal tokens*, so it makes the process a bit longer because you're required to follow the [authorization workflow](https://developer.spotify.com/documentation/general/guides/authorization-guide/)... Follow the instructions below for a *TL;DR* to obtain a `refresh_token`. -Sign-in to the [developer dashboard](https://developer.spotify.com/dashboard/) and create a new app. +Sign in to the [developer dashboard](https://developer.spotify.com/dashboard/) and create a new app. Keep your `client_id` and `client_secret` and let this tab open for now. ![Add a redirect url](.github/readme/imgs/plugin_music_recent_spotify_token_0.png) @@ -978,7 +978,7 @@ Add the following to your workflow: ### 🎟️ Follow-up -The *follow-up* plugin displays the ratio of opened/closed issues and the ratio of opened/merged pull requests across all your repositories, which shows if they're well-maintened or not. +The *follow-up* plugin displays the ratio of open/closed issues and the ratio of open/merged pull requests across all your repositories, which shows if they're well-maintained or not. ![Follow-up plugin](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.followup.svg) @@ -1011,7 +1011,7 @@ You can choose to display and order topics by: - Most `stars` - Recent `activity` - Recently `starred` by you -- `random`ly +- `random` Add the following to your workflow: ```yaml @@ -1081,7 +1081,7 @@ Fill the informations and set visibility to *public*: It is possible to display projects related to repositories along with personal projects. -To do so, open your repository project and retrieve the last url endpoint, in the format `:user/:repository/projects/:project_id` (for example, `lowlighter/metrics/projects/1`) and add it in the `plugin_projects_repositories` option. Enable `Track project progress` in the project settings to display a progress bar in generated metrics. +To do so, open your repository project and retrieve the last URL endpoint, in the format `:user/:repository/projects/:project_id` (for example, `lowlighter/metrics/projects/1`) and add it in the `plugin_projects_repositories` option. Enable `Track project progress` in the project settings to display a progress bar in generated metrics. ![Add a repository project](.github/readme/imgs/plugin_projects_repositories.png) @@ -1098,7 +1098,7 @@ Add the following to your workflow: ### 👨‍💻 Lines -The *lines* of code plugin displays the number of lines of code you added and removed across all of your repositories. +The *lines* of code plugin displays the number of lines of code you have added and removed across all of your repositories. ![Lines plugin](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.lines.svg) @@ -1121,7 +1121,7 @@ Add the following to your workflow: ⚠️ This plugin requires a personal token with repo scope. -The repositories *traffic* plugin displays the number of pages views across your repositories. +The repositories *traffic* plugin displays the number of page views across your repositories. ![Traffic plugin](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.traffic.svg) @@ -1130,7 +1130,7 @@ The repositories *traffic* plugin displays the number of pages views across your It will consume an additional GitHub request per repository. -Because of GitHub REST API limitation, provided token requires full `repo` scope to access traffic informations. +Because of GitHub REST API limitation, the provided token requires full `repo` scope to access traffic informations. ![Token with repo scope](.github/readme/imgs/setup_token_repo_scope.png) @@ -1148,7 +1148,7 @@ Add the following to your workflow: ### 🐤 Tweets -The recent *tweets* plugin displays your latest tweets of the [twitter](https://twitter.com) attached mentioned on your account: +The recent *tweets* plugin displays your latest tweets of the [Twitter](https://twitter.com) account attached to your account. ![Tweets plugin](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.tweets.svg) @@ -1164,7 +1164,7 @@ Add the following to your workflow: plugin_tweets_token: ${{ secrets.TWITTER_TOKEN }} ``` -It is possible to use a different twitter username from the one linked to your GitHub account by using `plugin_tweets_user` option. +It is possible to use a different Twitter username from the one linked to your GitHub account by using `plugin_tweets_user` option. Add the following to your workflow: ```yaml @@ -1175,9 +1175,9 @@ Add the following to your workflow: ```
-💬 Obtaining a twitter token +💬 Obtaining a Twitter token -To get a twitter token, you'll need to apply to the [developer program](https://apps.twitter.com). +To get a Twitter token, you'll need to apply to the [developer program](https://apps.twitter.com). It's a bit tedious, but it seems that requests are approved quite quickly. Create an app from your [developer dashboard](https://developer.twitter.com/en/portal/dashboard) and register your bearer token in your repository secrets. @@ -1223,7 +1223,7 @@ Add the following to your workflow: ### 💡 Habits -The coding *habits* add deduced coding habits based on your recent activity, from up to 1000 events. +The coding *habits* plugin adds deduced coding habits based on your recent activity, from up to 1000 events. ![Habits plugin](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.habits.svg) @@ -1272,7 +1272,7 @@ Add the following to your workflow instead: plugin_habits_charts: yes ``` -By default, dates are based on the Greenwich meridian (England time). In order to these metrics to be accurate, be sure to set your timezone (see [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of supported timezones): +By default, dates are based on the Greenwich meridian (GMT/UTC). In order to these metrics to be accurate, be sure to set your timezone (see [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of supported timezones): ```yaml - uses: lowlighter/metrics@latest @@ -1287,7 +1287,7 @@ By default, dates are based on the Greenwich meridian (England time). In order t 🚧 This plugin is available as pre-release on @master branch (unstable) -The *activity* plugin displays your recent activity in GitHub. +The *activity* plugin displays your recent activity on GitHub. ![Activity plugin](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.activity.svg) @@ -1447,7 +1447,7 @@ See all supported options in [action.yml](action.yml). #### 🌐 Set timezone -By default, dates are based on the Greenwich meridian (England time). +By default, dates are based on the Greenwich meridian (GMT/UTC). It is possible to set set your timezone (see [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of supported timezones) by adding the following to your workflow: @@ -1476,11 +1476,12 @@ It is possible to order metrics content by adding the following to your workflow Content ordering is done through "[partials](https://github.com/lowlighter/metrics/blob/master/source/templates/classic/partials/_.json)", which are actually content chunks of generated metrics, which may vary from one template to another. -It is not mandatory to specify all partials, rest will automatically be appendend in default order. +It is not mandatory to specify all partials, as the rest will automatically be appended in the default order. #### 🔲 Adjust padding -Generated metrics height is computed after being rendered through an headless browser. As rendering can depends on used fonts and operating system, it may render as cropped or with additional blank space at the bottom. +The height of the generated metrics image is computed after being rendered through an headless browser. +As rendering can depends on used fonts and operating system, it may render as cropped or with additional blank space at the bottom. It is possible to adjust the padding by adding the following to your workflow: ```yaml
⏱️ Google PageSpeed plugin📅 Isometric calendar plugin⏱️ Google PageSpeed plugin📅 Isometric calendar plugin
- +
Detailed audit version - +
With screenshot version - +
- +
Full year version - +
🎼 Favorite music tracks plugin🎧 Recently listened music plugin🎼 Favorite music tracks plugin🎧 Recently listened music plugin
- + - +
🈷️ Most used languages plugin🎟️ Follow-up plugin🈷️ Most used languages plugin🎟️ Follow-up plugin
- + - +
📌 Starred topics plugin🗂️ Active projects plugin📌 Starred topics plugin🗂️ Active projects plugin
- +
Mastered and known technologies version - +
- +
👨‍💻 Lines of code plugin🧮 Repositories traffic plugin👨‍💻 Lines of code plugin🧮 Repositories traffic plugin
- + - +
🐤 Tweets plugin✒️ Recent posts plugin🐤 Tweets plugin✒️ Recent posts plugin
- + - +
💡 Coding Habits plugin📰 Activity plugin 🚧 @master💡 Coding Habits plugin📰 Activity plugin 🚧 @master
- +
With charts version - +
- +
✨ Stargazers evolution🌟 Recently starred repositories✨ Stargazers evolution🌟 Recently starred repositories
- + - +
🎫 Gists plugin🧑‍🤝‍🧑 People plugin 🚧 @master🎫 Gists plugin🧑‍🤝‍🧑 People plugin 🚧 @master
- + - +
Followed people version - +
🗃️ Header special features🗃️ Header special features
- +