docs: updated workflows examples and options descriptions (#772) [skip ci]

.github/examples.mjs

@@ -0,0 +1,44 @@
+//Imports
+import fs from "fs/promises"
+import fss from "fs"
+import paths from "path"
+import url from "url"
+import metadata from "../source/app/metrics/metadata.mjs"
+import yaml from "js-yaml"
+
+//Paths
+const __metrics = paths.join(paths.dirname(url.fileURLToPath(import.meta.url)), "..")
+const __templates = paths.join(paths.join(__metrics, "source/templates/"))
+const __plugins = paths.join(paths.join(__metrics, "source/plugins/"))
+
+//Load plugins metadata
+const {plugins, templates} = await metadata({log:false, diff:true})
+
+async function plugin(id) {
+  const path = paths.join(__plugins, id)
+  const readme = paths.join(path, "README.md")
+  const examples = paths.join(path, "examples.yml")
+  return {
+    readme:{
+      path:readme,
+      content:`${await fs.readFile(readme)}`
+    },
+    examples:fss.existsSync(examples) ? yaml.load(await fs.readFile(examples), "utf8") ?? [] : [],
+    options:plugins[id].readme.table
+  }
+}
+
+//Plugins
+for (const id of Object.keys(plugins)) {
+  const {examples, options, readme} = await plugin(id)
+  //Plugin readme
+  await fs.writeFile(readme.path, readme.content
+    .replace(/(<!--examples-->)[\s\S]*(<!--\/examples-->)/g, `$1\n${examples.map(({test, prod, ...step}) => ["```yaml", yaml.dump(step), "```"].join("\n")).join("\n")}\n$2`)
+    .replace(/(<!--options-->)[\s\S]*(<!--\/options-->)/g, `$1\n${options}\n$2`)
+  )
+  //Plugin tests
+}
+
+//Templates
+
+//Workflow

source/app/metrics/metadata.mjs

@@ -3,12 +3,16 @@ import fs from "fs"
 import yaml from "js-yaml"
 import path from "path"
 import url from "url"
+import fetch from "node-fetch"
 
 //Defined categories
 const categories = ["core", "github", "social", "community"]
 
+//Previous descriptors
+let previous = null
+
 /**Metadata descriptor parser */
-export default async function metadata({log = true} = {}) {
+export default async function metadata({log = true, diff = false} = {}) {
   //Paths
   const __metrics = path.join(path.dirname(url.fileURLToPath(import.meta.url)), "../../..")
   const __templates = path.join(__metrics, "source/templates")
@@ -19,6 +23,16 @@ export default async function metadata({log = true} = {}) {
   //Init
   const logger = log ? console.debug : () => null
 
+  //Diff with latest version
+  if (diff) {
+    try {
+      previous = yaml.load(await fetch("https://raw.githubusercontent.com/lowlighter/metrics/latest/action.yml").then(response => response.text()))
+    }
+    catch (error) {
+      logger(error)
+    }
+  }
+
   //Load plugins metadata
   let Plugins = {}
   logger("metrics/metadata > loading plugins metadata")
@@ -254,8 +268,47 @@ metadata.plugin = async function({__plugins, name, logger}) {
       const raw = `${await fs.promises.readFile(path.join(__plugins, name, "README.md"), "utf-8")}`
       const demo = raw.match(/(?<demo><table>[\s\S]*?<[/]table>)/)?.groups?.demo?.replace(/<[/]?(?:table|tr)>/g, "")?.trim() ?? "<td></td>"
 
+      //Options table
+      const table = [
+        "| Option | Type *(format)* **[default]** *{allowed values}* | Description |",
+        "| ------ | -------------------------------- | ----------- |",
+        Object.entries(inputs).map(([option, {description, type, ...o}]) => {
+          let row = []
+          {
+            const cell = [`${"`"}${option}${"`"}`]
+            if (type === "token")
+              cell.push("🔐")
+            if (!Object.keys(previous?.inputs ?? {}).includes(option))
+              cell.push("✨")
+            row.push(cell.join(" "))
+          }
+          {
+            const cell = [`${"`"}${type}${"`"}`]
+            if ("format" in o)
+              cell.push(`*(${o.format})*`)
+            if ("default" in o)
+              cell.push(`**[${o.default}]**`)
+            if ("values" in o)
+              cell.push(`*{${o.values.map(value => `"${value}"`).join(", ")}}*`)
+            if ("min" in o)
+              cell.push(`*{${o.min} ≤`)
+            if (("min" in o)||("max" in o))
+              cell.push(`${"min" in o ? "" : "*{"}𝑥${"max" in o ? "" : "}*"}`)
+            if ("max" in o)
+              cell.push(`≤ ${o.max}}*`)
+            row.push(cell.join(" "))
+          }
+          row.push(description)
+          return `| ${row.join(" | ")} |`
+        }).join("\n"),
+        "\n",
+        "Legend for option icons:",
+        "* 🔐 Value should be stored in repository secrets",
+        "* ✨ New feature currently in testing on `master`/`main`"
+      ].flat(Infinity).filter(s => s).join("\n")
+
       //Readme descriptor
-      meta.readme = {demo}
+      meta.readme = {demo, table}
     }
 
     //Icon

source/plugins/achievements/README.md

@@ -27,19 +27,54 @@ It also lets you quickly see at a glance what this user primarly use GitHub for,
 
 ![Ranks](/.github/readme/imgs/plugin_achievements_ranks.png)
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_achievements` | `boolean` **[no]** | Display achievements |
+| `plugin_achievements_threshold` | `string` **[C]** *{"S", "A", "B", "C", "X"}* | Display rank minimal threshold |
+| `plugin_achievements_secrets` | `boolean` **[yes]** | Display unlocked secrets achievements |
+| `plugin_achievements_display` | `string` **[detailed]** *{"detailed", "compact"}* | Achievements display style |
+| `plugin_achievements_limit` | `number` **[0]** *{0 ≤ 𝑥}* | Maximum number of achievements to display |
+| `plugin_achievements_ignored` | `array` *(comma-separated)* **[]** | Unlocked achievements to hide |
+| `plugin_achievements_only` | `array` *(comma-separated)* **[]** | Unlocked achievements to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Detailed display
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_achievements: yes
+  filename: metrics.plugin.achievements.svg
-    plugin_achievements_threshold: B      # Display achievements with rank B or higher
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_achievements_secrets: yes      # Display unlocked secrets achievements
+  base: ''
-    plugin_achievements_display: compact  # Use compact display
+  plugin_achievements: 'yes'
-    plugin_achievements_limit: 0          # Display all unlocked achievements (no limit)
+  plugin_achievements_only: sponsor, maintainer, octonaut
-    plugin_achievements_ignored: octonaut # Hide "octonaut" achievement
+
-    plugin_achievements_only: explorer    # Display only "explorer" achievement (don't use with "ignored" option)
 ```
+```yaml
+name: Compact display
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.achievements.compact.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_achievements: 'yes'
+  plugin_achievements_only: >-
+    polyglot, stargazer, sponsor, deployer, member, maintainer, developer,
+    scripter, packager, explorer, infographile, manager
+  plugin_achievements_display: compact
+  plugin_achievements_threshold: X
+
+```
+<!--/examples-->

source/plugins/achievements/examples.yml

@@ -0,0 +1,23 @@
+- name: Detailed display
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.achievements.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_achievements: yes
+    plugin_achievements_only: sponsor, maintainer, octonaut
+  test:
+    timeout: 900000
+
+- name: Compact display
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.achievements.compact.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_achievements: yes
+    plugin_achievements_only: polyglot, stargazer, sponsor, deployer, member, maintainer, developer, scripter, packager, explorer, infographile, manager
+    plugin_achievements_display: compact
+    plugin_achievements_threshold: X
+  test:
+    timeout: 900000

source/plugins/activity/README.md

@@ -29,20 +29,43 @@ It uses data from [GitHub events](https://docs.github.com/en/free-pro-team@lates
 
 Use a full `repo` scope token to display **private** events.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_activity` | `boolean` **[no]** | Display recent activity |
+| `plugin_activity_limit` | `number` **[5]** *{1 ≤ 𝑥 ≤ 1000}* | Maximum number of events to display |
+| `plugin_activity_load` | `number` **[300]** *{100 ≤ 𝑥 ≤ 1000}* | Number of events to load |
+| `plugin_activity_days` | `number` **[14]** *{0 ≤ 𝑥 ≤ 365}* | Maximum event age |
+| `plugin_activity_filter` | `array` *(comma-separated)* **[all]** *{"all", "comment", "ref/create", "ref/delete", "release", "push", "issue", "pr", "review", "wiki", "fork", "star", "member", "public"}* | Events types to keep |
+| `plugin_activity_visibility` | `string` **[all]** *{"public", "all"}* | Set events visibility |
+| `plugin_activity_timestamps` | `boolean` **[no]** | Display events timestamps |
+| `plugin_activity_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
+| `plugin_activity_ignored` | `undefined` **[github-actions[bot], dependabot[bot], dependabot-preview[bot]]** | Actors to ignore |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Recent activity
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_activity: yes
+  filename: metrics.plugin.activity.svg
-    plugin_activity_limit: 5           # Limit to 5 events
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_activity_load: 100          # Load up to 100 recent events from API (should be higher than "limit")
+  base: ''
-    plugin_activity_days: 14           # Keep only events from last 14 days (set to 0 for no limit)
+  plugin_activity: 'yes'
-    plugin_activity_filter: all        # Show all events (use table above to filter events types)
+  plugin_activity_limit: 5
-    plugin_activity_visibility: public # Only display public events
+  plugin_activity_days: 0
-    plugin_activity_timestamps: yes    # Display events timestamps
+  plugin_activity_filter: issue, pr, release, fork, review, ref/create
-    plugin_activity_skipped: repo      # Ignored repositories
+
 ```
+<!--/examples-->

source/plugins/activity/examples.yml

@@ -0,0 +1,10 @@
+- name: Recent activity
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.activity.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_activity: yes
+    plugin_activity_limit: 5
+    plugin_activity_days: 0
+    plugin_activity_filter: issue, pr, release, fork, review, ref/create

source/plugins/anilist/README.md

@@ -25,19 +25,63 @@ This plugin is composed of the following sections, which can be displayed or hid
 
 These sections can also be filtered by media type, which can be either `anime`, `manga` or both.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_anilist` | `boolean` **[no]** | Display data from your AniList account |
+| `plugin_anilist_medias` | `array` *(comma-separated)* **[anime, manga]** *{"anime", "manga"}* | Medias types to display |
+| `plugin_anilist_sections` | `array` *(comma-separated)* **[favorites]** *{"favorites", "watching", "reading", "characters"}* | Sections to display |
+| `plugin_anilist_limit` | `number` **[2]** *{0 ≤ 𝑥}* | Maximum number of entries to display per section |
+| `plugin_anilist_limit_characters` | `number` **[22]** *{0 ≤ 𝑥}* | Maximum number of entries to display in characters section |
+| `plugin_anilist_shuffle` | `boolean` **[yes]** | Shuffle AniList data |
+| `plugin_anilist_user` | `string` **[.user.login]** | AniList login |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Favorites anime and currently watching
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_anilist: yes
+  filename: metrics.plugin.anilist.svg
-    plugin_anilist_medias: anime, manga            # Display both animes and mangas
+  token: NOT_NEEDED
-    plugin_anilist_sections: favorites, characters # Display only favorites and characters sections
+  plugin_anilist: 'yes'
-    plugin_anilist_limit: 2                        # Limit to 2 entry per section (characters section excluded)
+  plugin_anilist_medias: anime
-    plugin_anilist_limit_characters: 22            # Limit to 22 characters in characters section
+  plugin_anilist_sections: favorites, watching
-    plugin_anilist_shuffle: yes                    # Shuffle data for more varied outputs
+  plugin_anilist_limit: 1
-    plugin_anilist_user: .user.login               # Use same username as GitHub login
+
 ```
+```yaml
+name: Favorites manga and currently reading
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.anilist.manga.svg
+  token: NOT_NEEDED
+  plugin_anilist: 'yes'
+  plugin_anilist_medias: manga
+  plugin_anilist_sections: favorites, reading
+  plugin_anilist_limit: 1
+
+```
+```yaml
+name: Favorites characters
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.anilist.characters.svg
+  token: NOT_NEEDED
+  plugin_anilist: 'yes'
+  plugin_anilist_sections: characters
+  plugin_anilist_limit_characters: 22
+
+```
+<!--/examples-->

source/plugins/anilist/examples.yml

@@ -0,0 +1,28 @@
+- name: Favorites anime and currently watching
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.anilist.svg
+    token: NOT_NEEDED
+    plugin_anilist: yes
+    plugin_anilist_medias: anime
+    plugin_anilist_sections: favorites, watching
+    plugin_anilist_limit: 1
+
+- name: Favorites manga and currently reading
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.anilist.manga.svg
+    token: NOT_NEEDED
+    plugin_anilist: yes
+    plugin_anilist_medias: manga
+    plugin_anilist_sections: favorites, reading
+    plugin_anilist_limit: 1
+
+- name: Favorites characters
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.anilist.characters.svg
+    token: NOT_NEEDED
+    plugin_anilist: yes
+    plugin_anilist_sections: characters
+    plugin_anilist_limit_characters: 22

source/plugins/base/README.md

@@ -24,19 +24,29 @@ It contains the following sections:
 
 These are all enabled by default, but you can explicitely opt out from them.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `base` | `array` *(comma-separated)* **[header, activity, community, repositories, metadata]** *{"header", "activity", "community", "repositories", "metadata"}* | Metrics base content |
+| `repositories` | `number` **[100]** *{0 ≤ 𝑥}* | Number of repositories to use |
+| `repositories_batch` | `number` **[100]** *{1 ≤ 𝑥 ≤ 100}* | Number of repositories to load at once by queries |
+| `repositories_forks` | `boolean` **[no]** | Include forks in metrics |
+| `repositories_affiliations` | `array` *(comma-separated)* **[owner]** *{"owner", "collaborator", "organization_member"}* | Repositories affiliations |
+| `repositories_skipped` | `array` *(comma-separated)* **[]** | Default repositories to skip |
+| `commits_authoring` | `array` *(comma-seperated)* **[.user.login]** | List of surnames or email addresses you use when authoring commits |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
 
-```yaml
+<!--/examples-->
-- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    base: header, repositories                     # Only display "header" and "repositories" sections
-    repositories: 100                              # Query only last 100 repositories
-    repositories_batch: 25                         # Query repositories 25 by 25 (lower this to avoid API timeouts)
-    repositories_forks: no                         # Don't include forks
-    repositories_affiliations: owner, collaborator # Display only repositories where user is owner or collaborator
-    repositories_skipped: lowlighter/lowlighter    # Exclude automatically "lowlighter/lowlighter" repository from plugins allowing a skip list
-    commits_authoring: octocat@github.com          # Handle you use when authoring commits, which can be used to filter commits in other plugins
-```

source/plugins/code/README.md

@@ -11,18 +11,39 @@ Display a random code snippet from your recent activity history.
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_code` | `boolean` **[no]** | Display a random code snippet from recent activity |
+| `plugin_code_lines` | `number` **[12]** | Maximum number of line that a code snippet can contain |
+| `plugin_code_load` | `number` **[100]** *{100 ≤ 𝑥 ≤ 1000}* | Number of events to load |
+| `plugin_code_visibility` | `string` **[public]** *{"public", "all"}* | Set events visibility |
+| `plugin_code_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
+| `plugin_code_languages` | `array` *(comma-separated)* **[]** | Restrict code snippet languages |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: JavaScript or TypeScript snippet of the day
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_code: yes
+  filename: metrics.plugin.code.svg
-    plugin_code_lines: 12               # Only display snippets with less than 12 lines
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_code_load: 100               # Fetch 100 events from activity
+  base: ''
-    plugin_code_visibility: public      # Only display snippets from public activity
+  plugin_code: 'yes'
-    plugin_code_skipped: github/octocat # Skip github/octocat repository
+  plugin_code_languages: javascript, typescript
-    plugin_code_languages: javascript   # Limit code snippets to JavaScript code
+  plugin_code_load: 400
-```
+
+```
+<!--/examples-->

source/plugins/code/examples.yml

@@ -0,0 +1,9 @@
+- name: JavaScript or TypeScript snippet of the day
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.code.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_code: yes
+    plugin_code_languages: javascript, typescript
+    plugin_code_load: 400

source/plugins/contributors/README.md

@@ -34,24 +34,65 @@ plugin_contributors_categories: |
 Each time a file modified by a contributor match a fileglob, they will be added in said category.
 Matching is performed in keys order.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_contributors` | `boolean` **[no]** | Display repository contributors |
+| `plugin_contributors_base` | `string` **[]** | Base reference |
+| `plugin_contributors_head` | `string` **[master]** | Head reference |
+| `plugin_contributors_ignored` | `array` *(comma-separated)* **[github-actions[bot], dependabot[bot], dependabot-preview[bot]]** | Contributors to ignore |
+| `plugin_contributors_contributions` | `boolean` **[no]** | Display contributions |
+| `plugin_contributors_sections` | `array` *(comma-separated)* **[contributors]** *{"contributors", "categories"}* | Sections to display |
+| `plugin_contributors_categories` | `json` **[{
+  "📚 Documentation": ["README.md", "docs/**"],
+  "💻 Code": ["source/**", "src/**"],
+  "#️⃣ Others": ["*"]
+}
+]** | Contributions categories |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Contributors with contributions count
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_contributors: yes
+  filename: metrics.plugin.contributors.contributions.svg
-    plugin_contributors_base: ""               # Base reference (commit, tag, branch, etc.)
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_contributors_head: main             # Head reference (commit, tag, branch, etc.)
+  base: ''
-    plugin_contributors_ignored: bot           # Ignore "bot" user
+  template: repository
-    plugin_contributors_contributions: yes     # Display number of contributions for each contributor
+  repo: metrics
-    plugin_contributors_sections: contributors # Display contributors sections
+  plugin_contributors: 'yes'
-    plugin_contributors_categories: |          # A JSON mapping of labels by files edited
+  plugin_contributors_contributions: 'yes'
-      {
+
-        "📚 Documentation": ["README.md", "docs/**"],
+```
-        "💻 Code": ["source/**", "src/**"],
+```yaml
-        "#️⃣ Others": ["*"]
+name: Contributors by categories
-      }
+uses: lowlighter/metrics@latest
-```
+with:
+  filename: metrics.plugin.contributors.categories.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  template: repository
+  repo: metrics
+  plugin_contributors: 'yes'
+  plugin_contributors_sections: categories
+  plugin_contributors_categories: |
+    {
+      "🧩 Plugins / 🖼️ templates":["source/plugins/**", "source/templates/**"],
+      "📚 Documentation":["README.md", "**/README.md", "**/metadata.yml"],
+      "💻 Code (other)":["source/**", "Dockerfile"]
+    }
+
+```
+<!--/examples-->

source/plugins/contributors/examples.yml

@@ -0,0 +1,27 @@
+- name: Contributors with contributions count
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.contributors.contributions.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    template: repository
+    repo: metrics
+    plugin_contributors: yes
+    plugin_contributors_contributions: yes
+
+- name: Contributors by categories
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.contributors.categories.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    template: repository
+    repo: metrics
+    plugin_contributors: yes
+    plugin_contributors_sections: categories
+    plugin_contributors_categories: |
+      {
+        "🧩 Plugins / 🖼️ templates":["source/plugins/**", "source/templates/**"],
+        "📚 Documentation":["README.md", "**/README.md", "**/metadata.yml"],
+        "💻 Code (other)":["source/**", "Dockerfile"]
+      }

source/plugins/core/README.md

@@ -2,7 +2,58 @@
 
 Metrics also have general options that impact global metrics rendering.
 
-[➡️ Available options](metadata.yml)
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `token` 🔐 | `token` | GitHub Personal Token |
+| `user` | `string` **[]** | GitHub username |
+| `repo` | `string` **[]** | GitHub repository |
+| `committer_token` 🔐 | `token` **[${{ github.token }}]** | GitHub Token used to commit metrics |
+| `committer_branch` | `string` **[]** | Branch used to commit rendered metrics |
+| `committer_message` | `string` **[Update ${filename} - [Skip GitHub Action]]** | Commit message |
+| `committer_gist` | `string` **[]** | Gist used to store metrics |
+| `filename` | `string` **[github-metrics.*]** | Rendered metrics output path |
+| `markdown` | `string` **[TEMPLATE.md]** | Rendered markdown output path |
+| `markdown_cache` | `string` **[.cache]** | Rendered markdown file cache |
+| `output_action` | `string` **[commit]** *{"none", "commit", "pull-request", "pull-request-merge", "pull-request-squash", "pull-request-rebase", "gist"}* | Output action |
+| `output_condition` | `string` **[always]** *{"always", "data-changed"}* | Output condition |
+| `optimize` | `array` *(comma-separated)* **[css, xml]** *{"css", "xml", "svg"}* | SVG optimization |
+| `setup_community_templates` | `array` *(comma-separated,/(?<user>[-a-z0-9]+)[/](?<repo>[-a-z0-9]+)@(?<branch>[-a-z0-9]+):(?<template>[-a-z0-9]+)/)* **[]** | Additional community templates to setup |
+| `template` | `string` **[classic]** | Template to use |
+| `query` | `json` **[{}]** | Additional query parameters |
+| `extras_css` | `string` **[]** | Extra CSS |
+| `config_timezone` | `string` **[]** | Timezone used |
+| `config_order` | `array` *(comma-separated)* **[]** | Configure content order |
+| `config_twemoji` | `boolean` **[no]** | Use twemojis instead of emojis |
+| `config_gemoji` | `boolean` **[yes]** | Use GitHub custom emojis |
+| `config_display` | `string` **[regular]** *{"regular", "large", "columns"}* | Render display width |
+| `config_animations` | `boolean` **[yes]** | SVG CSS animations |
+| `config_base64` | `boolean` **[yes]** | Encode images links into base64 data |
+| `config_padding` | `string` **[0, 8 + 11%]** | Image padding |
+| `config_output` | `string` **[auto]** *{"auto", "svg", "png", "jpeg", "json", "markdown", "markdown-pdf", "insights"}* | Output image format |
+| `retries` | `number` **[3]** *{1 ≤ 𝑥 ≤ 10}* | Number of retries |
+| `retries_delay` | `number` **[300]** *{0 ≤ 𝑥 ≤ 3600}* | Time to wait (in seconds) before each retry |
+| `retries_output_action` | `number` **[5]** *{1 ≤ 𝑥 ≤ 10}* | Number of retries (output action) |
+| `retries_delay_output_action` | `number` **[120]** *{0 ≤ 𝑥 ≤ 3600}* | Time to wait (in seconds) before each retry (output action) |
+| `plugins_errors_fatal` | `boolean` **[no]** | Die on plugins errors |
+| `debug` | `boolean` **[no]** | Debug logs |
+| `verify` | `boolean` **[no]** | Verify SVG |
+| `debug_flags` | `array` *(space-separated)* **[]** *{"--cakeday", "--hireable", "--halloween", "--error"}* | Debug flags |
+| `dryrun` | `boolean` **[no]** | Enable dry-run |
+| `experimental_features` | `array` *(space-separated)* **[]** *{"--optimize-svg"}* | Experimental features |
+| `use_mocked_data` | `boolean` **[no]** | Use mocked data instead of live APIs |
+| `use_prebuilt_image` | `boolean` **[yes]** | Use pre-built image from GitHub registry |
+| `delay` | `number` **[0]** *{0 ≤ 𝑥 ≤ 3600}* | Use this to avoid triggering abuse mechanics on large workflows |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
 
 ### 🛠️ General configuration
 

source/plugins/discussions/README.md

@@ -9,13 +9,35 @@ The *discussions* plugin displays your GitHub discussions metrics.
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_discussions` | `boolean` **[no]** | GitHub discussions metrics |
+| `plugin_discussions_categories` ✨ | `boolean` **[yes]** | Display discussion categories |
+| `plugin_discussions_categories_limit` ✨ | `number` **[0]** | Number of discussion categories to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: GitHub Discussions
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_discussions: yes
+  filename: metrics.plugin.discussions.svg
-```
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_discussions: 'yes'
+  plugin_discussions_categories_limit: 8
+
+```
+<!--/examples-->

source/plugins/discussions/examples.yml

@@ -0,0 +1,8 @@
+- name: GitHub Discussions
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.discussions.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_discussions: yes
+    plugin_discussions_categories_limit: 8

source/plugins/followup/README.md

@@ -17,15 +17,56 @@ The *followup* plugin displays the ratio of open/closed issues and the ratio of
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_followup` | `boolean` **[no]** | Display follow-up of repositories issues and pull requests |
+| `plugin_followup_sections` | `array` *(comma-separated)* **[repositories]** *{"repositories", "user"}* | Sections to display |
+| `plugin_followup_indepth` | `boolean` **[no]** | Indepth follow-up processing |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Opened on user's repositories
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_followup: yes
+  filename: metrics.plugin.followup.svg
-    plugin_followup_sections: repositories, user # Display overall status of issues/pull requests created on user's repositories and created by user
+  token: ${{ secrets.METRICS_TOKEN }}
-```
+  base: ''
+  plugin_followup: 'yes'
 
+```
+```yaml
+name: Opened by user
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.followup.user.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_followup: 'yes'
+  plugin_followup_sections: user
+
+```
+```yaml
+name: Indepth analysis
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.followup.indepth.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_followup: 'yes'
+  plugin_followup_indepth: 'yes'
+
+```
+<!--/examples-->

source/plugins/followup/examples.yml

@@ -0,0 +1,25 @@
+- name: Opened on user's repositories
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.followup.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_followup: yes
+
+- name: Opened by user
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.followup.user.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_followup: yes
+    plugin_followup_sections: user
+
+- name: Indepth analysis
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.followup.indepth.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_followup: yes
+    plugin_followup_indepth: yes

source/plugins/gists/README.md

@@ -9,13 +9,32 @@ The *gists* plugin displays your [gists](https://gist.github.com) metrics.
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_gists` | `boolean` **[no]** | Display gists metrics |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Gists
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_gists: yes
+  filename: metrics.plugin.gists.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_gists: 'yes'
+
 ```
+<!--/examples-->

source/plugins/gists/examples.yml

@@ -0,0 +1,7 @@
+- name: Gists
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.gists.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_gists: yes

source/plugins/habits/README.md

@@ -25,19 +25,53 @@ By default, dates use Greenwich meridian (GMT/UTC). Be sure to set your timezone
 
 > 🔣 On web instances, *recent languages activity* is an extra feature and must be enabled globally in `settings.json`
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_habits` | `boolean` **[no]** | Display coding habits metrics |
+| `plugin_habits_from` | `number` **[200]** *{1 ≤ 𝑥 ≤ 1000}* | Number of events to use |
+| `plugin_habits_days` | `number` **[14]** *{1 ≤ 𝑥 ≤ 30}* | Maximum event age |
+| `plugin_habits_facts` | `boolean` **[yes]** | Display coding habits collected facts based on recent activity |
+| `plugin_habits_charts` | `boolean` **[no]** | Display coding habits charts based on recent activity |
+| `plugin_habits_trim` | `boolean` **[no]** | Trim unused hours on daily chart |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Midly interesting facts
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_habits: yes
+  filename: metrics.plugin.habits.facts.svg
-    plugin_habits_from: 200       # Use 200 events to compute habits
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_habits_days: 14        # Keep only events from last 14 days
+  base: ''
-    plugin_habits_facts: yes      # Display facts section
+  plugin_habits: 'yes'
-    plugin_habits_charts: yes     # Display charts section
+  plugin_habits_facts: 'yes'
-    plugin_habits_trim: yes       # Trim unused hours on daily chart
+  plugin_habits_charts: 'no'
-    config_timezone: Europe/Paris # Set timezone
+  config_timezone: Europe/Paris
+
 ```
+```yaml
+name: Recent activity charts
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.habits.charts.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_habits: 'yes'
+  plugin_habits_facts: 'no'
+  plugin_habits_charts: 'yes'
+  config_timezone: Europe/Paris
+
+```
+<!--/examples-->

source/plugins/habits/examples.yml

@@ -0,0 +1,21 @@
+- name: Midly interesting facts
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.habits.facts.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_habits: yes
+    plugin_habits_facts: yes
+    plugin_habits_charts: no
+    config_timezone: Europe/Paris
+
+- name: Recent activity charts
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.habits.charts.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_habits: yes
+    plugin_habits_facts: no
+    plugin_habits_charts: yes
+    config_timezone: Europe/Paris

source/plugins/introduction/README.md

@@ -15,14 +15,46 @@ It is mostly intended for metrics used outside of GitHub, since these informatio
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_introduction` | `boolean` **[no]** | Display account or repository introduction |
+| `plugin_introduction_title` | `boolean` **[yes]** | Display introduction section title |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: User introduction
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_introduction: yes
+  filename: metrics.plugin.introduction.svg
-    plugin_introduction_title: no # Hide section title
+  token: ${{ secrets.METRICS_TOKEN }}
-```
+  user: github
+  base: header
+  plugin_introduction: 'yes'
+
+```
+```yaml
+name: Repository introduction
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.introduction.repository.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  template: repository
+  repo: metrics
+  base: header
+  plugin_introduction: 'yes'
+
+```
+<!--/examples-->

source/plugins/introduction/examples.yml

@@ -0,0 +1,20 @@
+- name: User introduction
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.introduction.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    user: github
+    base: header
+    plugin_introduction: yes
+  prod:
+    token: ${{ secrets.METRICS_BOT_TOKEN }}
+
+- name: Repository introduction
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.introduction.repository.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    template: repository
+    repo: metrics
+    base: header
+    plugin_introduction: yes

source/plugins/isocalendar/README.md

@@ -14,14 +14,44 @@ The *isocalendar* plugin displays an isometric view of your commits calendar, al
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_isocalendar` | `boolean` **[no]** | Display an isometric view of your commits calendar |
+| `plugin_isocalendar_duration` | `string` **[half-year]** *{"half-year", "full-year"}* | Set time window shown by isometric calendar |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Half-year calendar
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_isocalendar: yes
+  filename: metrics.plugin.isocalendar.svg
-    plugin_isocalendar_duration: full-year # Display full year instead of half year
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_isocalendar: 'yes'
+
 ```
+```yaml
+name: Full-year calendar
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.isocalendar.fullyear.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_isocalendar: 'yes'
+  plugin_isocalendar_duration: full-year
+
+```
+<!--/examples-->

source/plugins/isocalendar/examples.yml

@@ -0,0 +1,16 @@
+- name: Half-year calendar
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.isocalendar.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_isocalendar: yes
+
+- name: Full-year calendar
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.isocalendar.fullyear.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_isocalendar: yes
+    plugin_isocalendar_duration: full-year

source/plugins/languages/README.md

@@ -43,29 +43,98 @@ Since Git lets you use any email and name for commits, metrics may not be able t
 
 For better results, it's advised to add either your surnames and eventually no-reply email addresses.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_languages` | `boolean` **[no]** | Display most used languages metrics |
+| `plugin_languages_ignored` | `array` *(comma-separated)* **[]** | Languages to ignore |
+| `plugin_languages_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
+| `plugin_languages_limit` | `number` **[8]** *{0 ≤ 𝑥 ≤ 8}* | Maximum number of languages to display |
+| `plugin_languages_sections` | `array` *(comma-separated)* **[most-used]** *{"most-used", "recently-used"}* | Sections to display |
+| `plugin_languages_colors` | `array` *(comma-separated,/((?<index>[0-9])|(?<language>[-+a-z0-9#]+)):(?<color>#?[-a-z0-9]+)/)* **[github]** | Custom languages colors |
+| `plugin_languages_aliases` | `string` **[]** | Custom languages names |
+| `plugin_languages_details` | `array` *(comma-separated)* **[]** *{"bytes-size", "percentage", "lines"}* | Additional details |
+| `plugin_languages_threshold` | `string` **[0%]** | Minimum threshold |
+| `plugin_languages_indepth` | `boolean` **[false]** | Indepth languages processing (see documentation before enabling) |
+| `plugin_languages_analysis_timeout` | `number` **[15]** *{1 ≤ 𝑥 ≤ 30}* | Languages analysis timeout |
+| `plugin_languages_categories` | `array` *(comma-separated)* **[markup, programming]** *{"data", "markup", "programming", "prose"}* | Language categories to display |
+| `plugin_languages_recent_categories` | `array` *(comma-separated)* **[markup, programming]** *{"data", "markup", "programming", "prose"}* | Language categories to display (for recently used section) |
+| `plugin_languages_recent_load` | `number` **[300]** *{100 ≤ 𝑥 ≤ 1000}* | Number of events to load (for recently used section) |
+| `plugin_languages_recent_days` | `number` **[14]** *{0 ≤ 𝑥 ≤ 365}* | Maximum event age (for recently used section) |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Most used
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_languages: yes
+  filename: metrics.plugin.languages.svg
-    plugin_languages_ignored: html, css                           # List of languages to ignore
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_languages_skipped: my-test-repo                        # List of repositories to skip
+  base: ''
-    plugin_languages_limit: 8                                     # Display up to 8 languages
+  plugin_languages: 'yes'
-    plugin_languages_sections: most-used, recently-used           # Display most used and recently used
+  plugin_languages_ignored: >-
-    plugin_languages_colors: "0:orange, javascript:#ff0000, ..."  # Make most used languages orange and JavaScript red
+    html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
-    plugin_languages_aliases: "JavaScript:JS, TypeScript:TS, ..." # Customize languages names with aliases
+    gnuplot
-    plugin_languages_details: bytes-size, percentage              # Additionally display total bytes size and percentage
+  plugin_languages_limit: 4
-    plugin_languages_threshold: 2%                                # Hides all languages less than 2%
+
-    languages stats
-    plugin_languages_indepth: no                                  # Get indepth stats (see documentation before enabling)
-    plugin_languages_analysis_timeout: 15                         # Set maximum time for indepth analysis
-    plugin_languages_categories: programming                      # Display only languages that match these categories in most-used section
-    plugin_languages_recent_categories: markup, programming, data # Display only languages that match these categories in recently-used section
-    plugin_languages_recent_load: 500                             # Load up to 500 events to compute recently used stats
-    plugin_languages_recent_days: 7                               # Limit recently used stats to last week
-    commits_authoring: octocat@users.noreply.github.com           # Surnames or email addresses used to identify your commits
 ```
+```yaml
+name: Most used (with details)
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.languages.details.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_languages: 'yes'
+  plugin_languages_ignored: >-
+    html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
+    gnuplot
+  plugin_languages_details: bytes-size, percentage
+  plugin_languages_limit: 4
+
+```
+```yaml
+name: Recently used
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.languages.recent.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_languages: 'yes'
+  plugin_languages_ignored: >-
+    html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
+    gnuplot
+  plugin_languages_sections: recently-used
+  plugin_languages_details: bytes-size, percentage
+  plugin_languages_limit: 4
+
+```
+```yaml
+name: Indepth analysis
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.languages.indepth.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_languages: 'yes'
+  plugin_languages_ignored: >-
+    html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
+    gnuplot
+  plugin_languages_indepth: 'yes'
+  plugin_languages_details: lines, bytes-size
+  plugin_languages_limit: 4
+  plugin_languages_analysis_timeout: 15
+
+```
+<!--/examples-->

source/plugins/languages/examples.yml

@@ -0,0 +1,45 @@
+- name: Most used
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.languages.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_languages: yes
+    plugin_languages_ignored: html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell, gnuplot
+    plugin_languages_limit: 4
+
+- name: Most used (with details)
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.languages.details.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_languages: yes
+    plugin_languages_ignored: html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell, gnuplot
+    plugin_languages_details: bytes-size, percentage
+    plugin_languages_limit: 4
+
+- name: Recently used
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.languages.recent.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_languages: yes
+    plugin_languages_ignored: html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell, gnuplot
+    plugin_languages_sections: recently-used
+    plugin_languages_details: bytes-size, percentage
+    plugin_languages_limit: 4
+
+- name: Indepth analysis
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.languages.indepth.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_languages: yes
+    plugin_languages_ignored: html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell, gnuplot
+    plugin_languages_indepth: yes
+    plugin_languages_details: lines, bytes-size
+    plugin_languages_limit: 4
+    plugin_languages_analysis_timeout: 15

source/plugins/licenses/README.md

@@ -24,19 +24,52 @@ Project must be setup with dependencies using `plugin_licenses_setup` option (fo
 
 Dependencies will be analyzed with [github/licensed](https://github.com/github/licensed) and compared against GitHub known licenses.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_licenses` | `boolean` **[no]** | Display licenses informations |
+| `plugin_licenses_setup` | `string` **[]** | Command to setup target repository |
+| `plugin_licenses_ratio` | `boolean` **[no]** | Display used licenses ratio |
+| `plugin_licenses_legal` | `boolean` **[yes]** | Display legal informations about used licenses |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Licenses and permissions
-  with:
+with:
-    # ... other options
+  filename: metrics.plugin.licenses.svg
-    template: repository
+  token: ${{ secrets.METRICS_TOKEN }}
-    user: repository-owner
+  base: ''
-    repo: repository-name
+  template: repository
-    plugin_licenses: yes
+  repo: metrics
-    plugin_licenses_setup: npm ci       # Command to setup target repository
+  plugin_licenses: 'yes'
-    plugin_licenses_ratio: yes          # Display used licenses ratio
+  plugin_licenses_setup: npm ci
-    plugin_licenses_legal: yes          # Display permissions, limitations and conditions
+
-```
+```
+```yaml
+name: Licenses with open-source ratio graphs
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.licenses.ratio.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  template: repository
+  repo: metrics
+  plugin_licenses: 'yes'
+  plugin_licenses_setup: npm ci
+  plugin_licenses_legal: 'no'
+  plugin_licenses_ratio: 'yes'
+
+```
+<!--/examples-->

source/plugins/licenses/examples.yml

@@ -0,0 +1,22 @@
+- name: Licenses and permissions
+  with:
+    filename: metrics.plugin.licenses.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    template: repository
+    repo: metrics
+    plugin_licenses: yes
+    plugin_licenses_setup: npm ci
+
+- name: Licenses with open-source ratio graphs
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.licenses.ratio.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    template: repository
+    repo: metrics
+    plugin_licenses: yes
+    plugin_licenses_setup: npm ci
+    plugin_licenses_legal: no
+    plugin_licenses_ratio: yes

source/plugins/lines/README.md

@@ -9,14 +9,33 @@ The *lines* of code plugin displays the number of lines of code you have added a
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_lines` | `boolean` **[no]** | Display lines of code metrics |
+| `plugin_lines_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Lines of code changed
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_lines: yes
+  filename: metrics.plugin.lines.svg
-    plugin_lines_skipped: repo # List of skipped repositories
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: repositories
+  plugin_lines: 'yes'
+
 ```
+<!--/examples-->

source/plugins/lines/examples.yml

@@ -0,0 +1,7 @@
+- name: Lines of code changed
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.lines.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: repositories
+    plugin_lines: yes

source/plugins/music/README.md

@@ -205,61 +205,121 @@ Click on the Name of any matching request. In the “Headers” tab, scroll to t
 
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_music` | `boolean` **[no]** | Display your music tracks |
+| `plugin_music_provider` | `string` **[]** *{"apple", "spotify", "lastfm", "youtube"}* | Music provider |
+| `plugin_music_token` 🔐 | `token` **[]** | Music provider personal token |
+| `plugin_music_mode` | `string` **[]** *{"playlist", "recent", "top"}* | Plugin mode |
+| `plugin_music_playlist` | `string` **[]** | Embed playlist url |
+| `plugin_music_limit` | `number` **[4]** *{1 ≤ 𝑥 ≤ 100}* | Maximum number of tracks to display |
+| `plugin_music_played_at` | `boolean` **[no]** | Display when the track was played |
+| `plugin_music_time_range` | `string` **[short]** *{"short", "medium", "long"}* | Time period for top mode |
+| `plugin_music_top_type` | `string` **[tracks]** *{"tracks", "artists"}* | Whether to show tracks or artists in top mode |
+| `plugin_music_user` | `string` **[.user.login]** | Music provider username |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
-##### Recent
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Apple Music - Random track from playlist
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_music: yes
+  filename: metrics.plugin.music.playlist.svg
-    plugin_music_provider: spotify # Use Spotify as provider
+  token: NOT_NEEDED
-    plugin_music_mode: recent      # Set plugin mode
+  plugin_music: 'yes'
-    plugin_music_limit: 4          # Limit to 4 entries
+  plugin_music_playlist: https://embed.music.apple.com/fr/playlist/usr-share/pl.u-V9D7m8Etjmjd0D
-    plugin_music_played_at: yes    # Show timestamp (for spotify only)
+  plugin_music_limit: 2
-    plugin_music_token: "${{ secrets.SPOTIFY_CLIENT_ID }}, ${{ secrets.SPOTIFY_CLIENT_SECRET }}, ${{ secrets.SPOTIFY_REFRESH_TOKEN }}"
-```
 
+```
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Spotify - Random track from playlist
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_music: yes
+  filename: metrics.plugin.music.playlist.spotify.svg
-    plugin_music_provider: lastfm  # Use Last.fm as provider
+  token: NOT_NEEDED
-    plugin_music_mode: recent      # Set plugin mode
+  plugin_music: 'yes'
-    plugin_music_limit: 4          # Limit to 4 entries
+  plugin_music_playlist: https://open.spotify.com/embed/playlist/3nfA87oeJw4LFVcUDjRcqi
-    plugin_music_user: .user.login # Use same username as GitHub login
+
-    plugin_music_token: ${{ secrets.LASTFM_API_KEY }}
 ```
-
-##### Top
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Spotify - Recently listed
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_music: yes
+  filename: metrics.plugin.music.recent.svg
-    plugin_music_provider: spotify # Use Spotify as provider
+  token: NOT_NEEDED
-    plugin_music_mode: top         # Set plugin mode
+  plugin_music: 'yes'
-    plugin_music_limit: 4          # Limit to 4 entries, maximum is 50 for "top" mode with spotify
+  plugin_music_provider: spotify
-    plugin_music_top_type: tracks  # Set type for "top" mode; either tracks or artists
+  plugin_music_mode: recent
-    plugin_music_time_range: short # Set time range for "top" mode; either short (4 weeks), medium (6 months) or long (several years)
+  plugin_music_token: ${{ secrets.SPOTIFY_TOKENS }}
-    plugin_music_token: "${{ secrets.SPOTIFY_CLIENT_ID }}, ${{ secrets.SPOTIFY_CLIENT_SECRET }}, ${{ secrets.SPOTIFY_REFRESH_TOKEN }}"
+  plugin_music_limit: 2
-```
 
-```yaml
-- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_music: yes
-    plugin_music_provider: lastfm  # Use Last.fm as provider
-    plugin_music_mode: top         # Set plugin mode
-    plugin_music_limit: 4          # Limit to 4 entries
-    plugin_music_top_type: artists # Set type for "top" mode; either tracks or artists
-    plugin_music_time_range: long  # Set time range for "top" mode; either short (4 weeks), medium (6 months) or long (several years)
-    plugin_music_user: .user.login # Use same username as GitHub login
-    plugin_music_token: ${{ secrets.LASTFM_API_KEY }}
 ```
+```yaml
+name: Spotify - Top tracks
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_mode: top
+  plugin_music_provider: spotify
+  plugin_music_time_range: short
+  plugin_music_top_type: tracks
+
+```
+```yaml
+name: Spotify - Top artists
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_mode: top
+  plugin_music_provider: spotify
+  plugin_music_time_range: long
+  plugin_music_top_type: artists
+
+```
+```yaml
+name: Youtube Music - Random track from playlist
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music: 'yes'
+  plugin_music_playlist: >-
+    https://music.youtube.com/playlist?list=OLAK5uy_kU_uxp9TUOl9zVdw77xith8o9AknVwz9U
+
+```
+```yaml
+name: Youtube Music - Recently listed
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music_token: ${{ secrets.YOUTUBE_MUSIC_TOKENS }}
+  plugin_music: 'yes'
+  plugin_music_mode: recent
+  plugin_music_provider: youtube
+
+```
+```yaml
+name: Last.fm  - Recently listed
+uses: lowlighter/metrics@latest
+with:
+  token: NOT_NEEDED
+  plugin_music_token: ${{ secrets.LASTFM_TOKEN }}
+  plugin_music: 'yes'
+  plugin_music_provider: lastfm
+  plugin_music_user: RJ
+
+```
+<!--/examples-->

source/plugins/music/examples.yml

@@ -0,0 +1,82 @@
+- name: Apple Music - Random track from playlist
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.music.playlist.svg
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_playlist: https://embed.music.apple.com/fr/playlist/usr-share/pl.u-V9D7m8Etjmjd0D
+    plugin_music_limit: 2
+
+- name: Spotify - Random track from playlist
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.music.playlist.spotify.svg
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_playlist: https://open.spotify.com/embed/playlist/3nfA87oeJw4LFVcUDjRcqi
+
+- name: Spotify - Recently listed
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.music.recent.svg
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_provider: spotify
+    plugin_music_mode: recent
+    plugin_music_token: ${{ secrets.SPOTIFY_TOKENS }}
+    plugin_music_limit: 2
+  test:
+    plugin_music_token: MOCKED_CLIENT_ID, MOCKED_CLIENT_SECRET, MOCKED_REFRESH_TOKEN
+
+- name: Spotify - Top tracks
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_mode: top
+    plugin_music_provider: spotify
+    plugin_music_time_range: short
+    plugin_music_top_type: tracks
+  test:
+    plugin_music_token: MOCKED_CLIENT_ID, MOCKED_CLIENT_SECRET, MOCKED_REFRESH_TOKEN
+
+- name: Spotify - Top artists
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_mode: top
+    plugin_music_provider: spotify
+    plugin_music_time_range: long
+    plugin_music_top_type: artists
+  test:
+    plugin_music_token: MOCKED_CLIENT_ID, MOCKED_CLIENT_SECRET, MOCKED_REFRESH_TOKEN
+
+- name: Youtube Music - Random track from playlist
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music: yes
+    plugin_music_playlist: https://music.youtube.com/playlist?list=OLAK5uy_kU_uxp9TUOl9zVdw77xith8o9AknVwz9U
+
+- name: Youtube Music - Recently listed
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music_token: ${{ secrets.YOUTUBE_MUSIC_TOKENS }}
+    plugin_music: yes
+    plugin_music_mode: recent
+    plugin_music_provider: youtube
+  test:
+    plugin_music_token: SAPISID=MOCKED_COOKIE; OTHER_PARAM=OTHER_VALUE;
+
+- name: Last.fm  - Recently listed
+  uses: lowlighter/metrics@latest
+  with:
+    token: NOT_NEEDED
+    plugin_music_token: ${{ secrets.LASTFM_TOKEN }}
+    plugin_music: yes
+    plugin_music_provider: lastfm
+    plugin_music_user: RJ
+  test:
+    plugin_music_token: MOCKED_TOKEN

source/plugins/nightscout/README.md

@@ -16,19 +16,35 @@ The [nightscout website](http://www.nightscout.info/) details how to self-host a
 
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_nightscout` | `boolean` **[no]** | Displays Blood Glucose |
+| `plugin_nightscout_url` | `string` **[https://example.herokuapp.com]** | Your Nightscout site URL |
+| `plugin_nightscout_datapoints` | `number` **[12]** *{0 ≤ 𝑥}* | How many datapoints to show on the graph. 0 and 1 disable the graph. |
+| `plugin_nightscout_lowalert` | `number` **[80]** *{0 ≤ 𝑥}* | When the blood sugar is considered low |
+| `plugin_nightscout_highalert` | `number` **[180]** *{0 ≤ 𝑥}* | When the blood sugar is considered high |
+| `plugin_nightscout_urgentlowalert` | `number` **[50]** *{0 ≤ 𝑥}* | When the blood sugar is considered urgently low |
+| `plugin_nightscout_urgenthighalert` | `number` **[250]** *{0 ≤ 𝑥}* | When the blood sugar is considered urgently high |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+uses: lowlighter/metrics@latest
-  with:
+with:
-    # ... other options
+  plugin_nightscout: 'yes'
-    plugin_nightscout: yes
+  plugin_nightscout_url: ${{ secrets.NIGHTSCOUT_URL }}
-    plugin_nightscout_url: ${{ secrets.NIGHTSCOUT_URL }} # Use the github actions "NIGHTSCOUT_URL" secret as your nightscout site
+
-    plugin_nightscout_datapoints: 12                     # Use the latest 12 blood sugar datapoints to create a graph
+```
-    plugin_nightscout_lowalert: 80                       # Blood sugars below 80 will be considered low
+<!--/examples-->
-    plugin_nightscout_highalert: 180                     # Blood sugars above 180 will be considered high
-    plugin_nightscout_urgentlowalert: 50                 # Blood sugars below 50 will be considered urgently low
-    plugin_nightscout_urgenthighalert: 250               # Blood sugars above 250 will be considered urgently high
-```

source/plugins/nightscout/examples.yml

@@ -0,0 +1,6 @@
+- uses: lowlighter/metrics@latest
+  with:
+    plugin_nightscout: yes
+    plugin_nightscout_url: ${{ secrets.NIGHTSCOUT_URL }}
+  prod:
+    skip: true

source/plugins/notable/README.md

@@ -21,17 +21,48 @@ The `plugin_notable_indepth` option lets you get additional metrics about your c
 
 > 🔣 On web instances, `indepth` is an extra feature and must be enabled globally in `settings.json`
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_notable` | `boolean` **[no]** | Display notable contributions in organizations |
+| `plugin_notable_filter` | `string` **[]** | Query filter |
+| `plugin_notable_from` | `string` **[organization]** *{"all", "organization", "user"}* | Filter by repository host account type |
+| `plugin_notable_repositories` | `boolean` **[no]** | Also display repository name |
+| `plugin_notable_indepth` | `boolean` **[no]** | Indepth notable contributions processing |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Contributions
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_notable: yes
+  filename: metrics.plugin.notable.svg
-    plugin_notable_filter: stars:>500 # Only display repositories with 500 stars or more (syntax based on GitHub search query)
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_notable_from: organization # Only display contributions within organization repositories
+  base: ''
-    plugin_notable_repositories: yes  # Display repositories name instead of only organization name
+  plugin_notable: 'yes'
-    plugin_notable_indepth: yes       # Gather additional informations about contributions
+
-```
+```
+```yaml
+name: Indepth analysis
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.notable.indepth.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_notable: 'yes'
+  plugin_notable_indepth: 'yes'
+  plugin_notable_repositories: 'yes'
+
+```
+<!--/examples-->

source/plugins/notable/examples.yml

@@ -0,0 +1,17 @@
+- name: Contributions
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.notable.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_notable: yes
+
+- name: Indepth analysis
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.notable.indepth.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_notable: yes
+    plugin_notable_indepth: yes
+    plugin_notable_repositories: yes

source/plugins/pagespeed/README.md

@@ -26,17 +26,58 @@ Although not mandatory, you can generate an API key for PageSpeed API [here](htt
 
 Expect 10 to 30 seconds to generate the results.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_pagespeed` | `boolean` **[no]** | Display a website Google PageSpeed metrics |
+| `plugin_pagespeed_url` | `string` **[.user.website]** | Audited website |
+| `plugin_pagespeed_detailed` | `boolean` **[no]** | Detailed audit result |
+| `plugin_pagespeed_screenshot` | `boolean` **[no]** | Display a screenshot of your website |
+| `plugin_pagespeed_token` 🔐 | `token` **[]** | PageSpeed token |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Succint report
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_pagespeed: yes
+  filename: metrics.plugin.pagespeed.svg
-    plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }} # Optional but recommended
+  token: NOT_NEEDED
-    plugin_pagespeed_detailed: yes                         # Print detailed audit metrics
+  plugin_pagespeed: 'yes'
-    plugin_pagespeed_screenshot: no                        # Display a screenshot of your website
+  plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
-    plugin_pagespeed_url: .user.website                    # Website to audit (defaults to your GitHub linked website)
+
 ```
+```yaml
+name: Detailed report
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.pagespeed.detailed.svg
+  token: NOT_NEEDED
+  plugin_pagespeed: 'yes'
+  plugin_pagespeed_detailed: 'yes'
+  plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
+
+```
+```yaml
+name: Screenshot
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.pagespeed.screenshot.svg
+  token: NOT_NEEDED
+  plugin_pagespeed: 'yes'
+  plugin_pagespeed_screenshot: 'yes'
+  plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
+
+```
+<!--/examples-->

source/plugins/pagespeed/examples.yml

@@ -0,0 +1,26 @@
+- name: Succint report
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.pagespeed.svg
+    token: NOT_NEEDED
+    plugin_pagespeed: yes
+    plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
+
+- name: Detailed report
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.pagespeed.detailed.svg
+    token: NOT_NEEDED
+    plugin_pagespeed: yes
+    plugin_pagespeed_detailed: yes
+    plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
+
+- name: Screenshot
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.pagespeed.screenshot.svg
+    token: NOT_NEEDED
+    plugin_pagespeed: yes
+    plugin_pagespeed_screenshot: yes
+    plugin_pagespeed_token: ${{ secrets.PAGESPEED_TOKEN }}
+

source/plugins/people/README.md

@@ -33,20 +33,56 @@ The following types are supported:
 Sections will be ordered the same as specified in `plugin_people_types`.
 `sponsors` for repositories will output the same as the owner's sponsors.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_people` | `boolean` **[no]** | Display GitHub users from various affiliations |
+| `plugin_people_limit` | `number` **[24]** *{0 ≤ 𝑥}* | Maximum number of user to display |
+| `plugin_people_size` | `number` **[28]** *{8 ≤ 𝑥 ≤ 64}* | Size of displayed GitHub users' avatars |
+| `plugin_people_types` | `array` *(comma-separated)* **[followers, following]** *{"followers", "following", "followed", "sponsoring", "members", "sponsored", "sponsors", "contributors", "stargazers", "watchers", "thanks"}* | Affiliations to display |
+| `plugin_people_thanks` | `array` *(comma-separated)* **[]** | GitHub users to personally thanks |
+| `plugin_people_sponsors_custom` | `array` *(comma-separated)* **[]** | Custom GitHub sponsors |
+| `plugin_people_identicons` | `boolean` **[no]** | Use identicons instead of avatars |
+| `plugin_people_shuffle` | `boolean` **[no]** | Shuffle users |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Followers
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_people: yes
+  filename: metrics.plugin.people.followers.svg
-    plugin_people_types: followers, thanks     # Display followers and "thanks" sections
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_people_limit: 28                    # Limit to 28 entries per section
+  base: ''
-    plugin_people_size: 28                     # Size in pixels of displayed avatars
+  plugin_people: 'yes'
-    plugin_people_identicons: no               # Use avatars (do not use identicons)
+  plugin_people_types: followers
-    plugin_people_thanks: lowlighter, octocat  # Users that will be displayed in "thanks" section
+
-    plugin_people_sponsors_custom: octocat     # Users that will be displayed additionally in "sponsors" section
-    plugin_people_shuffle: yes                 # Shuffle for varied output
 ```
+```yaml
+name: Contributors and sponsors
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.people.repository.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  template: repository
+  repo: metrics
+  plugin_people: 'yes'
+  plugin_people_types: contributors, stargazers, watchers, sponsors
+  plugin_people_sponsors_custom: >-
+    iamsainikhil, yutkat, KasparJohannesSchneider, ktnkk, tfSheol, haribo-io,
+    marcreichel
+
+```
+<!--/examples-->

source/plugins/people/examples.yml

@@ -0,0 +1,21 @@
+- name: Followers
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.people.followers.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_people: yes
+    plugin_people_types: followers
+
+- name: Contributors and sponsors
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.people.repository.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    template: repository
+    repo: metrics
+    plugin_people: yes
+    plugin_people_types: contributors, stargazers, watchers, sponsors
+    # Note that active sponsors are automatically added, but I want to thanks previous sponsors too!
+    plugin_people_sponsors_custom: iamsainikhil, yutkat, KasparJohannesSchneider, ktnkk, tfSheol, haribo-io, marcreichel

source/plugins/poopmap/README.md

@@ -39,15 +39,30 @@ Extract the `token` query paramater from the link
 You now have your PoopMap token! This token will not expire and it can only access public details.
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_poopmap` | `boolean` **[no]** | Display PoopMap stats |
+| `plugin_poopmap_token` 🔐 | `token` **[]** | PoopMap API token |
+| `plugin_poopmap_days` | `number` **[7]** *{"7", "30", "180", "365"}* | PoopMap time range |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+uses: lowlighter/metrics@latest
-  with:
+with:
-    # ... other options
+  plugin_poopmap: 'yes'
-    plugin_poopmap: yes
+
-    plugin_poopmap_token: ${{ secrets.POOPMAP_TOKEN }}      # Required
-    plugin_poopmap_days: 7                                  # Display last week stats
 ```
+<!--/examples-->

source/plugins/poopmap/examples.yml

@@ -0,0 +1,5 @@
+- uses: lowlighter/metrics@latest
+  with:
+    plugin_poopmap: yes
+  prod:
+    skip: true

source/plugins/posts/README.md

@@ -14,18 +14,51 @@ The recent *posts* plugin displays recent articles you wrote on an external sour
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_posts` | `boolean` **[no]** | Display recent posts |
+| `plugin_posts_source` | `string` **[]** *{"dev.to", "hashnode"}* | Posts external source |
+| `plugin_posts_descriptions` | `boolean` **[no]** | Display posts descriptions |
+| `plugin_posts_covers` | `boolean` **[no]** | Display posts cover images |
+| `plugin_posts_limit` | `number` **[4]** *{1 ≤ 𝑥 ≤ 30}* | Maximum number of posts to display |
+| `plugin_posts_user` | `string` **[.user.login]** | Posts external source username |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Recent posts
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_posts: yes
+  filename: metrics.plugin.posts.svg
-    plugin_posts_source: dev.to      # External source
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_people_user: .github.user # Use same username as GitHub login
+  base: ''
-    plugin_posts_limit: 4            # Limit to 4 posts
+  plugin_posts: 'yes'
-    plugin_posts_descriptions: yes   # Display article short description (when supported)
+  plugin_posts_source: dev.to
-    plugin_posts_covers: yes         # Display article thumbnail (when supported)
+
 ```
+```yaml
+name: Recent posts with descriptions and cover images
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.posts.full.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_posts: 'yes'
+  plugin_posts_source: dev.to
+  plugin_posts_descriptions: 'yes'
+  plugin_posts_covers: 'yes'
+
+```
+<!--/examples-->

source/plugins/posts/examples.yml

@@ -0,0 +1,19 @@
+- name: Recent posts
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.posts.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_posts: yes
+    plugin_posts_source: dev.to
+
+- name: Recent posts with descriptions and cover images
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.posts.full.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_posts: yes
+    plugin_posts_source: dev.to
+    plugin_posts_descriptions: yes
+    plugin_posts_covers: yes

source/plugins/projects/README.md

@@ -40,16 +40,37 @@ To do so, open your repository project and retrieve the last URL endpoint, in th
 
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_projects` | `boolean` **[no]** | Display active projects |
+| `plugin_projects_limit` | `number` **[4]** *{0 ≤ 𝑥 ≤ 100}* | Maximum number of projects to display |
+| `plugin_projects_repositories` | `array` *(comma-separated,/(?<user>[-a-z0-9]+)[/](?<repo>[-a-z0-9]+)[/]projects[/](?<id>[0-9]+)/)* **[]** | List of repository project identifiers to disaplay |
+| `plugin_projects_descriptions` | `boolean` **[no]** | Display projects descriptions |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Project from a repository
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_projects: yes
+  filename: metrics.plugin.projects.svg
-    plugin_projects_repositories: lowlighter/metrics/projects/1 # Display #1 project of lowlighter/metrics repository
+  token: ${{ secrets.METRICS_BOT_TOKEN }}
-    plugin_projects_limit: 4                                    # Limit to 4 entries
+  base: ''
-    plugin_projects_descriptions: yes                           # Display projects descriptions
+  plugin_projects: 'yes'
+  plugin_projects_repositories: lowlighter/metrics/projects/1
+  plugin_projects_descriptions: 'yes'
+
 ```
+<!--/examples-->

source/plugins/projects/examples.yml

@@ -0,0 +1,9 @@
+- name: Project from a repository
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.projects.svg
+    token: ${{ secrets.METRICS_BOT_TOKEN }}
+    base: ""
+    plugin_projects: yes
+    plugin_projects_repositories: lowlighter/metrics/projects/1
+    plugin_projects_descriptions: yes

source/plugins/reactions/README.md

@@ -9,21 +9,42 @@ The *reactions* plugin displays overall reactions on your recent issues and issu
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_reactions` | `boolean` **[no]** | Display average issue comments reactions |
+| `plugin_reactions_limit` | `number` **[200]** *{0 ≤ 𝑥 ≤ 1000}* | Maximum number of issue comments to parse |
+| `plugin_reactions_limit_issues` | `number` **[100]** *{0 ≤ 𝑥 ≤ 1000}* | Maximum number of issues and pull requests opened to parse |
+| `plugin_reactions_limit_discussions` | `number` **[100]** *{0 ≤ 𝑥 ≤ 1000}* | Maximum number of discussions opened to parse |
+| `plugin_reactions_limit_discussions_comments` | `number` **[100]** *{0 ≤ 𝑥 ≤ 1000}* | Maximum number of discussions comments opened to parse |
+| `plugin_reactions_days` | `number` **[0]** *{0 ≤ 𝑥}* | Maximum comments age |
+| `plugin_reactions_display` | `string` **[absolute]** *{"absolute", "relative"}* | Display mode |
+| `plugin_reactions_details` | `array` *(comma-separated)* **[]** *{"count", "percentage"}* | Additional details |
+| `plugin_reactions_ignored` | `array` *(comma-separated)* **[github-actions[bot], dependabot[bot], dependabot-preview[bot]]** | Users to ignore |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: 🎭 Comment reactions
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_reactions: yes
+  filename: metrics.plugin.reactions.svg
-    plugin_reactions_limit: 200                  # Compute reactions over last 200 issue comments
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_reactions_limit_issues: 100           # Compute reactions over last 100 issues/pull requests opened
+  base: ''
-    plugin_reactions_limit_discussions: 100      # Compute reactions over last 100 discussions
+  plugin_reactions: 'yes'
-plugin_reactions_limit_discussions_comments: 100 # Compute reactions over last 100 discussions comments
+  plugin_reactions_limit: 100
-    plugin_reactions_days: 14                    # Compute reactions on issue comments posted less than 14 days ago
+  plugin_reactions_details: percentage
-    plugin_reactions_display: absolute           # Display percentages based on the total amoun fetched
+
-    plugin_reactions_details: count, percentage  # Display reactions count and percentage
-    plugin_reactions_ignored: bot                # Ignore "bot" user
 ```
+<!--/examples-->

source/plugins/reactions/examples.yml

@@ -0,0 +1,10 @@
+- name: 🎭 Comment reactions
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.reactions.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_reactions: yes
+    plugin_reactions_limit: 100
+    plugin_reactions_details: percentage
+

source/plugins/repositories/README.md

@@ -13,14 +13,34 @@ It is mostly intended for external usage as [pinned repositories](https://www.go
 
 Because of limitations of using SVG inside of `<img>` tags, people won't be able to click on it.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_repositories` | `boolean` **[no]** | Display chosen featured repositories |
+| `plugin_repositories_featured` | `array` *(comma-separated)* **[]** | List of repositories to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Featured repositories
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_repositories: yes
+  filename: metrics.plugin.repositories.svg
-    plugin_repositories_featured: lowlighter/metrics, denoland/deno  # List of repositories you want to feature
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_repositories: 'yes'
+  plugin_repositories_featured: lowlighter/metrics
+
 ```
+<!--/examples-->

source/plugins/repositories/examples.yml

@@ -0,0 +1,8 @@
+- name: Featured repositories
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.repositories.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_repositories: yes
+    plugin_repositories_featured: lowlighter/metrics

source/plugins/rss/README.md

@@ -9,15 +9,25 @@ The *rss* plugin displays items from a specified RSS feed.
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_rss` | `boolean` **[no]** | Display RSS feed |
+| `plugin_rss_source` | `string` **[]** | RSS feed source |
+| `plugin_rss_limit` | `number` **[4]** *{0 ≤ 𝑥 ≤ 30}* | Maximum number of items to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
 
-```yaml
+<!--/examples-->
-- uses: lowlighter/metrics@latest
-  with:
-    # ... other options
-    plugin_rss: yes
-    plugin_rss_source: https://news.ycombinator.com/rss  # RSS feed
-    plugin_rss_limit: 6                                  # Limit to 6 items
-```

source/plugins/rss/tests.yml

@@ -1,6 +1,9 @@
-- name: Rss plugin (default)
+- name: Feed from hacker news
   uses: lowlighter/metrics@latest
   with:
+    filename: metrics.plugin.rss.svg
     token: NOT_NEEDED
+    base: ""
     plugin_rss: yes
-    plugin_rss_source: https://example.org/rss
+    plugin_rss_source: https://news.ycombinator.com/rss
+    plugin_rss_limit: 4

source/plugins/screenshot/README.md

@@ -10,17 +10,39 @@ It can be restricted with a [CSS selector](https://developer.mozilla.org/en-US/d
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_screenshot` | `boolean` **[no]** | Display a screenshot of any website |
+| `plugin_screenshot_title` | `string` **[Screenshot]** | Screenshot title caption |
+| `plugin_screenshot_url` | `string` **[]** | Website to take screenshot |
+| `plugin_screenshot_selector` | `string` **[body]** | Selector to take in screenshot |
+| `plugin_screenshot_background` | `boolean` **[yes]** | Display or remove default page background |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: XKCD of the day
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_screenshot: yes
+  filename: metrics.plugin.screenshot.svg
-    plugin_screenshot_title: XKCD of the day  # Section title
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_screenshot_url: https://xkcd.com   # Website url
+  base: ''
-    plugin_screenshot_selector: "#comic img"  # CSS selector to take into screenshot
+  plugin_screenshot: 'yes'
-    plugin_screenshot_background: no          # Remove page background
+  plugin_screenshot_title: XKCD of the day
-```
+  plugin_screenshot_url: https://xkcd.com
+  plugin_screenshot_selector: '#comic img'
+
+```
+<!--/examples-->

source/plugins/screenshot/examples.yml

@@ -0,0 +1,10 @@
+- name: XKCD of the day
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.screenshot.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_screenshot: yes
+    plugin_screenshot_title: XKCD of the day
+    plugin_screenshot_url: https://xkcd.com
+    plugin_screenshot_selector: "#comic img"

source/plugins/skyline/README.md

@@ -13,17 +13,38 @@ The *skyline* plugin lets you display your 3D commits calendar from [skyline.git
 
 This uses puppeteer to generate collect image frames, and use CSS animations to create an animated rendering (GIF images are not animated in GitHub flavored markdown rendering which is why this design choice was made).
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_skyline` | `boolean` **[no]** | Display GitHub Skyline 3D calendar |
+| `plugin_skyline_year` | `number` **[current-year]** *{2008 ≤ 𝑥}* | Displayed year |
+| `plugin_skyline_frames` | `number` **[60]** *{1 ≤ 𝑥 ≤ 120}* | Number of frames |
+| `plugin_skyline_quality` | `number` **[0.5]** *{0.1 ≤ 𝑥 ≤ 1}* | Image quality |
+| `plugin_skyline_compatibility` | `boolean` **[no]** | Compatibility mode |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: GitHub Skyline
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_skyline: yes
+  filename: metrics.plugin.skyline.svg
-    plugin_skyline_year: 0            # Set to 0 to display current year
+  token: NOT_NEEDED
-    plugin_skyline_frames: 60         # Use 60 frames (half-loop)
+  plugin_skyline: 'yes'
-    plugin_skyline_quality: 0.5       # Set image quality
+  plugin_skyline_year: 2020
-    plugin_skyline_compatibility: yes # Support additional browsers (⚠️ increases file size and reduce optimization)
+  plugin_skyline_frames: 6
-```
+  plugin_skyline_quality: 1
+
+```
+<!--/examples-->

source/plugins/skyline/examples.yml

@@ -0,0 +1,9 @@
+- name: GitHub Skyline
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.skyline.svg
+    token: NOT_NEEDED
+    plugin_skyline: yes
+    plugin_skyline_year: 2020
+    plugin_skyline_frames: 6
+    plugin_skyline_quality: 1

source/plugins/sponsors/README.md

@@ -14,14 +14,44 @@ The *sponsors* plugin lets you display your sponsors and introduction text from
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_sponsors` | `boolean` **[no]** | Display GitHub sponsors |
+| `plugin_sponsors_sections` | `array` *(comma-separated)* **[goal, about]** *{"goal", "about"}* | Sections to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Sponsors goal
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_sponsors: yes
+  filename: metrics.plugin.sponsors.svg
-    plugin_sponsors_sections: goal, about # Display goal and about sections
+  token: ${{ secrets.METRICS_TOKEN }}
-```
+  base: ''
+  plugin_sponsors: 'yes'
+  plugin_sponsors_sections: goal
+
+```
+```yaml
+name: Sponsors introduction
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.sponsors.full.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_sponsors: 'yes'
+
+```
+<!--/examples-->

source/plugins/sponsors/examples.yml

@@ -0,0 +1,16 @@
+- name: Sponsors goal
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.sponsors.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_sponsors: yes
+    plugin_sponsors_sections: goal
+
+- name: Sponsors introduction
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.sponsors.full.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_sponsors: yes

source/plugins/stackoverflow/README.md

@@ -20,18 +20,40 @@ Your user id will be in both url and search bar.
 
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_stackoverflow` | `boolean` **[no]** | Stackoverflow metrics |
+| `plugin_stackoverflow_user` | `number` **[0]** | Stackoverflow user id |
+| `plugin_stackoverflow_sections` | `array` *(comma-separated)* **[answers-top, questions-recent]** *{"answers-top", "answers-recent", "questions-top", "questions-recent"}* | Sections to display |
+| `plugin_stackoverflow_limit` | `number` **[2]** *{1 ≤ 𝑥 ≤ 30}* | Maximum number of entries to display per section |
+| `plugin_stackoverflow_lines` | `number` **[4]** *{0 ≤ 𝑥}* | Maximum number of lines to display per question or answer |
+| `plugin_stackoverflow_lines_snippet` | `number` **[2]** *{0 ≤ 𝑥}* | Maximum number of lines to display per code snippet |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Top answers from stackoverflow
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_stackoverflow: yes
+  filename: metrics.plugin.stackoverflow.svg
-    plugin_stackoverflow_user: 8332505                           # Stackoverflow user id (required)
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_stackoverflow_sections: answers-top, questions-recent # Display top answers and recent questions
+  base: ''
-    plugin_stackoverflow_limit: 2                                # Display 2 entries per section
+  plugin_stackoverflow: 'yes'
-    plugin_stackoverflow_lines: 4                                # Display 4 lines per entry
+  plugin_stackoverflow_user: 1
-    plugin_stackoverflow_lines_snippet: 2                        # Display 2 lines in embed code snippets
+  plugin_stackoverflow_sections: answers-top
-```
+  plugin_stackoverflow_limit: 2
+
+```
+<!--/examples-->

source/plugins/stackoverflow/examples.yml

@@ -0,0 +1,10 @@
+- name: Top answers from stackoverflow
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.stackoverflow.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_stackoverflow: yes
+    plugin_stackoverflow_user: 1
+    plugin_stackoverflow_sections: answers-top
+    plugin_stackoverflow_limit: 2

source/plugins/stargazers/README.md

@@ -9,13 +9,32 @@ The *stargazers* plugin displays your stargazers evolution across all of your re
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_stargazers` | `boolean` **[no]** | Display stargazers metrics |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Last weeks stargazers
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_stargazers: yes
+  filename: metrics.plugin.stargazers.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_stargazers: 'yes'
+
 ```
+<!--/examples-->

source/plugins/stargazers/examples.yml

@@ -0,0 +1,7 @@
+- name: Last weeks stargazers
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.stargazers.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_stargazers: yes

source/plugins/starlists/README.md

@@ -9,17 +9,39 @@ The *starlists* plugin displays your recently star lists.
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_starlists` ✨ | `boolean` **[no]** | Display star lists |
+| `plugin_starlists_limit` ✨ | `number` **[2]** *{1 ≤ 𝑥 ≤ 100}* | Number of star lists to display |
+| `plugin_starlists_limit_repositories` ✨ | `number` **[2]** *{0 ≤ 𝑥 ≤ 100}* | Number of repositories to display per star lists |
+| `plugin_starlists_shuffle_repositories` ✨ | `boolean` **[yes]** | Shuffle displayed repositories |
+| `plugin_starlists_ignored` ✨ | `array` *(comma-separated)* **[]** | Star lists to skip |
+| `plugin_starlists_only` ✨ | `array` *(comma-separated)* **[]** | Star lists to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Featured star list
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_starlists: yes
+  filename: metrics.plugin.starlists.svg
-    plugin_starlists_limit: 16             # Limit to 16 entries
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_starlists_limit_repositories: 2 # Limit to 2 repositories per entries
+  base: ''
-    plugin_starlists_ignored: list1, list2 # Ignored lists
+  plugin_starlists: 'yes'
-    plugin_starlists_only: list3           # Only display this list
+  plugin_starlists_limit_repositories: 2
-```
+  plugin_starlists_only: 🤘 TC39
+
+```
+<!--/examples-->

source/plugins/starlists/examples.yml

@@ -0,0 +1,9 @@
+- name: Featured star list
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.starlists.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_starlists: yes
+    plugin_starlists_limit_repositories: 2
+    plugin_starlists_only: 🤘 TC39

source/plugins/stars/README.md

@@ -9,14 +9,34 @@ The *stars* plugin displays your recently starred repositories.
   </td>
 </table>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_stars` | `boolean` **[no]** | Display recently starred repositories |
+| `plugin_stars_limit` | `number` **[4]** *{1 ≤ 𝑥 ≤ 100}* | Maximum number of stars to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Recently starred
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_stars: yes
+  filename: metrics.plugin.stars.svg
-    plugin_stars_limit: 4 # Limit to 4 entries
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_stars: 'yes'
+  plugin_stars_limit: 3
+
 ```
+<!--/examples-->

source/plugins/stars/examples.yml

@@ -0,0 +1,8 @@
+- name: Recently starred
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.stars.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_stars: yes
+    plugin_stars_limit: 3

source/plugins/stock/README.md

@@ -18,17 +18,37 @@ Create a [RapidAPI account](https://rapidapi.com) and subscribe to [Yahoo Financ
 
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_stock` | `boolean` **[no]** | Display stock prices of a given company |
+| `plugin_stock_token` 🔐 | `token` **[]** | Yahoo Finance token |
+| `plugin_stock_symbol` | `string` **[]** | Company stock symbol |
+| `plugin_stock_duration` | `string` **[1d]** *{"1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"}* | Time range to display |
+| `plugin_stock_interval` | `string` **[5m]** *{"1m", "2m", "5m", "15m", "60m", "1d"}* | Time intervals between records |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Stock prices from Tesla
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_stock: yes
+  filename: metrics.plugin.stock.svg
-    plugin_stock_token: ${{ secrets.STOCK_TOKEN }} # RapidAPI Yahoo Finance token
+  token: NOT_NEEDED
-    plugin_stock_symbol: TSLA                      # Display Tesla stock price
+  base: ''
-    plugin_stock_duration: 1d                      # Display last day of market
+  plugin_stock: 'yes'
-    plugin_stock_interval: 5m                      # Use precision of 5 minutes for each record
+  plugin_stock_symbol: TSLA
-```
+
+```
+<!--/examples-->

source/plugins/stock/examples.yml

@@ -0,0 +1,8 @@
+- name: Stock prices from Tesla
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.stock.svg
+    token: NOT_NEEDED
+    base: ""
+    plugin_stock: yes
+    plugin_stock_symbol: TSLA

source/plugins/support/README.md

@@ -11,13 +11,31 @@ The *support* plugin lets you display your statistics from [GitHub Support Commu
 
 An account on [GitHub Support Community](https://github.community/) is required to use this plugin.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_support` | `boolean` **[no]** | GitHub Community Support metrics |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: GitHub Community Support
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_support: yes
+  filename: metrics.plugin.support.svg
-```
+  token: NOT_NEEDED
+  plugin_support: 'yes'
+
+```
+<!--/examples-->

source/plugins/support/examples.yml

@@ -0,0 +1,6 @@
+- name: GitHub Community Support
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.support.svg
+    token: NOT_NEEDED
+    plugin_support: yes

source/plugins/topics/README.md

@@ -17,16 +17,48 @@ Check out [GitHub topics](https://github.com/topics) to search interesting topic
 
 This uses puppeteer to navigate through your starred topics page.
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_topics` | `boolean` **[no]** | Display starred topics |
+| `plugin_topics_mode` | `string` **[starred]** *{"starred", "icons", "mastered"}* | Plugin mode |
+| `plugin_topics_sort` | `string` **[stars]** *{"stars", "activity", "starred", "random"}* | Sorting method of starred topics |
+| `plugin_topics_limit` | `number` **[15]** *{0 ≤ 𝑥 ≤ 20}* | Maximum number of topics to display |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Labels
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_topics: yes
+  filename: metrics.plugin.topics.svg
-    plugin_topics_sort: stars    # Sort by most starred topics
+  token: ${{ secrets.METRICS_TOKEN }}
-    plugin_topics_mode: icons    # Display icons instead of labels
+  base: ''
-    plugin_topics_limit: 0       # Disable limitations
+  plugin_topics: 'yes'
+  plugin_topics_limit: 12
+
 ```
+```yaml
+name: Icons
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.topics.icons.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: ''
+  plugin_topics: 'yes'
+  plugin_topics_limit: 0
+  plugin_topics_mode: icons
+
+```
+<!--/examples-->

source/plugins/topics/examples.yml

@@ -0,0 +1,18 @@
+- name: Labels
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.topics.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_topics: yes
+    plugin_topics_limit: 12
+
+- name: Icons
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.topics.icons.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: ""
+    plugin_topics: yes
+    plugin_topics_limit: 0
+    plugin_topics_mode: icons

source/plugins/traffic/README.md

@@ -14,13 +14,33 @@ Because of GitHub REST API limitation, provided token requires full `repo` scope
 
 ![Token with repo scope](/.github/readme/imgs/setup_token_repo_scope.png)
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_traffic` | `boolean` **[no]** | Display repositories traffic metrics |
+| `plugin_traffic_skipped` | `array` *(comma-separated)* **[]** | Repositories to skip |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Repositories traffic
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_traffic: yes
+  filename: metrics.plugin.traffic.svg
+  token: ${{ secrets.METRICS_TOKEN }}
+  base: repositories
+  plugin_traffic: 'yes'
+
 ```
+<!--/examples-->

source/plugins/traffic/examples.yml

@@ -0,0 +1,9 @@
+- name: Repositories traffic
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.traffic.svg
+    token: ${{ secrets.METRICS_TOKEN }}
+    base: repositories
+    plugin_traffic: yes
+  prod:
+    token: ${{ secrets.METRICS_BOT_TOKEN }}

source/plugins/tweets/README.md

@@ -26,17 +26,49 @@ Create an app from your [developer dashboard](https://developer.twitter.com/en/p
 
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_tweets` | `boolean` **[no]** | Display recent tweets |
+| `plugin_tweets_token` 🔐 | `token` **[]** | Twitter API token |
+| `plugin_tweets_attachments` | `boolean` **[no]** | Display tweets attchments |
+| `plugin_tweets_limit` | `number` **[2]** *{1 ≤ 𝑥 ≤ 10}* | Maximum number of tweets to display |
+| `plugin_tweets_user` | `string` **[.user.twitter]** | Twitter username |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: Latest tweets
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_tweets: yes
+  filename: metrics.plugin.tweets.svg
-    plugin_tweets_token: ${{ secrets.TWITTER_TOKEN }} # Required
+  token: NOT_NEEDED
-    plugin_tweets_attachments: yes                    # Display tweets attachments (images, preview urls, etc.)
+  plugin_tweets: 'yes'
-    plugin_tweets_limit: 2                            # Limit to 2 tweets
+  plugin_tweets_token: ${{ secrets.TWITTER_TOKEN }}
-    plugin_tweets_user: .user.twitter                 # Defaults to your GitHub linked twitter username
+  plugin_tweets_user: github
+
 ```
+```yaml
+name: Latest tweets including attachments
+uses: lowlighter/metrics@latest
+with:
+  filename: metrics.plugin.tweets.attachments.svg
+  token: NOT_NEEDED
+  plugin_tweets: 'yes'
+  plugin_tweets_token: ${{ secrets.TWITTER_TOKEN }}
+  plugin_tweets_attachments: 'yes'
+  plugin_tweets_user: github
+
+```
+<!--/examples-->

source/plugins/tweets/examples.yml

@@ -0,0 +1,23 @@
+- name: Latest tweets
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.tweets.svg
+    token: NOT_NEEDED
+    plugin_tweets: yes
+    plugin_tweets_token: ${{ secrets.TWITTER_TOKEN }}
+    plugin_tweets_user: github
+  prod:
+    user: botlighter
+
+- name: Latest tweets including attachments
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.tweets.attachments.svg
+    token: NOT_NEEDED
+    plugin_tweets: yes
+    plugin_tweets_token: ${{ secrets.TWITTER_TOKEN }}
+    plugin_tweets_attachments: yes
+    plugin_tweets_user: github
+  prod:
+    user: botlighter
+

source/plugins/wakatime/README.md

@@ -20,19 +20,39 @@ Then setup [WakaTime plugins](https://wakatime.com/plugins) to be ready to go!
 
 </details>
 
+#### ➡️ Available options
+
+<!--options-->
+| Option | Type *(format)* **[default]** *{allowed values}* | Description |
+| ------ | -------------------------------- | ----------- |
+| `plugin_wakatime` | `boolean` **[no]** | Display WakaTime stats |
+| `plugin_wakatime_token` 🔐 | `token` **[]** | WakaTime API token |
+| `plugin_wakatime_days` | `string` **[7]** *{"7", "30", "180", "365"}* | WakaTime time range |
+| `plugin_wakatime_sections` | `array` **[time, projects, projects-graphs, languages, languages-graphs, editors, os]** *{"time", "projects", "projects-graphs", "languages", "languages-graphs", "editors", "editors-graphs", "os", "os-graphs"}* | Sections to display |
+| `plugin_wakatime_limit` | `number` **[5]** *{0 ≤ 𝑥}* | Maximum number of entries to display per graph |
+| `plugin_wakatime_url` | `string` **[https://wakatime.com]** | Address where to reach your Wakatime instance |
+| `plugin_wakatime_user` | `string` **[current]** | Your Wakatime user on the selfhosted Wakapi instance |
+
+
+Legend for option icons:
+* 🔐 Value should be stored in repository secrets
+* ✨ New feature currently in testing on `master`/`main`
+<!--/options-->
+
+*[→ Full specification](metadata.yml)*
+
 #### ℹ️ Examples workflows
 
-[➡️ Available options for this plugin](metadata.yml)
+<!--examples-->
-
 ```yaml
-- uses: lowlighter/metrics@latest
+name: ⏰ WakaTime
-  with:
+uses: lowlighter/metrics@latest
-    # ... other options
+with:
-    plugin_wakatime: yes
+  filename: metrics.plugin.wakatime.svg
-    plugin_wakatime_token: ${{ secrets.WAKATIME_TOKEN }}      # Required
+  token: NOT_NEEDED
-    plugin_wakatime_days: 7                                   # Display last week stats
+  plugin_wakatime: 'yes'
-    plugin_wakatime_sections: time, projects, projects-graphs # Display time and projects sections, along with projects graphs
+  plugin_wakatime_sections: time, projects, projects-graphs, languages, languages-graphs, editors, os
-    plugin_wakatime_limit: 4                                  # Show 4 entries per graph
+  plugin_wakatime_token: ${{ secrets.WAKATIME_TOKEN }}
-    plugin_wakatime_url: https://wakatime.com                 # Wakatime url endpoint
+
-    plugin_wakatime_user: .user.login                         # User
 ```
+<!--/examples-->

source/plugins/wakatime/examples.yml

@@ -0,0 +1,12 @@
+- name: ⏰ WakaTime
+  uses: lowlighter/metrics@latest
+  with:
+    filename: metrics.plugin.wakatime.svg
+    token: NOT_NEEDED
+    plugin_wakatime: yes
+    plugin_wakatime_sections: time, projects, projects-graphs, languages, languages-graphs, editors, os
+    plugin_wakatime_token: ${{ secrets.WAKATIME_TOKEN }}
+  prod:
+    # ⚠️ Using mocked data because I don't really use WakaTime, disable this
+    plugin_wakatime_token: MOCKED_TOKEN
+    use_mocked_data: yes