docs(plugins): clarification, fix typos and style

2022-07-04 23:18:01 -04:00
parent 3c00e64c57
commit 52ca4d04b7
47 changed files with 733 additions and 408 deletions
--- a/.github/readme/partials/documentation/setup/web.md
+++ b/.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

--- a/.github/scripts/quickstart/plugin/metadata.yml
+++ b/.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
--- a/.github/scripts/quickstart/template/metadata.yml
+++ b/.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:
--- a/source/app/metrics/metadata.mjs
+++ b/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
--- a/source/plugins/achievements/metadata.yml
+++ b/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: ""
--- a/source/plugins/activity/metadata.yml
+++ b/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: ""
--- a/source/plugins/anilist/metadata.yml
+++ b/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
--- a/source/plugins/base/metadata.yml
+++ b/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
-      * `activity`, which contains recent activity (commits, pull requests, issues, etc.)
-      * `community`, which contains community stats (following, sponsors, organizations, etc.)
-      * `repositories`, which contains repository stats (license, forks, stars, etc.)
-      * `metadata`, which contains information about generated metrics
+      - `header`, which usually contains username, two-weeks commits calendars and a few additional data
+      - `activity`, which contains recent activity (commits, pull requests, issues, etc.)
+      - `community`, which contains community stats (following, sponsors, organizations, etc.)
+      - `repositories`, which contains repository stats (license, forks, stars, etc.)
+      - `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),
-      try lowering this value.
+      If you receive `Something went wrong while executing your query` (which is usually caused by API timeouts), lowering this value may help.
+      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.
-      Broad affiliation will result in less representative metrics.
+      Set to `""` to disable and fetch all repositories related to given account.
+      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
--- a/source/plugins/calendar/metadata.yml
+++ b/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

--- a/source/plugins/code/metadata.yml
+++ b/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: ""
--- a/source/plugins/community/README.md
+++ b/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: |
      {
--- a/source/plugins/community/fortune/metadata.yml
+++ b/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
--- a/source/plugins/community/nightscout/metadata.yml
+++ b/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
--- a/source/plugins/community/poopmap/metadata.yml
+++ b/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
--- a/source/plugins/community/screenshot/metadata.yml
+++ b/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.
-  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).
+  This plugin displays a screenshot from any website.
+
+  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
--- a/source/plugins/community/stock/metadata.yml
+++ b/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
--- a/source/plugins/contributors/metadata.yml
+++ b/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
--- a/source/plugins/core/metadata.yml
+++ b/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.
-      Note that when doing so, all defaults values using `.user.*` will not be applicable meaning that they need to be filled manually.
-      Most of the time `user` option must also be set.
+      When using a configuration which does not requires a GitHub PAT, it is possible to pass `NOT_NEEDED` instead.
+      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.
    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
--- a/source/plugins/discussions/metadata.yml
+++ b/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
--- a/source/plugins/followup/metadata.yml
+++ b/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
--- a/source/plugins/gists/metadata.yml
+++ b/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
--- a/source/plugins/habits/metadata.yml
+++ b/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
--- a/source/plugins/introduction/metadata.yml
+++ b/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
--- a/source/plugins/isocalendar/metadata.yml
+++ b/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
--- a/source/plugins/languages/metadata.yml
+++ b/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: Displayed sections
+    description: |
+      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: Indepth mode (⚠️ read documentation first)
+    description: |
+      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: Indepth mode - Analysis timeout
+    description: |
+      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: Indepth mode - Displayed categories (most-used section)
+    description: |
+      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: Indepth mode - Displayed categories (recently-used section)
+    description: |
+      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: Events to load (recently-used section)
+    description: |
+      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: Events maximum age (day, recently-used section)
+    description: |
+      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
--- a/source/plugins/licenses/metadata.yml
+++ b/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
--- a/source/plugins/lines/metadata.yml
+++ b/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: ""
--- a/source/plugins/music/metadata.yml
+++ b/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
--- a/source/plugins/notable/metadata.yml
+++ b/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: |
--- a/source/plugins/pagespeed/metadata.yml
+++ b/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
--- a/source/plugins/people/metadata.yml
+++ b/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
-      will still be filtered out, but will have their picture replaced by an identicon instead.
+      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
    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
--- a/source/plugins/posts/metadata.yml
+++ b/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
-
--- a/source/plugins/projects/metadata.yml
+++ b/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
--- a/source/plugins/reactions/metadata.yml
+++ b/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: ""
--- a/source/plugins/repositories/metadata.yml
+++ b/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
--- a/source/plugins/rss/metadata.yml
+++ b/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
--- a/source/plugins/skyline/metadata.yml
+++ b/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
--- a/source/plugins/sponsors/metadata.yml
+++ b/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
--- a/source/plugins/stackoverflow/metadata.yml
+++ b/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
--- a/source/plugins/stargazers/metadata.yml
+++ b/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,13 +15,15 @@ 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
@@ -28,3 +31,5 @@ inputs:
    values:
      - classic
      - chartist
+    extras:
+      - metrics.npm.optional.chartist
--- a/source/plugins/starlists/metadata.yml
+++ b/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.
-      This option is equivalent to `plugin_starlists_ignored` with all star lists but the ones listed in this option
+      Case and emojis insensitive.
+
+      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: ""
--- a/source/plugins/stars/metadata.yml
+++ b/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
--- a/source/plugins/support/metadata.yml
+++ b/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
--- a/source/plugins/topics/metadata.yml
+++ b/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
-      - `random`: sort topics randomly
+      - `starred`: sort by starred date
+      - `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
--- a/source/plugins/traffic/metadata.yml
+++ b/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: ""
--- a/source/plugins/tweets/metadata.yml
+++ b/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
--- a/source/plugins/wakatime/metadata.yml
+++ b/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:
-    description: Time range
+  plugin_wakatime_url:
+    description: |
+      WakaTime URL
+
+      Can be used to specify a [wakapi](https://github.com/muety/wakapi) instance
    type: string
-    values:
-      - 7
-      - 30
-      - 180
-      - 365
-    default: 7
+    default: https://wakatime.com
+
+  plugin_wakatime_user:
+    description: |
+      WakaTime username
+    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: