docs(plugins): clarification, fix typos and style

.github/readme/partials/documentation/setup/web.md

@@ -84,7 +84,9 @@ Configuration file also contains settings about enabled templates, plugins and f
 }
 ```
 
-> ⚠️ Extras features **should not** be enabled on a public server, most of these are compute-intensive and some of some even allow remote code execution! Use with caution
+> ⚠️ Extras features **should not** be enabled on a public server, most of these are either compute, network or API intensive tasks. Some extras features even allow remote code execution which could compromise server security.
+>
+> Use at your own risk, *metrics* and its authors cannot be held responsible for any damage caused.
 
 ## 3️ Start docker container
 

.github/scripts/quickstart/plugin/metadata.yml

@@ -1,6 +1,7 @@
-name: "🧩 <%= `${name.charAt(0).toLocaleUpperCase()}${name.substring(1)}` %>"
+name: 🧩 <%= `${name.charAt(0).toLocaleUpperCase()}${name.substring(1)}` %>
 category: community
-description: Short description
+description: |
+  Short description
 examples:
   default: https://via.placeholder.com/468x60?text=No%20preview%20available
 authors:
@@ -13,6 +14,7 @@ scopes: []
 inputs:
 
   plugin_<%= name %>:
-    description: Enable <%= name %> plugin
+    description: |
+      Enable <%= name %> plugin
     type: boolean
     default: no

.github/scripts/quickstart/template/metadata.yml

@@ -1,6 +1,7 @@
-name: "🖼️ Template name"
+name: 🖼️ Template name
 extends: classic
-description: Short description
+description: |
+  Short description
 examples:
   default: https://via.placeholder.com/468x60?text=No%20preview%20available
 authors:

source/app/metrics/metadata.mjs

@@ -212,6 +212,38 @@ metadata.plugin = async function({__plugins, __templates, name, logger}) {
       Object.assign(meta.inputs, inputs, Object.fromEntries(Object.entries(inputs).map(([key, value]) => [metadata.to.query(key, {name}), value])))
     }
 
+    //Extra features parser
+    {
+      meta.extras = function(input, {extras = {}}) {
+        //Required permissions
+        const required = inputs[metadata.to.yaml(input, {name})]?.extras ?? null
+        if (!required)
+          return true
+        console.debug(`metrics/extras > ${name} > ${input} > require [${required}]`)
+
+        //Legacy handling
+        const enabled = extras?.features ?? extras?.default ?? false
+        if (typeof enabled === "boolean") {
+          console.debug(`metrics/extras > ${name} > ${input} > extras features is set to ${enabled}`)
+          return enabled
+        }
+        if (!Array.isArray(required)) {
+          console.debug(`metrics/extras > ${name} > ${input} > extras is not a permission array, skipping`)
+          return false
+        }
+
+        //Check permissions
+        if (!Array.isArray(extras.features))
+          throw new Error(`metrics/extras > ${name} > ${input} > extras.features is not an array`)
+        const missing = required.filter(permission => !extras.features.includes(permission))
+        if (missing.length > 0) {
+          console.debug(`metrics/extras > ${name} > ${input} > missing permissions [${missing}], skipping`)
+          return false
+        }
+        return true
+      }
+    }
+
     //Action metadata
     {
       //Extract comments
@@ -538,6 +570,12 @@ metadata.to = {
     key = key.replace(/^plugin_/, "").replace(/_/g, ".")
     return name ? key.replace(new RegExp(`^(${name}.)`, "g"), "") : key
   },
+  yaml(key, {name = ""} = {}) {
+    const parts = [key.replaceAll(".", "_")]
+    if (name)
+      parts.unshift((name === "base") ? name : `plugin_${name}`)
+    return parts.join("_")
+  }
 }
 
 //Demo for main and individual readmes

source/plugins/achievements/metadata.yml

@@ -1,6 +1,7 @@
-name: "🏆 Achievements"
+name: 🏆 Achievements
 category: github
-description: This plugin displays several highlights about what you achieved on GitHub.
+description: |
+  This plugin displays several highlights about what an account has achieved on GitHub.
 examples:
   +compact display: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.achievements.compact.svg
   detailed display: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.achievements.svg
@@ -13,13 +14,14 @@ scopes:
 inputs:
 
   plugin_achievements:
-    description: Enable achievements plugin
+    description: |
+      Enable achievements plugin
     type: boolean
     default: no
 
   plugin_achievements_threshold:
     description: |
-      Display rank threshold
+      Rank threshold filter
 
       Use `X` to display achievements not yet unlocked
     type: string
@@ -32,13 +34,15 @@ inputs:
       - X
 
   plugin_achievements_secrets:
-    description: Display secrets achievements
+    description: |
+      Secrets achievements
     type: boolean
     default: yes
 
   plugin_achievements_display:
     description: |
       Display style
+
       - `detailed`: display icon, name, description and ranking
       - `compact`: display icon, name and value
     type: string
@@ -48,16 +52,18 @@ inputs:
       - compact
 
   plugin_achievements_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 0
     min: 0
+    zero: disable
 
   plugin_achievements_ignored:
     description: |
-      Hide specified achievements
+      Ignored achievements
 
-      Use names without the rank adjective (i.e. without "great", "super" or "master")
+      Use achievements names without their rank adjective (i.e. without "great", "super" or "master")
     type: array
     format: comma-separated
     default: ""
@@ -65,11 +71,11 @@ inputs:
 
   plugin_achievements_only:
     description: |
-      Restrict display to specified achievements
+      Showcased achievements
 
-      Use names without the rank adjective (i.e. without "great", "super" or "master")
+      Use achievements names without their rank adjective (i.e. without "great", "super" or "master")
 
-      This option is equivalent to `plugin_achievements_ignored` with all existing achievements but the ones listed in this option
+      This option is equivalent to [`plugin_achievements_ignored`](/source/plugins/achievements/README.md#plugin_achievements_ignored) with all existing achievements except the ones listed in this option
     type: array
     format: comma-separated
     default: ""

source/plugins/activity/metadata.yml

@@ -1,6 +1,7 @@
-name: "📰 Recent activity"
+name: 📰 Recent activity
 category: github
-description: This plugin displays your recent activity on GitHub.
+description: |
+  This plugin displays recent activity on GitHub.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.activity.svg
 index: 13
@@ -13,26 +14,30 @@ scopes:
 inputs:
 
   plugin_activity:
-    description: Enable activity plugin
+    description: |
+      Enable activity plugin
     type: boolean
     default: no
 
   plugin_activity_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 5
     min: 1
     max: 1000
 
   plugin_activity_load:
-    description: Events to load
+    description: |
+      Events to load
     type: number
     default: 300
     min: 100
     max: 1000
 
   plugin_activity_days:
-    description: Events maximum age
+    description: |
+      Events maximum age
     type: number
     default: 14
     min: 0
@@ -43,7 +48,7 @@ inputs:
     description: |
       Events visibility
 
-      Lets you hide private activity when using a `repo` scope token
+      Can be used to toggle private activity visibility when using a token with `repo` scope
     type: string
     default: all
     values:
@@ -51,12 +56,14 @@ inputs:
       - all
 
   plugin_activity_timestamps:
-    description: Display events timestamps
+    description: |
+      Events timestamps
     type: boolean
     default: no
 
   plugin_activity_skipped:
-    description: Skipped repositories
+    description: |
+      Skipped repositories
     type: array
     format: comma-separated
     default: ""
@@ -67,7 +74,7 @@ inputs:
     description: |
       Ignored users
 
-      Useful to ignore bots activity
+      Can be used to ignore bots activity
     type: array
     format: comma-separated
     default: ""

source/plugins/anilist/metadata.yml

@@ -1,6 +1,7 @@
-name: "🌸 Anilist watch list and reading list"
+name: 🌸 Anilist watch list and reading list
 category: social
-description: This plugin displays your favorites animes, mangas and characters from your [AniList](https://anilist.co) account.
+description: |
+  This plugin displays favorites animes, mangas and characters from a [AniList](https://anilist.co) account.
 examples:
   +for anime watchers: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.anilist.svg
   for manga readers: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.anilist.manga.svg
@@ -13,12 +14,21 @@ scopes: []
 inputs:
 
   plugin_anilist:
-    description: Enable aniList plugin
+    description: |
+      Enable aniList plugin
     type: boolean
     default: no
 
+  plugin_anilist_user:
+    type: string
+    description: |
+      AniList login
+    default: .user.login
+    preset: no
+
   plugin_anilist_medias:
-    description: Display medias types
+    description: |
+      Medias types
     type: array
     format: comma-separated
     default: anime, manga
@@ -29,7 +39,8 @@ inputs:
   plugin_anilist_sections:
     description: |
       Displayed sections
-      - `favorites` will display favorites `plugin_anilist_medias`
+
+      - `favorites` will display favorites from `plugin_anilist_medias`
       - `watching` will display animes currently in watching list
       - `reading` will display manga currently in reading list
       - `characters` will display liked characters
@@ -44,26 +55,25 @@ inputs:
       - characters
 
   plugin_anilist_limit:
-    description: Display limit (medias)
+    description: |
+      Display limit (medias)
     type: number
     default: 2
     min: 0
     zero: disable
 
   plugin_anilist_limit_characters:
-    description: Display limit (characters)
+    description: |
+      Display limit (characters)
     type: number
     default: 22
     min: 0
     zero: disable
 
   plugin_anilist_shuffle:
-    description: Shuffle data for varied outputs
+    description: |
+      Shuffle data
+
+      Can be used to create varied outputs
     type: boolean
     default: yes
-
-  plugin_anilist_user:
-    type: string
-    description: AniList login
-    default: .user.login
-    preset: no

source/plugins/base/metadata.yml

@@ -1,4 +1,4 @@
-name: "🗃️ Base content"
+name: 🗃️ Base content
 category: core
 description:
 examples:
@@ -12,17 +12,16 @@ scopes:
   - public_access
 inputs:
 
-  # Base content
   base:
     description: |
       Base content
 
       The following sections are supported:
-      * `header`, which usually contains username, two-week commits calendars and a few additional data
+      - `header`, which usually contains username, two-weeks commits calendars and a few additional data
-      * `activity`, which contains recent activity (commits, pull requests, issues, etc.)
+      - `activity`, which contains recent activity (commits, pull requests, issues, etc.)
-      * `community`, which contains community stats (following, sponsors, organizations, etc.)
+      - `community`, which contains community stats (following, sponsors, organizations, etc.)
-      * `repositories`, which contains repository stats (license, forks, stars, etc.)
+      - `repositories`, which contains repository stats (license, forks, stars, etc.)
-      * `metadata`, which contains information about generated metrics
+      - `metadata`, which contains information about generated metrics
 
       These are all enabled by default, but it is possible to explicitly opt out from them.
     type: array
@@ -36,7 +35,6 @@ inputs:
       - metadata
 
   base_indepth:
-    extras: yes
     description: |
       Indepth mode
 
@@ -49,16 +47,19 @@ inputs:
         - total repositories contributed to
     type: boolean
     default: no
+    extras:
+      - metrics.api.github.overuse
+      - plugins.base.indepth
 
   base_hireable:
     description: |
-      Display `Available for hire!` in header section
+      Show `Available for hire!` in header section
     type: boolean
     default: no
 
   repositories:
     description: |
-      Repositories to fetch
+      Fetched repositories
 
       A higher value result in more accurate metrics but can hit GitHub API rate-limit more easily (especially with a lot of plugins enabled)
     type: number
@@ -67,31 +68,33 @@ inputs:
 
   repositories_batch:
     description: |
-      Repositories to fetch at a time
+      Fetched repositories per query
 
-      If you receive `Something went wrong while executing your query` (which is usually caused by API timeout),
+      If you receive `Something went wrong while executing your query` (which is usually caused by API timeouts), lowering this value may help.
-      try lowering this value.
+      This setting may not be supported by all plugins.
     type: number
     default: 100
     max: 100
     min: 1
 
   repositories_forks:
-    description: Include forks
+    description: |
+      Include forks
     type: boolean
     default: no
 
   repositories_affiliations:
     description: |
       Repositories affiliations
+
       - `owner`: owned repositories
       - `collaborator`: repositories with push access
       - `organization_member`: repositories from an organization where user is a member
 
       Some plugin outputs may be affected by this setting too.
 
-      Set to `""` to disable and fetch all repositories related to you.
+      Set to `""` to disable and fetch all repositories related to given account.
-      Broad affiliation will result in less representative metrics.
+      Broad affiliations will result in less representative metrics.
     type: array
     format: comma-separated
     default: owner
@@ -101,7 +104,8 @@ inputs:
       - organization_member
 
   repositories_skipped:
-    description: Default skipped repositories
+    description: |
+      Default skipped repositories
     type: array
     format: comma-separated
     default: ""
@@ -112,7 +116,7 @@ inputs:
     description: |
       Default ignored users
 
-      Note that email are supported only commits-related elements.
+      Note that emails are only supported in commits-related elements.
     type: array
     format: comma-separated
     default: github-actions[bot], dependabot[bot], dependabot-preview[bot], actions-user, action@github.com

source/plugins/calendar/metadata.yml

@@ -1,6 +1,7 @@
-name: "📆 Calendar"
+name: 📆 Commit calendar
 category: github
-description: This plugin displays your commit calendar across several years
+description: |
+  This plugin can display commit calendar across several years.
 examples:
   current year: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.calendar.svg
   +full history: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.calendar.full.svg
@@ -12,7 +13,8 @@ scopes:
 inputs:
 
   plugin_calendar:
-    description: Enable calendar plugin
+    description: |
+      Enable calendar plugin
     type: boolean
     default: no
 

source/plugins/code/metadata.yml

@@ -1,7 +1,7 @@
-name: "♐ Code snippet of the day"
+name: ♐ Random code snippet
 category: github
 description: |
-  This plugin displays a random code snippet from your recent activity history.
+  This plugin displays a random code snippet from recent activity history.
 
   > ⚠️ When improperly configured, this plugin could display private code.
   > If you work with sensitive data or company code, it is advised to keep this plugin disabled.
@@ -17,24 +17,30 @@ scopes:
 inputs:
 
   plugin_code:
-    description: Enable code plugin
+    description: |
+      Enable code plugin
     type: boolean
     default: no
 
   plugin_code_lines:
-    description: Display limit for code snippets
+    description: |
+      Display limit (lines per code snippets)
     type: number
     default: 12
+    min: 1
+    max: 128
 
   plugin_code_load:
-    description: Events to load
+    description: |
+      Events to load
     type: number
     default: 400
     min: 100
     max: 1000
 
   plugin_code_days:
-    description: Events maximum age
+    description: |
+      Events maximum age
     type: number
     default: 3
     min: 0
@@ -45,7 +51,7 @@ inputs:
     description: |
       Events visibility
 
-      Lets you hide private activity when using a `repo` scope token
+      Can be used to toggle private activity visibility when using a token with `repo` scope
     type: string
     default: public
     values:
@@ -53,7 +59,8 @@ inputs:
       - all
 
   plugin_code_skipped:
-    description: Skipped repositories
+    description: |
+      Skipped repositories
     type: array
     format: comma-separated
     default: ""
@@ -61,7 +68,8 @@ inputs:
     inherits: repositories_skipped
 
   plugin_code_languages:
-    description: Restrict display to specific languages
+    description: |
+      Showcased languages
     type: array
     format: comma-separated
     default: ""

source/plugins/community/README.md

@@ -99,9 +99,10 @@ Plugins are auto-loaded based on their folder existence, so there's no need to r
 
 The default file looks like below:
 ```yaml
-name: "🧩 Plugin name"
+name: 🧩 Plugin name
 category: community
-description: Short description
+description: |
+  Short description
 examples:
   default: https://via.placeholder.com/468x60?text=No%20preview%20available
 authors:
@@ -114,7 +115,8 @@ scopes: []
 inputs:
 
   plugin_{name}:
-    description: Enable {name} plugin
+    description: |
+      Enable {name} plugin
     type: boolean
     default: no
 ```
@@ -134,14 +136,16 @@ Because of GitHub Actions original limitations, only strings, numbers and boolea
 *Example: boolean type, defaults to `false`*
 ```yml
   plugin_{name}_{option}:
-    description: Boolean type
+    description: |
+      Boolean type
     type: boolean
     default: no
 ```
 
 ```yml
   plugin_{name}_{option}:
-    description: String type
+    description: |
+      String type
     type: string
     default: .user.login
 ```
@@ -151,7 +155,8 @@ Because of GitHub Actions original limitations, only strings, numbers and boolea
 *Example: string type, defaults to `foo` with `foo` or `bar` as allowed values*
 ```yml
   plugin_{name}_{option}:
-    description: Select type
+    description: |
+      Select type
     type: string
     values:
       - foo
@@ -164,7 +169,8 @@ Because of GitHub Actions original limitations, only strings, numbers and boolea
 *Example: number type, defaults to `1` and expected to be between `0` and `100`*
 ```yml
   plugin_{name}_{option}:
-    description: Number type
+    description: |
+      Number type
     type: number
     default: 1
     min: 0
@@ -178,7 +184,8 @@ Because of GitHub Actions original limitations, only strings, numbers and boolea
 *Example: array type, with comma-separated elements*
 ```yml
   plugin_{name}_{option}:
-    description: Array type
+    description: |
+      Array type
     type: array
     format: comma-separated
     values:
@@ -192,7 +199,8 @@ Because of GitHub Actions original limitations, only strings, numbers and boolea
 *Example: json type*
 ```yml
   plugin_{name}_{option}:
-    description: JSON type
+    description: |
+      JSON type
     type: json
     default: |
       {

source/plugins/community/fortune/metadata.yml

@@ -1,6 +1,7 @@
-name: "🥠 Fortune"
+name: 🥠 Fortune
 category: community
-description: This plugins displays a random fortune message
+description: |
+  This plugins displays a random fortune message
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.fortune.svg
 authors:
@@ -11,6 +12,7 @@ scopes: []
 inputs:
 
   plugin_fortune:
-    description: Enable fortune plugin
+    description: |
+      Enable fortune plugin
     type: boolean
     default: no

source/plugins/community/nightscout/metadata.yml

@@ -1,6 +1,7 @@
-name: "💉 Nightscout"
+name: 💉 Nightscout
 category: community
-description: This plugin lets you display blood sugar values from a [Nightscout](http://nightscout.info) site.
+description: |
+  This plugin displays blood sugar values from a [Nightscout](http://nightscout.info) site.
 examples:
   default: https://github.com/legoandmars/legoandmars/blob/master/metrics.plugin.nightscout.svg
 authors:
@@ -11,42 +12,49 @@ scopes: []
 inputs:
 
   plugin_nightscout:
-    description: Enable nightscout plugin
+    description: |
+      Enable nightscout plugin
     type: boolean
     default: no
 
   plugin_nightscout_url:
-    description: Nightscout URL
+    description: |
+      Nightscout URL
     type: string
     default: https://example.herokuapp.com
 
   plugin_nightscout_datapoints:
-    description: Number of datapoints shown the graph
+    description: |
+      Number of datapoints shown the graph
     type: number
     default: 12
     min: 0
     zero: disable
 
   plugin_nightscout_lowalert:
-    description: Threshold for low blood sugar
+    description: |
+      Threshold for low blood sugar
     type: number
     default: 80
     min: 0
 
   plugin_nightscout_highalert:
-    description: Threshold for high blood sugar
+    description: |
+      Threshold for high blood sugar
     type: number
     default: 180
     min: 0
 
   plugin_nightscout_urgentlowalert:
-    description: Threshold for urgently low blood sugar
+    description: |
+      Threshold for urgently low blood sugar
     type: number
     default: 50
     min: 0
 
   plugin_nightscout_urgenthighalert:
-    description: Threshold for urgently high blood sugar
+    description: |
+      Threshold for urgently high blood sugar
     type: number
     default: 250
     min: 0

source/plugins/community/poopmap/metadata.yml

@@ -1,6 +1,7 @@
-name: "💩 PoopMap plugin"
+name: 💩 PoopMap plugin
 category: community
-description: This plugin displays statistics from a [PoopMap](https://poopmap.net) account.
+description: |
+  This plugin displays statistics from a [PoopMap](https://poopmap.net) account.
 examples:
   default: https://github.com/matievisthekat/matievisthekat/blob/master/metrics.plugin.poopmap.svg
 authors:
@@ -11,17 +12,20 @@ scopes: []
 inputs:
 
   plugin_poopmap:
-    description: Enable poopmap plugin
+    description: |
+      Enable poopmap plugin
     type: boolean
     default: no
 
   plugin_poopmap_token:
-    description: PoopMap API token
+    description: |
+      PoopMap API token
     type: token
     default: ""
 
   plugin_poopmap_days:
-    description: Time range
+    description: |
+      Time range
     type: number
     values:
       - 7

source/plugins/community/screenshot/metadata.yml

@@ -1,8 +1,9 @@
-name: "📸 Website screenshot"
+name: 📸 Website screenshot
 category: community
 description: |
-  This plugin display a screenshot from any website.
+  This plugin displays a screenshot from any website.
-  It can either the full page or a portion restricted by a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).
+
+  It can either show the full page or a portion restricted by a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.screenshot.svg
 authors:
@@ -15,27 +16,32 @@ scopes: []
 inputs:
 
   plugin_screenshot:
-    description: Enable screenshot plugin
+    description: |
+      Enable screenshot plugin
     type: boolean
     default: no
 
   plugin_screenshot_title:
-    description: Title caption
+    description: |
+      Title caption
     type: string
     default: Screenshot
 
   plugin_screenshot_url:
-    description: Website url
+    description: |
+      Website URL
     type: string
     default: ""
     example: https://metrics.lecoq.io
 
   plugin_screenshot_selector:
-    description: CSS Selector
+    description: |
+      CSS Selector
     type: string
     default: body
 
   plugin_screenshot_background:
-    description: Display background
+    description: |
+      Background
     type: boolean
     default: yes

source/plugins/community/stock/metadata.yml

@@ -1,6 +1,7 @@
-name: "💹 Stock prices"
+name:"💹 Stock prices
 category: community
-description: This plugin displays the stock market price of a given company.
+description: |
+  This plugin displays the stock market price of a given company.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.stock.svg
 authors:
@@ -13,24 +14,30 @@ scopes: []
 inputs:
 
   plugin_stock:
-    description: Enable stock plugin
+    description: |
+      Enable stock plugin
     type: boolean
     default: no
+    extras:
+      - metrics.npm.optional.chartist
 
   plugin_stock_token:
-    description: Yahoo Finance token
+    description: |
+      Yahoo Finance token
     type: token
     default: ""
 
   plugin_stock_symbol:
-    description: Company stock symbol
+    description: |
+      Company stock symbol
     type: string
     default: ""
     example: MSFT
 
   plugin_stock_duration:
     description: |
-      Time range (relative to current date)
+      Time range
+
       - `1d`: Today
       - `5d`: 5 days
       - `1mo`: 1 month
@@ -42,6 +49,8 @@ inputs:
       - `10y`: 10 years
       - `ytd`: Year to date
       - `max`: All time
+
+      This is relative to current date
     type: string
     default: 1d
     values:
@@ -60,6 +69,7 @@ inputs:
   plugin_stock_interval:
     description: |
       Time interval between points
+
       - `1m`: 1 minute
       - `2m`: 2 minutes
       - `5m`: 5 minutes

source/plugins/contributors/metadata.yml

@@ -1,6 +1,7 @@
-name: "🏅 Repository contributors"
+name: 🏅 Repository contributors
 category: github
-description: This plugin display repositories contributors from a commit range along with additional stats.
+description: |
+  This plugin display repositories contributors from a commit range along with additional stats.
 examples:
   +by contribution types: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.categories.svg
   by number of contributions: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.contributions.svg
@@ -12,18 +13,25 @@ scopes:
 inputs:
 
   plugin_contributors:
-    description: Enable contributors plugin
+    description: |
+      Enable contributors plugin
     type: boolean
     default: no
 
   plugin_contributors_base:
-    description: Base reference (commit, tag, branch, etc.)
+    description: |
+      Base reference
+
+      Can be a commit, tag, branch, etc.
     type: string
     default: ""
     example: commit, tag or branch
 
   plugin_contributors_head:
-    description: Head reference (commit, tag, branch, etc.)
+    description: |
+      Head reference
+
+      Can be a commit, tag, branch, etc.
     type: string
     default: master
 
@@ -31,22 +39,24 @@ inputs:
     description: |
       Ignored users
 
-      Useful to ignore bots activity
+      Can be used to ignore bots activity
     type: array
     format: comma-separated
     default: ""
     inherits: users_ignored
 
   plugin_contributors_contributions:
-    description: Toggle number of contributions display
+    description: |
+      Contributions count
     type: boolean
     default: no
 
   plugin_contributors_sections:
     description: |
       Displayed sections
+
       - `contributors`: all contributors
-      - `categories`: contributors sorted by contributions categories
+      - `categories`: contributors sorted by contributions categories (must be configured with `plugin_contributors_categories`)
     type: array
     format: comma-separated
     default: contributors
@@ -57,9 +67,9 @@ inputs:
 
   plugin_contributors_categories:
     description: |
-      Configure contribution categories
+      Contribution categories
 
-      This option required `plugin_contributors_sections` to have `categories` in it to be effective
+      This option requires [`plugin_contributors_sections`](/source/plugins/contributors/README.md#plugin_contributors_sections) to have `categories` in it to be effective.
       Pass a JSON object mapping category with fileglobs
     type: json
     default: |
@@ -68,4 +78,6 @@ inputs:
         "💻 Code": ["source/**", "src/**"],
         "#️⃣ Others": ["*"]
       }
-    extras: yes
+    extras:
+      - metrics.runner.tempdir
+      - metrics.runner.git

source/plugins/core/metadata.yml

@@ -1,4 +1,4 @@
-name: "🧱 Core"
+name: 🧱 Core
 category: core
 description: Global configuration and options
 supports:
@@ -12,11 +12,10 @@ inputs:
     description: |
       GitHub Personal Access Token
 
-      No scopes are required by default, though some plugins and features may require additional scopes
+      No scopes are required by default, though some plugins and features may require additional scopes.
 
-      When using a configuration which does not requires a GitHub PAT, you may pass `NOT_NEEDED` instead.
+      When using a configuration which does not requires a GitHub PAT, it is possible to pass `NOT_NEEDED` instead.
-      Note that when doing so, all defaults values using `.user.*` will not be applicable meaning that they need to be filled manually.
+      When doing so, any settings which defaults on user fetched values will not be templated (e.g. `.user.*`) and will usually need to be set manually.
-      Most of the time `user` option must also be set.
     type: token
     required: true
 
@@ -33,7 +32,7 @@ inputs:
     description: |
       GitHub repository
 
-      This option is revevalant only for repositories templates
+      This option is only revelant for repositories templates
     type: string
     default: ""
     preset: no
@@ -52,7 +51,7 @@ inputs:
     description: |
       Target branch
 
-      Default value is set to your repository default branch
+      Defaults to current repository default branch
     type: string
     default: ""
 
@@ -90,7 +89,8 @@ inputs:
     default: TEMPLATE.md
 
   markdown_cache:
-    description: Markdown file cache
+    description: |
+      Markdown file cache
     type: string
     default: .cache
 
@@ -153,7 +153,8 @@ inputs:
     type: array
     format: comma-separated
     default: ""
-    extras: yes
+    extras:
+      - metrics.run.setup.community.templates
 
   template:
     description: |
@@ -176,7 +177,6 @@ inputs:
     default: "{}"
 
   extras_css:
-    extras: yes
     description: |
       Extra CSS
 
@@ -184,9 +184,10 @@ inputs:
       Useful to avoid creating a new template just to tweak some styling
     type: string
     default: ""
+    extras:
+      - metrics.run.user.css
 
   extras_js:
-    extras: yes
     description: |
       Extra JavaScript
 
@@ -197,6 +198,8 @@ inputs:
       It is run after transformations and optimizations, but just before resizing.
     type: string
     default: ""
+    extras:
+      - metrics.run.user.js
 
   config_timezone:
     description: |
@@ -278,7 +281,8 @@ inputs:
     global: yes
 
   config_animations:
-    description: Use CSS animations
+    description: |
+      Use CSS animations
     type: boolean
     default: yes
     global: yes
@@ -336,7 +340,8 @@ inputs:
       - insights
 
   config_presets:
-    description: Configuration presets
+    description: |
+      Configuration presets
     type: array
     format: comma-separated
     default: ""
@@ -344,28 +349,32 @@ inputs:
     example: "@lunar-red"
 
   retries:
-    description: Retries in case of failures (for rendering)
+    description: |
+      Retries in case of failures (for rendering)
     type: number
     default: 3
     min: 1
     max: 10
 
   retries_delay:
-    description: Delay between each retry (in seconds, for rendering)
+    description: |
+      Delay between each retry (in seconds, for rendering)
     type: number
     default: 300
     min: 0
     max: 3600
 
   retries_output_action:
-    description: Retries in case of failures (for output action)
+    description: |
+      Retries in case of failures (for output action)
     type: number
     default: 5
     min: 1
     max: 10
 
   retries_delay_output_action:
-    description: Delay between each retry (in seconds, for output action)
+    description: |
+      Delay between each retry (in seconds, for output action)
     type: number
     default: 120
     min: 0
@@ -442,7 +451,8 @@ inputs:
     max: 30
 
   notice_releases:
-    description: Notice about new releases of metrics
+    description: |
+      Notice about new releases of metrics
     type: boolean
     default: yes
 
@@ -481,7 +491,8 @@ inputs:
     preset: no
 
   verify:
-    description: SVG validity check
+    description: |
+      SVG validity check
     type: boolean
     default: no
     testing: yes
@@ -504,7 +515,8 @@ inputs:
     preset: no
 
   debug_print:
-    description: Print output in console
+    description: |
+      Print output in console
     type: boolean
     default: no
     testing: yes
@@ -534,7 +546,8 @@ inputs:
     preset: no
 
   use_mocked_data:
-    description: Use mocked data instead of live APIs
+    description: |
+      Use mocked data instead of live APIs
     type: boolean
     default: no
     testing: yes

source/plugins/discussions/metadata.yml

@@ -1,6 +1,7 @@
-name: "💬 Discussions"
+name: 💬 Discussions
 category: github
-description: This plugin displays your GitHub discussions stats.
+description: |
+  This plugin displays GitHub discussions stats.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.discussions.svg
 index: 16
@@ -11,12 +12,14 @@ scopes:
 inputs:
 
   plugin_discussions:
-    description: Enable discussions plugin
+    description: |
+      Enable discussions plugin
     type: boolean
     default: no
 
   plugin_discussions_categories:
-    description: Toggle discussion categories display
+    description: |
+      Discussion categories
     type: boolean
     default: yes
 
@@ -24,7 +27,7 @@ inputs:
     description: |
       Display limit (categories)
 
-      Note that categories are sorted from highest to lowest count.
+      Note that categories are sorted from highest to lowest count
     type: number
     default: 0
     zero: disable

source/plugins/followup/metadata.yml

@@ -1,6 +1,7 @@
-name: "🎟️ Follow-up of issues and pull requests"
+name: 🎟️ Follow-up of issues and pull requests
 category: github
-description: This plugin displays the ratio of open/closed issues and the ratio of open/merged pull requests across all your repositories.
+description: |
+  This plugin displays the ratio of open/closed issues and the ratio of open/merged pull requests across repositories.
 examples:
   +indepth analysis: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.indepth.svg
   created on a user's repositories: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.svg
@@ -15,13 +16,15 @@ scopes:
 inputs:
 
   plugin_followup:
-    description: Enable followup plugin
+    description: |
+      Enable followup plugin
     type: boolean
     default: no
 
   plugin_followup_sections:
     description: |
       Displayed sections
+
       - `repositories`: overall status of issues and pull requests on your repositories
       - `user`: overall status of issues and pull requests you have created on GitHub
     type: array
@@ -32,12 +35,15 @@ inputs:
       - user
 
   plugin_followup_indepth:
-    description: Indepth analysis
+    description: |
+      Indepth analysis
     type: boolean
     default: no
-    extras: yes
+    extras:
+      - metrics.api.github.overuse
 
   plugin_followup_archived:
-    description: Include Issues and Pull requests on the archived repositories.
+    description: |
+      Include archived repositories
     type: boolean
     default: yes

source/plugins/gists/metadata.yml

@@ -1,6 +1,7 @@
-name: "🎫 Gists"
+name: 🎫 Gists
 category: github
-description: This plugin displays [gists](https://gist.github.com) stats.
+description: |
+  This plugin displays [gists](https://gist.github.com) stats.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.gists.svg
 index: 21
@@ -11,6 +12,7 @@ scopes:
 inputs:
 
   plugin_gists:
-    description: Enable gists plugin
+    description: |
+      Enable gists plugin
     type: boolean
     default: no

source/plugins/habits/metadata.yml

@@ -1,6 +1,7 @@
-name: "💡 Coding habits"
+name: 💡 Coding habits and activity
 category: github
-description: This plugin display coding habits based on your recent activity, such as active hours and languages recently used.
+description: |
+  This plugin displays coding habits based on recent activity, such as active hours and languages recently used.
 examples:
   +recent activity charts: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.habits.charts.svg
   +midly interesting facts: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.habits.facts.svg
@@ -13,7 +14,8 @@ scopes:
 inputs:
 
   plugin_habits:
-    description: Enable habits plugin
+    description: |
+      Enable habits plugin
     type: boolean
     default: no
 
@@ -28,7 +30,8 @@ inputs:
     max: 1000
 
   plugin_habits_days:
-    description: Event maximum age
+    description: |
+      Event maximum age
     type: number
     default: 14
     min: 1
@@ -36,25 +39,29 @@ inputs:
 
   plugin_habits_facts:
     description: |
-      Toggle midly interesting facts display
+      Midly interesting facts
 
       It includes indentation type, average number of characters per line of code, and most active time and day
     type: boolean
     default: yes
 
   plugin_habits_charts:
-    extras: yes
     description: |
-      Toggle charts display
+      Charts
 
       It includes commit activity per hour of day and commit activity per day of week
       Recent language activity may also displayed (it requires extras features to be enabled for web instances) for historical reasons
     type: boolean
     default: no
+    extras:
+      - metrics.api.github.overuse
+      - metrics.run.tempdir
+      - metrics.run.git
 
   plugin_habits_charts_type:
     description: |
       Charts display type
+
       - `classic`: `<div>` based charts, simple and lightweight
       - `chartist`: `<svg>` based charts, smooth
     type: string
@@ -62,14 +69,18 @@ inputs:
     values:
       - classic
       - chartist
+    extras:
+      - metrics.npm.optional.chartist
 
   plugin_habits_trim:
-    description: Trim unused hours on charts
+    description: |
+      Trim unused hours on charts
     type: boolean
     default: no
 
   plugin_habits_languages_limit:
-    description: Limits the number of languages to be displayed
+    description: |
+      Display limit (languages)
     type: number
     default: 8
     min: 0

source/plugins/introduction/metadata.yml

@@ -3,7 +3,7 @@ category: github
 description: |
   This plugin displays account bio or organization/repository description.
 
-  It is mostly intended for images that will be used outside of GitHub, since these informations are already displayed on GitHub.
+  Since account bio is already displayed on account profile, this plugin is mostly intended for external usage.
 examples:
   +for a user or an organization: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.introduction.svg
   for a repository: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.introduction.repository.svg
@@ -16,14 +16,14 @@ scopes:
   - public_access
 inputs:
 
-  # Enable or disable plugin
   plugin_introduction:
-    description: Display account or repository introduction
+    description: |
+      Enable introduction plugin
     type: boolean
     default: no
 
-  # Display introduction section title
   plugin_introduction_title:
-    description: Display introduction section title
+    description: |
+      Section title
     type: boolean
     default: yes

source/plugins/isocalendar/metadata.yml

@@ -1,6 +1,7 @@
-name: "📅 Isometric commit calendar"
+name: 📅 Isometric commit calendar
 category: github
-description: This plugin displays an isometric view of your commit calendar along with a few additional statistics like current streak and average number of commit per day.
+description: |
+  This plugin displays an isometric view of a user commit calendar along with a few additional statistics like current streak and average number of commit per day.
 examples:
   +full year calendar: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.isocalendar.fullyear.svg
   half year calendar: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.isocalendar.svg
@@ -12,13 +13,15 @@ scopes:
 inputs:
 
   plugin_isocalendar:
-    description: Enable isocalendar plugin
+    description: |
+      Enable isocalendar plugin
     type: boolean
     default: no
 
   plugin_isocalendar_duration:
     description: |
       Time range
+
       - `half-year`: 180 days
       - `full-year`: 1 year
     type: string

source/plugins/languages/metadata.yml

@@ -1,6 +1,7 @@
-name: "🈷️ Most used languages"
+name: 🈷️ Languages activity
 category: github
-description: This plugin can display which languages you use across all repositories you contributed to.
+description: |
+  This plugin can display which languages you use across all repositories you contributed to.
 examples:
   +indepth analysis (clone and analyze repositories): https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.languages.indepth.svg
   +recently used (analyze recent activity events): https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.languages.recent.svg
@@ -16,19 +17,22 @@ scopes:
 inputs:
 
   plugin_languages:
-    description: Enable languages plugin
+    description: |
+      Enable languages plugin
     type: boolean
     default: no
 
   plugin_languages_ignored:
-    description: Ignored languages
+    description: |
+      Ignored languages
     type: array
     format: comma-separated
     default: ""
     example: html, css, ...
 
   plugin_languages_skipped:
-    description: Skipped repositories
+    description: |
+      Skipped repositories
     type: array
     format: comma-separated
     default: ""
@@ -36,7 +40,8 @@ inputs:
     inherits: repositories_skipped
 
   plugin_languages_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 8
     min: 0
@@ -44,35 +49,40 @@ inputs:
     zero: disable
 
   plugin_languages_threshold:
-    description: Display threshold (percentage)
+    description: |
+      Display threshold (percentage)
     type: string
     default: 0%
 
   plugin_languages_other:
     description: |
-      Group unknown, ignored and over-limit languages into a single "Other" category
+      Group unknown, ignored and over-limit languages into "Other" category
 
-      If this option is enabled, "Other" category will not be subject to `plugin_languages_threshold`.
+      If this option is enabled, "Other" category will not be subject to [`plugin_languages_threshold`](/source/plugins/languages/README.md#plugin_languages_threshold).
       It will be automatically hidden if empty.
     type: boolean
     default: no
 
   plugin_languages_colors:
-    description: Custom languages colors
+    description: |
+      Custom languages colors
     type: array
     format: comma-separated
     default: github
     example: javascript:red, 0:blue, 1:#ff00aa
 
   plugin_languages_aliases:
-    description: Custom languages names
+    description: |
+      Custom languages names
     type: string
     default: ""
     example: javascript:JS typescript:TS
 
   plugin_languages_sections:
-    extras: yes
+    description: |
-    description: Displayed sections
+      Displayed sections
+
+      Note that `recently-used` is only available when [`plugin_languages_indepth`](/source/plugins/languages/README.md#plugin_languages_indepth) is enabled
     type: array
     format: comma-separated
     default: most-used
@@ -82,11 +92,10 @@ inputs:
       - recently-used
 
   plugin_languages_details:
-    extras: yes
     description: |
       Additional details
 
-      Note that `lines` is only available when `plugin_languages_indepth` is enabled
+      Note that `lines` is only available when [`plugin_languages_indepth`](/source/plugins/languages/README.md#plugin_languages_indepth) is enabled
     type: array
     format: comma-separated
     values:
@@ -97,22 +106,32 @@ inputs:
     example: bytes-size, percentage
 
   plugin_languages_indepth:
-    extras: yes
+    description: |
-    description: Indepth mode (⚠️ read documentation first)
+      Indepth mode
+
+      > ⚠️ read documentation first
     type: boolean
     default: false
+    extras:
+      - metrics.api.github.overuse
+      - metrics.run.tempdir
+      - metrics.run.git
 
   plugin_languages_analysis_timeout:
-    extras: yes
+    description: |
-    description: Indepth mode - Analysis timeout
+      Indepth mode - Analysis timeout
     type: number
     default: 15
     min: 1
     max: 30
+    extras:
+      - metrics.api.github.overuse
+      - metrics.run.tempdir
+      - metrics.run.git
 
   plugin_languages_categories:
-    extras: yes
+    description: |
-    description: Indepth mode - Displayed categories (most-used section)
+      Indepth mode - Displayed categories (most-used section)
     type: array
     format: comma-separated
     values:
@@ -121,10 +140,14 @@ inputs:
       - programming
       - prose
     default: markup, programming
+    extras:
+      - metrics.api.github.overuse
+      - metrics.run.tempdir
+      - metrics.run.git
 
   plugin_languages_recent_categories:
-    extras: yes
+    description: |
-    description: Indepth mode - Displayed categories (recently-used section)
+      Indepth mode - Displayed categories (recently-used section)
     type: array
     format: comma-separated
     values:
@@ -133,20 +156,32 @@ inputs:
       - programming
       - prose
     default: markup, programming
+    extras:
+      - metrics.api.github.overuse
+      - metrics.run.tempdir
+      - metrics.run.git
 
   plugin_languages_recent_load:
-    extras: yes
+    description: |
-    description: Events to load (recently-used section)
+      Events to load (recently-used section)
     type: number
     default: 300
     min: 100
     max: 1000
+    extras:
+      - metrics.api.github.overuse
+      - metrics.run.tempdir
+      - metrics.run.git
 
   plugin_languages_recent_days:
-    extras: yes
+    description: |
-    description: Events maximum age (day, recently-used section)
+      Events maximum age (day, recently-used section)
     type: number
     default: 14
     min: 0
     max: 365
     zero: disable
+    extras:
+      - metrics.api.github.overuse
+      - metrics.run.tempdir
+      - metrics.run.git

source/plugins/licenses/metadata.yml

@@ -1,6 +1,7 @@
-name: "📜 Repository licenses"
+name: 📜 Repository licenses
 category: github
-description: This plugin display repository license informations like permissions, limitations and conditions along with additional stats about dependencies.
+description: |
+  This plugin display repository license informations like permissions, limitations and conditions along with additional stats about dependencies.
 examples:
   +permissions, limitations and conditions: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.licenses.svg
   +licenses overview: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.licenses.ratio.svg
@@ -12,23 +13,31 @@ scopes:
 inputs:
 
   plugin_licenses:
-    description: Enable licenses plugin
+    description: |
+      Enable licenses plugin
     type: boolean
     default: no
-    extras: yes
+    extras:
+      - metrics.run.tempdir
+      - metrics.run.git
+      - metrics.run.licensed
+      - metrics.run.user.cmd
 
   plugin_licenses_setup:
-    description: Setup command
+    description: |
+      Setup command
     type: string
     default: ""
     example: npm ci
 
   plugin_licenses_ratio:
-    description: Display used licenses ratio
+    description: |
+      Used licenses ratio
     type: boolean
     default: no
 
   plugin_licenses_legal:
-    description: Display permissions, limitations and conditions about licenses
+    description: |
+      Permissions, limitations and conditions about used licenses
     type: boolean
     default: yes

source/plugins/lines/metadata.yml

@@ -1,6 +1,7 @@
-name: "👨‍💻 Lines of code changed"
+name: 👨‍💻 Lines of code changed
 category: github
-description: This plugin displays the number of lines of code you have added and removed across all of your repositories.
+description: |
+  This plugin displays the number of lines of code added and removed across repositories.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.lines.svg
 index: 18
@@ -13,12 +14,14 @@ scopes:
 inputs:
 
   plugin_lines:
-    description: Enable lines plugin
+    description: |
+      Enable lines plugin
     type: boolean
     default: no
 
   plugin_lines_skipped:
-    description: Skipped repositories
+    description: |
+      Skipped repositories
     type: array
     format: comma-separated
     default: ""

source/plugins/music/metadata.yml

@@ -1,7 +1,7 @@
-name: "🎼 Music plugin"
+name: 🎼 Music activity and suggestions
 category: social
 description: |
-  This plugin can display top and recently listened music tracks or from a random playlist.
+  This plugin can display top and recently listened music tracks or titles from a random playlist.
 
   Different music providers are supported.
 examples:
@@ -15,19 +15,21 @@ scopes: []
 inputs:
 
   plugin_music:
-    description: Enable music plugin
+    description: |
+      Enable music plugin
     type: boolean
     default: no
 
   plugin_music_provider:
     description: |
       Music provider
+
       - `apple`: Apple Music
       - `spotify`: Spotify
       - `lastfm`: Last.fm
       - `youtube`: YouTube Music
 
-      This setting is optional when using `plugin_music_mode: playlist` (provider will be auto-detected from `plugin_music_playlist` URL)
+      This setting is optional when using [`plugin_music_mode: playlist`](/source/plugins/music/README.md#plugin_music_mode) (provider will be auto-detected from [`plugin_music_playlist`](/source/plugins/music/README.md#plugin_music_playlist) URL)
     type: string
     default: ""
     values:
@@ -48,14 +50,22 @@ inputs:
     type: token
     default: ""
 
+  plugin_music_user:
+    description: |
+      Music provider username
+    type: string
+    default: .user.login
+    preset: no
+
   plugin_music_mode:
     description: |
       Display mode
+
       - `playlist`: display random tracks from an URL playlist
       - `recent`: display recently listened tracks
       - `top`: display top listened artists/tracks
 
-      If `plugin_music_playlist` is specifed, the default value is `playlist`, else it is `recent`
+      If [`plugin_music_playlist`](/source/plugins/music/README.md#plugin_music_playlist) is specifed, the default value is `playlist`, else it is `recent`
     type: string
     default: ""
     values:
@@ -74,20 +84,23 @@ inputs:
     preset: no
 
   plugin_music_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 4
     min: 1
     max: 100
 
   plugin_music_played_at:
-    description: Recently played - Toggle last played timestamp display
+    description: |
+      Recently played - Last played timestamp
     type: boolean
     default: no
 
   plugin_music_time_range:
     description: |
-      Top tracks - Time range for `top` mode
+      Top tracks - Time range
+
       - `short`: 4 weeks
       - `medium`: 6 months
       - `long`: several years
@@ -101,6 +114,7 @@ inputs:
   plugin_music_top_type:
     description: |
       Top tracks - Display type
+
       - `tracks`: display track
       - `artists`: display artists
     type: string
@@ -108,9 +122,3 @@ inputs:
     values:
       - tracks
       - artists
-
-  plugin_music_user:
-    description: Music provider username
-    type: string
-    default: .user.login
-    preset: no

source/plugins/notable/metadata.yml

@@ -1,6 +1,7 @@
-name: "🎩 Notable contributions"
+name: 🎩 Notable contributions
 category: github
-description: This plugin displays badges of repositories where you commited at least once on default branch.
+description: |
+  This plugin displays badges for notable contributions on repositories.
 examples:
   +indepth analysis: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.indepth.svg
   contributions in organizations only: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.notable.svg
@@ -12,7 +13,8 @@ scopes:
 inputs:
 
   plugin_notable:
-    description: Enable notable plugin
+    description: |
+      Enable notable plugin
     type: boolean
     default: no
 
@@ -23,14 +25,15 @@ inputs:
       Based on [GitHub search syntax](https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax).
       Supported fields are `stars`, `forks` and `watchers`
 
-      If `plugin_notable_indepth` is enabled, `commits`, `commits.user`, `commits.user%` and `maintainer` fields are also supported.
+      If [`plugin_notable_indepth`](/source/plugins/notable/README.md#plugin_notable_indepth) is enabled, `commits`, `commits.user`, `commits.user%` and `maintainer` fields are also supported.
       Some repositories may not be able to reported advanced stats and in the case the default behaviour will be to bypass filtering
     type: string
     default: ""
     example: stars:>500 forks:>100 maintainer:true commits.user%:>5
 
   plugin_notable_skipped:
-    description: Skipped repositories
+    description: |
+      Skipped repositories
     type: array
     format: comma-separated
     default: ""
@@ -39,7 +42,8 @@ inputs:
 
   plugin_notable_from:
     description: |
-      Filter by repository owner account type
+      Repository owner account type filter
+
       - `all`: no filtering
       - `organization`: only organization accounts repositories
       - `user`: only user accounts repositories
@@ -52,17 +56,19 @@ inputs:
 
   plugin_notable_repositories:
     description: |
-      Toggle repository name display
+      Repository name
 
-      Note that Repositories hosted by user account will always be fully displayed
+      Repositories hosted by user account will always have their full handle displayed
     type: boolean
     default: no
 
   plugin_notable_indepth:
-    description: Indepth mode
+    description: |
+      Indepth mode
     type: boolean
     default: no
-    extras: yes
+    extras:
+      - metrics.api.github.overuse
 
   plugin_notable_types:
     description: |

source/plugins/pagespeed/metadata.yml

@@ -1,7 +1,8 @@
-name: "⏱️ Website performances"
+name: ⏱️ Google PageSpeed
 category: social
 description: |
-  This plugin adds performance statistics of a website.
+  This plugin displays performance statistics of a website.
+
   It uses [Google's PageSpeed API](https://developers.google.com/speed/docs/insights/v5/get-started) (same as [web.dev](https://web.dev)), see [performance scoring](https://web.dev/performance-scoring/) and [score calculator](https://googlechrome.github.io/lighthouse/scorecalc/) for more informations about results.
 examples:
   +PageSpeed scores: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.pagespeed.svg
@@ -16,12 +17,22 @@ scopes: []
 inputs:
 
   plugin_pagespeed:
-    description: Enable pagespeed plugin
+    description: |
+      Enable pagespeed plugin
     type: boolean
     default: no
 
+  plugin_pagespeed_token:
+    description: |
+      PageSpeed token
+
+      > ⚠️ While not mandatory, it is strongly advised pass a token to avoid triggering the rate limiter. See [PageSpeed documentation](https://developers.google.com/speed/docs/insights/v5/get-started) for more informations.
+    type: token
+    default: ""
+
   plugin_pagespeed_url:
-    description: Audited website
+    description: |
+      Audited website
     type: string
     default: .user.website
     preset: no
@@ -42,21 +53,14 @@ inputs:
 
   plugin_pagespeed_screenshot:
     description: |
-      Display a website screenshot
+      Website screenshot
 
       Significantly increase filesize
     type: boolean
     default: no
 
-  plugin_pagespeed_token:
-    description: |
-      PageSpeed token
-
-      Although not mandatory, it strongly advised to create one to avoid triggering the rate limiter. See [PageSpeed documentation](https://developers.google.com/speed/docs/insights/v5/get-started) for more informations.
-    type: token
-    default: ""
-
   plugin_pagespeed_pwa:
-    description: Display PWA Status
+    description: |
+      PWA Status
     type: boolean
     default: no

source/plugins/people/metadata.yml

@@ -1,6 +1,7 @@
-name: "🧑‍🤝‍🧑 People plugin"
+name: 🧑‍🤝‍🧑 People
 category: github
-description: This plugin can display relationships with users, such as followers, sponsors, contributors, stargazers, watchers, members, etc.
+description: |
+  This plugin can display relationships with users, such as followers, sponsors, contributors, stargazers, watchers, members, etc.
 examples:
   +related to a user: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.people.followers.svg
   related to a repository: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.people.repository.svg
@@ -14,12 +15,14 @@ scopes:
 inputs:
 
   plugin_people:
-    description: Enable people plugin
+    description: |
+      Enable people plugin
     type: boolean
     default: no
 
   plugin_people_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 24
     min: 0
@@ -27,25 +30,25 @@ inputs:
 
   plugin_people_identicons:
     description: |
-      Toggle identicons display
+      Force identicons pictures
 
-      This can be used to mask user profile pictures for privacy
+      Can be used to mask profile pictures for privacy
     type: boolean
     default: no
 
   plugin_people_identicons_hide:
     description: |
-      Hide identicons display
+      Hide identicons pictures
 
-      This can be used to mask user who did not setup a personal profile picture.
+      Can be used to mask users without a personal profile picture.
 
-      When used with `plugin_people_identicons`, users who did not setup a personal profile picture
+      When used with [`plugin_people_identicons`](/source/plugins/people/README.md#plugin_people_identicons), users without a personal profile picture will still be filtered out, but their picture will be replaced by an identicon instead
-      will still be filtered out, but will have their picture replaced by an identicon instead.
     type: boolean
     default: no
 
   plugin_people_size:
-    description: Profile picture display size
+    description: |
+      Profile picture display size
     type: number
     default: 28
     min: 8
@@ -53,7 +56,7 @@ inputs:
 
   plugin_people_types:
     description: |
-      Displayed sections (order is respected)
+      Displayed sections
 
       User and organization accounts support the following values:
       - `followers`
@@ -61,13 +64,16 @@ inputs:
       - `sponsoring`/`sponsored`
       - `sponsors`
       - `members` (organization only)
-      - `thanks`(to be configured with `plugin_people_thanks`)
+      - `thanks`(to be configured with [`plugin_people_thanks`](/source/plugins/people/README.md#plugin_people_thanks))
+
       Repositories support the following values:
       - `sponsors` (same as owner sponsors)
       - `contributors`
       - `stargazers`
       - `watchers`
-      - `thanks`(to be configured with `plugin_people_thanks`)
+      - `thanks`(to be configured with [`plugin_people_thanks`](/source/plugins/people/README.md#plugin_people_thanks))
+
+      Specified order is honored
     type: array
     format: comma-separated
     default: followers, following
@@ -89,7 +95,7 @@ inputs:
     description: |
       Special thanks
 
-      This list can be used to thank specific users
+      Can be used to thank specific users
     type: array
     format: comma-separated
     default: ""
@@ -101,7 +107,7 @@ inputs:
       Custom sponsors
 
       This list can be used to add users from unsupported GitHub sponsors sources.
-      The option `plugin_people_types` must contain the `sponsors` section in order for this setting to be effective
+      The option [`plugin_people_types`](/source/plugins/people/README.md#plugin_people_types) must contain the `sponsors` section in order for this setting to be effective
     type: array
     format: comma-separated
     default: ""
@@ -110,8 +116,9 @@ inputs:
 
   plugin_people_shuffle:
     description: |
-      Shuffle data for varied output
+      Shuffle data
 
-      This will fetch 10 times more data than `plugin_people_limit` to ensure output is always different
+      Can be used to create varied outputs
+      This will fetch additional data (10 times [`plugin_people_limit`](/source/plugins/people/README.md#plugin_people_limit)) to ensure output is always different
     type: boolean
     default: no

source/plugins/posts/metadata.yml

@@ -1,6 +1,7 @@
-name: "✒️ Recent posts"
+name: ✒️ Recent posts
 category: social
-description: This plugin displays recent articles from a specified external source.
+description: |
+  This plugin displays recent articles from a specified and supported external source.
 examples:
   +latest posts width description and cover image: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.posts.full.svg
   latest posts: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.posts.svg
@@ -13,13 +14,15 @@ scopes: []
 inputs:
 
   plugin_posts:
-    description: Enable posts plugin
+    description: |
+      Enable posts plugin
     type: boolean
     default: no
 
   plugin_posts_source:
     description: |
       External source
+
       - `dev.to`: [dev.to](https://dev.to)
       - `hashnode`: [hashnode.com](https://hashnode.com)
     type: string
@@ -28,26 +31,30 @@ inputs:
       - dev.to
       - hashnode
 
+  plugin_posts_user:
+    description: |
+      External source username
+    type: string
+    default: .user.login
+    preset: no
+
   plugin_posts_descriptions:
-    description: Toggle posts descriptions display
+    description: |
+      Posts descriptions
     type: boolean
     default: no
 
   plugin_posts_covers:
-    description: Toggle posts cover images display
+    description: |
+      Posts cover images
     type: boolean
     default: no
 
   plugin_posts_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 4
     min: 1
     max: 30
 
-  plugin_posts_user:
-    description: External source username
-    type: string
-    default: .user.login
-    preset: no
-

source/plugins/projects/metadata.yml

@@ -1,6 +1,9 @@
-name: "🗂️ Active projects"
+name: 🗂️ GitHub projects
 category: github
-description: This plugin displays progress of your profile and repository projects.
+description: |
+  This plugin displays progress of profile and repository projects.
+
+  > ℹ️ This plugin currently only supports [GitHub projects boards](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) and not [GitHub projects (beta)](https://docs.github.com/en/issues/trying-out-the-new-projects-experience/about-projects)
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.projects.svg
 index: 11
@@ -14,7 +17,8 @@ scopes:
 inputs:
 
   plugin_projects:
-    description: Enable projects plugin
+    description: |
+      Enable projects plugin
     type: boolean
     default: no
 
@@ -22,7 +26,7 @@ inputs:
     description: |
       Display limit
 
-      Note that `plugin_projects_repositories` is not affected by this option
+      Projects defined by [`plugin_projects_repositories`](/source/plugins/projects/README.md#plugin_projects_repositories) are not affected by this option
     type: number
     default: 4
     min: 0
@@ -30,7 +34,7 @@ inputs:
 
   plugin_projects_repositories:
     description: |
-      List of repositories projects
+      Featured repositories projects
 
       Use the following syntax for each project `:user/:repo/projects/:project_id`
     type: array
@@ -40,6 +44,7 @@ inputs:
     preset: no
 
   plugin_projects_descriptions:
-    description: Toggle projects descriptions display
+    description: |
+      Projects descriptions
     type: boolean
     default: no

source/plugins/reactions/metadata.yml

@@ -1,6 +1,7 @@
-name: "🎭 Comment reactions"
+name: 🎭 Comment reactions
 category: github
-description: This plugin displays overall reactions on your recent issues, comments and discussions.
+description: |
+  This plugin displays overall user reactions on recent issues, comments and discussions.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.reactions.svg
 index: 8
@@ -11,40 +12,46 @@ scopes:
 inputs:
 
   plugin_reactions:
-    description: Enable reactions plugin
+    description: |
+      Enable reactions plugin
     type: boolean
     default: no
 
   plugin_reactions_limit:
-    description: Display limit (issues and pull requests comments)
+    description: |
+      Display limit (issues and pull requests comments)
     type: number
     default: 200
     min: 0
     max: 1000
 
   plugin_reactions_limit_issues:
-    description: Display limit (issues and pull requests, first comment)
+    description: |
+      Display limit (issues and pull requests, first comment)
     type: number
     default: 100
     min: 0
     max: 1000
 
   plugin_reactions_limit_discussions:
-    description: Display limit (discussions, first comment)
+    description: |
+      Display limit (discussions, first comment)
     type: number
     default: 100
     min: 0
     max: 1000
 
   plugin_reactions_limit_discussions_comments:
-    description: Display limit (discussions comments)
+    description: |
+      Display limit (discussions comments)
     type: number
     default: 100
     min: 0
     max: 1000
 
   plugin_reactions_days:
-    description: Comments maximum age
+    description: |
+      Comments maximum age
     type: number
     default: 0
     min: 0
@@ -53,6 +60,7 @@ inputs:
   plugin_reactions_display:
     description: |
       Display mode
+
       - `absolute`: scale percentages using total reactions count
       - `relative`: scale percentages using highest reaction count
     type: string
@@ -62,7 +70,8 @@ inputs:
       - relative
 
   plugin_reactions_details:
-    description: Additional details
+    description: |
+      Additional details
     type: array
     format: comma-separated
     default: ""
@@ -75,7 +84,7 @@ inputs:
     description: |
       Ignored users
 
-      Useful to ignore bots activity
+      Can be used to ignore bots activity
     type: array
     format: comma-separated
     default: ""

source/plugins/repositories/metadata.yml

@@ -1,11 +1,11 @@
-name: "📓 Repositories"
+name: 📓 Featured repositories
 category: github
 description: |
   This plugin displays a list of chosen featured repositories.
 
-  It is mostly intended for images that will be used outside of GitHub, since it is already possible to [pin repositories](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile) on GitHub.
+  Since it is possible to [pin repositories](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile) on GitHub, this plugin is mostly intended for external usage.
 
-  > ⚠️ People will not be able to click on it due to limitations of using SVG inside `<img>` tags.
+  > ⚠️ Due to limitations of using SVG images inside `<img>` tags, clicking on a repository card will not redirect to repository page.
 examples:
   +featured: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.repositories.svg
   pinned: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.repositories.pinned.svg
@@ -18,24 +18,25 @@ scopes:
 inputs:
 
   plugin_repositories:
-    description: Enable repositories plugin
+    description: |
+      Enable repositories plugin
     type: boolean
     default: no
 
   plugin_repositories_featured:
     description: |
-      List of featured repositories
+      Featured repositories
 
-      If no owner is specified, it will implicitly use the current account login
+      Current [`user`](/source/plugins/core/README.md#user) will be used when no owner is specified
     type: array
     format: comma-separated
     default: ""
-    example: lowlighter/metrics
+    example: metrics, lowlighter/metrics
     preset: no
 
   plugin_repositories_pinned:
     description: |
-      Display pinned repositories
+      Pinned repositories
     type: number
     default: 0
     min: 0

source/plugins/rss/metadata.yml

@@ -1,6 +1,7 @@
-name: "🗼 Rss feed"
+name: 🗼 Rss feed
 category: social
-description: This plugin displays news from a given RSS feed.
+description: |
+  This plugin displays news from a given RSS feed.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.rss.svg
 index: 7
@@ -12,18 +13,21 @@ scopes: []
 inputs:
 
   plugin_rss:
-    description: Enable rss plugin
+    description: |
+      Enable rss plugin
     type: boolean
     default: no
 
   plugin_rss_source:
-    description: RSS feed source
+    description: |
+      RSS feed source
     type: string
     default: ""
     example: https://news.ycombinator.com/rss
 
   plugin_rss_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 4
     min: 0

source/plugins/skyline/metadata.yml

@@ -1,7 +1,7 @@
-name: "🌇 GitHub Skyline 3D calendar"
+name: 🌇 GitHub Skyline
 category: github
 description: |
-  This plugins lets you display your 3D commits calendar from [skyline.github.com](https://skyline.github.com/).
+  This plugin displays the 3D commits calendar from [skyline.github.com](https://skyline.github.com/).
 
   > ⚠️ This plugin significantly increase file size, consider using it as standalone.
 examples:
@@ -13,12 +13,16 @@ scopes: []
 inputs:
 
   plugin_skyline:
-    description: Enable skyline plugin
+    description: |
+      Enable skyline plugin
     type: boolean
     default: no
+    extras:
+      - metrics.npm.optional.gifencoder
 
   plugin_skyline_year:
-    description: Displayed year
+    description: |
+      Displayed year
     type: number
     default: current-year
     min: 2008
@@ -48,7 +52,7 @@ inputs:
     description: |
       Compatibility mode
 
-      This uses CSS animations rather than embedded GIF to support a widerr range of browser, like Firefox and Safari.
+      This uses CSS animations rather than embedded GIF to support a wider range of browsers, like Firefox and Safari.
       Using this mode significantly increase file size as each frame is encoded separately
     type: boolean
     default: no

source/plugins/sponsors/metadata.yml

@@ -1,6 +1,7 @@
-name: "💕 GitHub Sponsors"
+name: 💕 GitHub Sponsors
 category: github
-description: This plugin displays sponsors and introduction text from [GitHub sponsors](https://github.com/sponsors/).
+description: |
+  This plugin displays sponsors and introduction text from [GitHub sponsors](https://github.com/sponsors/).
 examples:
   +GitHub sponsors card: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.sponsors.svg
   GitHub sponsors full introduction: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.sponsors.full.svg
@@ -15,13 +16,15 @@ scopes:
 inputs:
 
   plugin_sponsors:
-    description: Enable sponsors plugin
+    description: |
+      Enable sponsors plugin
     type: boolean
     default: no
 
   plugin_sponsors_sections:
     description: |
       Displayed sections
+
       - `goal`: display GitHub active goal
       - `about`: display GitHub sponsors introduction
       - `list`: display GitHub sponsors list
@@ -36,16 +39,17 @@ inputs:
 
   plugin_sponsors_past:
     description: |
-      Display past sponsorships
+      Past sponsorships
 
-      This feature requires a token from target account, as past sponsorships are gathered from sponsors activity and is private data.
+      A [`token`](/source/plugins/core/README.md#token) from target [`user`](/source/plugins/core/README.md#user) must be specified to use this feature, as past sponsorships are gathered from sponsors activity which is private data.
 
-      > ⚠️ Past sponsorships does not respect sponsors privacy because of current GitHub API limitations. This may be fixed in future releases.
+      > ⚠️ Past sponsorships does not respect sponsors privacy because of current GitHub API limitations. This may be fixed in a future release.
     type: boolean
     default: no
 
   plugin_sponsors_size:
-    description: Profile picture display size
+    description: |
+      Profile picture display size
     type: number
     default: 24
     min: 8

source/plugins/stackoverflow/metadata.yml

@@ -1,6 +1,7 @@
-name: "🗨️ StackOverflow plugin"
+name: 🗨️ Stack Overflow
 category: social
-description: This plugin displays stats, questions and answer from [stackoverflow](https://stackoverflow.com/).
+description: |
+  This plugin displays stats, questions and answer from [Stack Overflow](https://stackoverflow.com/).
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.stackoverflow.svg
 index: 3
@@ -11,12 +12,14 @@ scopes: []
 inputs:
 
   plugin_stackoverflow:
-    description: Enable stackoverflow plugin
+    description: |
+      Enable stackoverflow plugin
     type: boolean
     default: no
 
   plugin_stackoverflow_user:
-    description: Stackoverflow user id
+    description: |
+      Stackoverflow user id
     type: number
     default: 0
     preset: no
@@ -24,6 +27,7 @@ inputs:
   plugin_stackoverflow_sections:
     description: |
       Displayed sections
+
       - `answers-top`: display most popular answers
       - `answers-recent`: display recent answers
       - `questions-top`: display most popular questions
@@ -38,7 +42,8 @@ inputs:
       - questions-recent
 
   plugin_stackoverflow_limit:
-    description: Display limit (per section)
+    description: |
+      Display limit (entries per section)
     type: number
     default: 2
     min: 1
@@ -46,16 +51,17 @@ inputs:
 
   plugin_stackoverflow_lines:
     description: |
-      Display limit for questions and answers
+      Display limit (lines per questions and answers)
 
-      Code snippets count as a single line and must be configured with `plugin_stackoverflow_lines_snippet` instead
+      Code snippets count as a single line and must be configured with [`plugin_stackoverflow_lines_snippet`](/source/plugins/stackoverflow/README.md#plugin_stackoverflow_lines_snippet) instead
     type: number
     default: 4
     min: 0
     zero: disable
 
   plugin_stackoverflow_lines_snippet:
-    description: Display limit for code snippets
+    description: |
+      Display limit (lines per code snippets)
     type: number
     default: 2
     min: 0

source/plugins/stargazers/metadata.yml

@@ -1,6 +1,7 @@
-name: "✨ Stargazers over last weeks"
+name: ✨ Stargazers over last weeks
 category: github
-description: This plugin displays your stargazers evolution across all of your repositories over the last two weeks.
+description: |
+  This plugin displays stargazers evolution across affiliated repositories over the last two weeks.
 examples:
   +classic charts: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.stargazers.svg
   chartist charts: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.stargazers.chartist.svg
@@ -14,17 +15,21 @@ scopes:
 inputs:
 
   plugin_stargazers:
-    description: Enable stargazers plugin
+    description: |
+      Enable stargazers plugin
     type: boolean
     default: no
 
   plugin_stargazers_charts_type:
     description: |
       Charts display type
+
       - `classic`: `<div>` based charts, simple and lightweight
       - `chartist`: `<svg>` based charts, smooth
     type: string
     default: classic
     values:
       - classic
-      - chartist
+      - chartist
+    extras:
+      - metrics.npm.optional.chartist

source/plugins/starlists/metadata.yml

@@ -1,6 +1,7 @@
-name: "💫 Starlists"
+name: 💫 Star lists
 category: github
-description: This plugin displays your star lists.
+description: |
+  This plugin displays star lists.
 examples:
   +repositories from star lists: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.starlists.svg
   +languages from star lists: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.starlists.languages.svg
@@ -11,38 +12,46 @@ scopes: []
 inputs:
 
   plugin_starlists:
-    description: Enable starlists plugin
+    description: |
+      Enable starlists plugin
     type: boolean
     default: no
 
   plugin_starlists_limit:
-    description: Display limit (star lists)
+    description: |
+      Display limit (star lists)
     type: number
     default: 2
     min: 1
     max: 100
 
   plugin_starlists_limit_repositories:
-    description: Display limit (repositories per star list)
+    description: |
+      Display limit (repositories per star list)
     type: number
     default: 2
     min: 0
     max: 100
 
   plugin_starlists_languages:
-    description: Toggle star list languages statistics
+    description: |
+      Star lists languages statistics
     type: boolean
     default: no
 
   plugin_starlists_limit_languages:
-    description: Disply limit (languages per star list)
+    description: |
+      Display limit (languages per star list)
     type: number
     default: 8
     min: 0
     zero: disable
 
   plugin_starlists_shuffle_repositories:
-    description: Shuffle data for varied outputs
+    description: |
+      Shuffle data
+
+      Can be used to create varied outputs
     type: boolean
     default: yes
 
@@ -50,7 +59,7 @@ inputs:
     description: |
       Skipped star lists
 
-      This is case and emojis insensitive
+      Case and emojis insensitive
     type: array
     format: comma-separated
     default: ""
@@ -58,10 +67,11 @@ inputs:
 
   plugin_starlists_only:
     description:  |
-      Restrict display to specified star lists
+      Showcased star lists
 
-      This is case and emojis insensitive.
+      Case and emojis insensitive.
-      This option is equivalent to `plugin_starlists_ignored` with all star lists but the ones listed in this option
+
+      Equivalent to [`plugin_starlists_ignored`](/source/plugins/starlists/README.md#plugin_starlists_ignored) with all star lists except the ones listed in this option
     type: array
     format: comma-separated
     default: ""

source/plugins/stars/metadata.yml

@@ -1,6 +1,7 @@
-name: "🌟 Recently starred repositories"
+name: 🌟 Recently starred repositories
 category: github
-description: This plugin displays your recently starred repositories.
+description: |
+  This plugin displays recently starred repositories.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.stars.svg
 index: 3
@@ -11,12 +12,14 @@ scopes:
 inputs:
 
   plugin_stars:
-    description: Enable stars plugin
+    description: |
+      Enable stars plugin
     type: boolean
     default: no
 
   plugin_stars_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 4
     min: 1

source/plugins/support/metadata.yml

@@ -1,6 +1,7 @@
-name: "💭 GitHub Community Support"
+name: 💭 GitHub Community Support
 category: github
-description: This plugin displays your statistics from [GitHub Support Community](https://github.community/) (an account must be created on it beforehand).
+description: |
+  This plugin displays statistics from a [GitHub Support Community](https://github.community/) account.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.support.svg
 index: 17
@@ -10,6 +11,7 @@ scopes: []
 inputs:
 
   plugin_support:
-    description: Enable support plugin
+    description: |
+      Enable support plugin
     type: boolean
     default: no

source/plugins/topics/metadata.yml

@@ -1,7 +1,8 @@
-name: "📌 Starred topics"
+name: 📌 Starred topics
 category: github
 description: |
   This plugin displays [starred topics](https://github.com/stars?filter=topics).
+
   Check out [GitHub topics](https://github.com/topics) to search interesting topics.
 examples:
   +with icons: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.topics.icons.svg
@@ -13,15 +14,17 @@ scopes: []
 inputs:
 
   plugin_topics:
-    description: Enable topics plugin
+    description: |
+      Enable topics plugin
     type: boolean
     default: no
 
   plugin_topics_mode:
     description: |
-      Display mode:
+      Display mode
+
       - `labels`: display labels
-      - `icons`: display icons *(topics without icons will be ignored)*
+      - `icons`: display icons *(topics without icons will not be displayed)*
       - `starred`: alias for `labels`
       - `mastered`: alias for `icons`
     type: string
@@ -34,11 +37,12 @@ inputs:
 
   plugin_topics_sort:
     description: |
-      Sorting method:
+      Sorting method
+
       - `stars`: sort by most stars
       - `activity`: sort by recent activity
-      - `starred`: sort by the date you starred them
+      - `starred`: sort by starred date
-      - `random`: sort topics randomly
+      - `random`: sort randomly
     type: string
     default: stars
     values:
@@ -50,8 +54,6 @@ inputs:
   plugin_topics_limit:
     description: |
       Display limit
-
-      When using `plugin_topics_mode: labels`, an ellipsis will be displayed
     type: number
     default: 15
     min: 0

source/plugins/traffic/metadata.yml

@@ -1,6 +1,7 @@
-name: "🧮 Repositories traffic"
+name: 🧮 Repositories traffic
 category: github
-description: This plugin displays the number of page views across your repositories.
+description: |
+  This plugin displays the number of page views across affiliated repositories.
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.traffic.svg
 index: 19
@@ -13,12 +14,14 @@ scopes:
 inputs:
 
   plugin_traffic:
-    description: Enable traffic plugin
+    description: |
+      Enable traffic plugin
     type: boolean
     default: no
 
   plugin_traffic_skipped:
-    description: Skipped repositories
+    description: |
+      Skipped repositories
     type: array
     format: comma-separated
     default: ""

source/plugins/tweets/metadata.yml

@@ -1,6 +1,7 @@
-name: "🐤 Latest tweets"
+name: 🐤 Latest tweets
 category: social
-description: This plugin displays the latest tweets from your [Twitter](https://twitter.com) account.
+description: |
+  This plugin displays the latest tweets from a [Twitter](https://twitter.com) account.
 examples:
   +latest tweets with attachments: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.tweets.attachments.svg
   latest tweets: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.tweets.svg
@@ -12,29 +13,37 @@ scopes: []
 inputs:
 
   plugin_tweets:
-    description: Enable tweets plugin
+    description: |
+      Enable tweets plugin
     type: boolean
     default: no
 
   plugin_tweets_token:
-    description: Twitter API token
+    description: |
+      Twitter API token
     type: token
     default: ""
 
+  plugin_tweets_user:
+    description: |
+      Twitter username
+    type: string
+    default: .user.twitter
+    preset: no
+
   plugin_tweets_attachments:
-    description: Display tweets attachments (images, video previews, etc.)
+    description: |
+      Tweets attachments
+
+      Can be used to display linked images, video thumbnails, etc.
     type: boolean
     default: no
 
   plugin_tweets_limit:
-    description: Display limit
+    description: |
+      Display limit
     type: number
     default: 2
     min: 1
     max: 10
 
-  plugin_tweets_user:
-    description: Twitter username
-    type: string
-    default: .user.twitter
-    preset: no

source/plugins/wakatime/metadata.yml

@@ -1,6 +1,9 @@
-name: "⏰ WakaTime plugin"
+name: ⏰ WakaTime
 category: social
-description: This plugin displays statistics from your [WakaTime](https://wakatime.com) account.
+description: |
+  This plugin displays statistics from a [WakaTime](https://wakatime.com) account.
+
+  It is also compatible with self-hosted instances from [wakapi](https://github.com/muety/wakapi).
 examples:
   default: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.wakatime.svg
 index: 8
@@ -10,37 +13,45 @@ scopes: []
 inputs:
 
   plugin_wakatime:
-    description: Enable wakatime plugin
+    description: |
+      Enable wakatime plugin
     type: boolean
     default: no
 
   plugin_wakatime_token:
-    description: WakaTime API token
+    description: |
+      WakaTime API token
     type: token
     default: ""
 
-  plugin_wakatime_days:
+  plugin_wakatime_url:
-    description: Time range
+    description: |
+      WakaTime URL
+
+      Can be used to specify a [wakapi](https://github.com/muety/wakapi) instance
     type: string
-    values:
+    default: https://wakatime.com
-      - 7
+
-      - 30
+  plugin_wakatime_user:
-      - 180
+    description: |
-      - 365
+      WakaTime username
-    default: 7
+    type: string
+    default: current
+    preset: no
 
   plugin_wakatime_sections:
     description: |
       Displayed sections
+
       - `time`: show total coding time and daily average
       - `projects`: show most time spent project
       - `projects-graphs`: show most time spent projects graphs
-      - `languages`: show most language
+      - `languages`: show most used language
       - `languages-graphs`: show languages graphs
       - `editors`: show most used code editor
       - `editors-graphs`: show code editors graphs
       - `os`: show most used operating system
-      - `os-graphs`: show code operating systems graphs
+      - `os-graphs`: show operating systems graphs
     type: array
     values:
       - time
@@ -54,34 +65,34 @@ inputs:
       - os-graphs
     default: time, projects, projects-graphs, languages, languages-graphs, editors, os
 
+  plugin_wakatime_days:
+    description: |
+      Time range
+    type: string
+    values:
+      - 7
+      - 30
+      - 180
+      - 365
+    default: 7
+
   plugin_wakatime_limit:
-    description: Display limit (per graph)
+    description: |
+      Display limit (entries per graph)
     type: number
     default: 5
     min: 0
     zero: disable
 
-  plugin_wakatime_url:
-    description: |
-      WakaTime url
-
-      Also compatible with self-hosted instance ([wakapi](https://github.com/muety/wakapi))
-    type: string
-    default: https://wakatime.com
-
-  plugin_wakatime_user:
-    description: WakaTime username
-    type: string
-    default: current
-    preset: no
-
   plugin_wakatime_languages_other:
-    description: Include other languages
+    description: |
+      Other languages
     type: boolean
     default: no
 
   plugin_wakatime_languages_ignored:
-    description: Ignored languages
+    description: |
+      Ignored languages
     type: array
     format: comma-separated
     default: ""
@@ -91,7 +102,7 @@ inputs:
     description: |
       Repositories visibility
 
-      Lets you hide private repositories.
+      Can be used to toggle private activity visibility
     type: string
     default: all
     values: