docs: remove cost, document missing options and improve docs (lowli…

…ghter#653)

.github/quickstart/plugin/metadata.yml

@@ -1,5 +1,4 @@
 name: "🧩 <%= `${name.charAt(0).toLocaleUpperCase()}${name.substring(1)}` %>"
-cost: Estimates how many GitHub requests is used during plugin execution ("N/A" for Third-Party services)
 category: other   # Set plugin category ("github", "social" or "other")
 supports:
   - user          # Support users account

.github/readme/partials/documentation/compatibility.md

@@ -10,7 +10,7 @@
   <tr>
     <td nowrap="nowrap"><%- name %></td><%# -%>
     <% for (const [plugin] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key)))) { %>
-    <td nowrap="nowrap" align="center" data-plugin="<%= plugin %>"><%= readme.compatibility[plugin] ? "✔️" : "❌" %></td><% } %>
+    <td nowrap="nowrap" align="center" data-plugin="<%= plugin %>"><%= {true:"✔️", false:"❌", embed:"✓"}[readme.compatibility[plugin]] %></td><% } %>
   </tr><% } %>
   <tr>
     <td colspan="<%= Object.keys(plugins).length %>"></td>

CONTRIBUTING.md

@@ -423,8 +423,7 @@ For example:
 Here's an example:
 ```yaml
 name: "🧩 Plugin name (with emoji icon)"
-cost: Estimates how many GitHub requests is used during plugin execution ("N/A" for Third-Party services)
-category: github # Plugin category ("github", "social" or "other")
+category: github  # Plugin category ("github", "social" or "other")
 index: ~          # Leave as it (this is used to order plugins on metrics README.md)
 supports:
   - user          # Support users account

source/app/metrics/metadata.mjs

@@ -297,7 +297,10 @@ metadata.template = async function({__templates, name, plugins, logger}) {
       supports:meta.supports ?? null,
       readme:{
         demo:readme.match(/(?<demo><table>[\s\S]*?<[/]table>)/)?.groups?.demo?.replace(/<[/]?(?:table|tr)>/g, "")?.trim() ?? (name === "community" ? '<td align="center" colspan="2">See <a href="/source/templates/community/README.md">documentation</a> 🌍</td>' : "<td></td>"),
-        compatibility:{...compatibility, base:true},
+        compatibility:{
+          ...Object.fromEntries(Object.entries(compatibility).filter(([_, value]) => value)),
+          ...Object.fromEntries(Object.entries(compatibility).filter(([_, value]) => !value).map(([key, _]) => [key, "embed"])),
+        },
       },
       check({q, account = "bypass", format = null}) {
         //Support check

source/plugins/achievements/README.md

@@ -36,9 +36,10 @@ It also lets you quickly see at a glance what this user primarly use GitHub for,
   with:
     # ... other options
     plugin_achievements: yes
-    plugin_achievements_threshold: B       # Display achievements with rank B or higher
-    plugin_achievements_secrets: yes       # Display unlocked secrets achievements
-    plugin_achievements_ignored: octonaut  # Hide octonaut achievement
-    plugin_achievements_limit: 0           # Display all unlocked achievement matching threshold and secrets params
-    plugin_achievements_display: compact   # Use compact display
+    plugin_achievements_threshold: B      # Display achievements with rank B or higher
+    plugin_achievements_secrets: yes      # Display unlocked secrets achievements
+    plugin_achievements_display: compact  # Use compact display
+    plugin_achievements_limit: 0          # Display all unlocked achievements (no limit)
+    plugin_achievements_ignored: octonaut # Hide "octonaut" achievement
+    plugin_achievements_only: explorer    # Display only "explorer" achievement (don't use with "ignored" option)
 ```

source/plugins/achievements/metadata.yml

@@ -1,5 +1,4 @@
 name: "🏆 Achievements"
-cost: ~5 GraphQL request
 category: github
 index: 17
 supports:

source/plugins/activity/README.md

@@ -38,7 +38,11 @@ Use a full `repo` scope token to display **private** events.
   with:
     # ... other options
     plugin_activity: yes
-    plugin_activity_limit: 5    # Limit to 5 events
-    plugin_activity_days: 14    # Keep only events from last 14 days (can be set to 0 to disable limitations)
-    plugin_activity_filter: all # Show all events (use table above to filter events types)
+    plugin_activity_limit: 5           # Limit to 5 events
+    plugin_activity_load: 100          # Load up to 100 recent events from API (should be higher than "limit")
+    plugin_activity_days: 14           # Keep only events from last 14 days (set to 0 for no limit)
+    plugin_activity_filter: all        # Show all events (use table above to filter events types)
+    plugin_activity_visibility: public # Only display public events
+    plugin_activity_timestamps: yes    # Display events timestamps
+    plugin_activity_skipped: repo      # Ignored repositories
 ```

source/plugins/activity/metadata.yml

@@ -1,5 +1,4 @@
 name: "📰 Recent activity"
-cost: 1 REST request per 100 events
 category: github
 index: 16
 supports:
@@ -86,4 +85,4 @@ inputs:
     type: array
     format: comma-separated
     default: ""
-    example: my-repo-1, my-repo-2, owner/repo-3 ...
+    example: my-repo-1, my-repo-2, owner/repo-3, ...

source/plugins/anilist/README.md

@@ -32,10 +32,10 @@ These sections can also be filtered by media type, which can be either `anime`,
   with:
     # ... other options
     plugin_anilist: yes
-    plugin_anilist_medias: anime, manga             # Display both animes and mangas
-    plugin_anilist_sections: favorites, characters  # Display only favorites and characters sections
-    plugin_anilist_limit: 2                         # Limit to 2 entry per section (characters section excluded)
-    plugin_anilist_shuffle: yes                     # Shuffle data for more varied outputs
-    plugin_anilist_user: .user.login                # Use same username as GitHub login
-    plugin_anilist_limit_characters: 22             # Limit to 22 characters in characters section
+    plugin_anilist_medias: anime, manga            # Display both animes and mangas
+    plugin_anilist_sections: favorites, characters # Display only favorites and characters sections
+    plugin_anilist_limit: 2                        # Limit to 2 entry per section (characters section excluded)
+    plugin_anilist_limit_characters: 22            # Limit to 22 characters in characters section
+    plugin_anilist_shuffle: yes                    # Shuffle data for more varied outputs
+    plugin_anilist_user: .user.login               # Use same username as GitHub login
 ```

source/plugins/anilist/metadata.yml

@@ -1,5 +1,4 @@
 name: "🌸 Anilist watch list and reading list"
-cost: N/A
 category: social
 index: 4
 supports:

source/plugins/base/README.md

@@ -34,7 +34,9 @@ These are all enabled by default, but you can explicitely opt out from them.
     # ... 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: [email protected]          # Handle you use when authoring commits, which can be used to filter commits in other plugins
 ```

source/plugins/base/metadata.yml

@@ -1,5 +1,4 @@
 name: "🗃️ Base content"
-cost: 2 GraphQL requests + 1 GraphQL request per 100 repositories fetched
 category: core
 supports:
   - user
@@ -64,7 +63,7 @@ inputs:
     type: array
     format: comma-separated
     default: ""
-    example: my-repo-1, my-repo-2, owner/repo-3 ...
+    example: my-repo-1, my-repo-2, owner/repo-3, ...
 
   # List of surnames or email addresses you use when authoring commits
   # These are mostly used to perform commits analysis to detect ownership

source/plugins/code/README.md

@@ -24,4 +24,5 @@ Display a random code snippet from your recent activity history.
     plugin_code_load: 100               # Fetch 100 events from activity
     plugin_code_visibility: public      # Only display snippets from public activity
     plugin_code_skipped: github/octocat # Skip github/octocat repository
+    plugin_code_languages: javascript   # Limit code snippets to JavaScript code
 ```

source/plugins/code/metadata.yml

@@ -1,5 +1,4 @@
 name: "♐ Code snippet of the day"
-cost: 1 REST request per 100 events fetched
 category: github
 index: 22
 supports:
@@ -44,7 +43,7 @@ inputs:
     type: array
     format: comma-separated
     default: ""
-    example: my-repo-1, my-repo-2, owner/repo-3 ...
+    example: my-repo-1, my-repo-2, owner/repo-3, ...
 
   # Restrict code snippet languages
   # These are guessed through linguist
@@ -53,4 +52,4 @@ inputs:
     type: array
     format: comma-separated
     default: ""
-    example: javascript, typescript, ....
+    example: javascript, typescript, ...

source/plugins/contributors/README.md

@@ -49,4 +49,10 @@ Matching is performed in keys order.
     plugin_contributors_ignored: bot           # Ignore "bot" user
     plugin_contributors_contributions: yes     # Display number of contributions for each contributor
     plugin_contributors_sections: contributors # Display contributors sections
+    plugin_contributors_categories: |          # A JSON mapping of labels by files edited
+      {
+        "📚 Documentation": ["README.md", "docs/**"],
+        "💻 Code": ["source/**", "src/**"],
+        "#️⃣ Others": ["*"]
+      }
 ```

source/plugins/contributors/metadata.yml

@@ -1,5 +1,4 @@
 name: "🏅 Repository contributors"
-cost: N/A
 category: github
 index: 5
 supports:

source/plugins/core/metadata.yml

@@ -1,5 +1,4 @@
 name: "🧱 Core"
-cost: N/A
 category: core
 supports:
   - user

source/plugins/discussions/metadata.yml

@@ -1,5 +1,4 @@
 name: "💬 Discussions"
-cost: 1 GraphQL request + 1 GraphQL request per 100 discussions started
 category: github
 index: 18
 supports:

source/plugins/followup/metadata.yml

@@ -1,5 +1,4 @@
 name: "🎟️ Follow-up of issues and pull requests"
-cost: 0 API request (1 GraphQL request if "user" section is enabled)
 category: github
 index: 11
 supports:

source/plugins/gists/metadata.yml

@@ -1,5 +1,4 @@
 name: "🎫 Gists"
-cost: 1 GraphQL request per 100 gists
 category: github
 index: 10
 supports:

source/plugins/habits/metadata.yml

@@ -1,5 +1,4 @@
 name: "💡 Coding habits"
-cost: 1 REST request per 100 events + 1 REST request per commit
 category: github
 index: 3
 supports:

source/plugins/introduction/metadata.yml

@@ -1,5 +1,4 @@
 name: "🙋 Introduction"
-cost: 1 GraphQL request
 category: github
 index: 2
 supports:

source/plugins/isocalendar/metadata.yml

@@ -1,5 +1,4 @@
 name: "📅 Isometric commit calendar"
-cost: 1-2 GraphQL requests + 1 GraphQL request per year
 category: github
 index: 0
 supports:

source/plugins/languages/README.md

@@ -52,16 +52,18 @@ For better results, it's advised to add either your surnames and eventually no-r
     plugin_languages: yes
     plugin_languages_ignored: html, css                           # List of languages to ignore
     plugin_languages_skipped: my-test-repo                        # List of repositories to skip
+    plugin_languages_limit: 8                                     # Display up to 8 languages
+    plugin_languages_sections: most-used, recently-used           # Display most used and recently used
     plugin_languages_colors: "0:orange, javascript:#ff0000, ..."  # Make most used languages orange and JavaScript red
     plugin_languages_aliases: "JavaScript:JS, TypeScript:TS, ..." # Customize languages names with aliases
     plugin_languages_details: bytes-size, percentage              # Additionally display total bytes size and percentage
     plugin_languages_threshold: 2%                                # Hides all languages less than 2%
-    plugin_languages_limit: 8                                     # Display up to 8 languages
-    plugin_languages_sections: most-used, recently-used           # Display most used and recently used languages stats
+    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: lowlighter@users.noreply.github.com        # Surnames or email addresses used to identify your commits
+    commits_authoring: octocat@users.noreply.github.com           # Surnames or email addresses used to identify your commits
 ```

source/plugins/languages/metadata.yml

@@ -1,5 +1,4 @@
 name: "🈷️ Most used languages"
-cost: 0 API request (1 per 100 events fetched when using recently-used section)
 category: github
 index: 1
 supports:
@@ -28,7 +27,7 @@ inputs:
     type: array
     format: comma-separated
     default: ""
-    example: my-repo-1, my-repo-2, owner/repo-3 ...
+    example: my-repo-1, my-repo-2, owner/repo-3, ...
 
   # Number of languages to display
   # Set to 0 to disable limitations

source/plugins/licenses/metadata.yml

@@ -1,5 +1,4 @@
 name: "📜 Repository licenses"
-cost: N/A
 category: github
 index: 4
 supports:

source/plugins/lines/README.md

@@ -18,4 +18,5 @@ The *lines* of code plugin displays the number of lines of code you have added a
   with:
     # ... other options
     plugin_lines: yes
+    plugin_lines_skipped: repo # List of skipped repositories
 ```

source/plugins/lines/metadata.yml

@@ -1,5 +1,4 @@
 name: "👨‍💻 Lines of code changed"
-cost: 1 REST request per repository
 category: github
 index: 12
 supports:
@@ -20,4 +19,4 @@ inputs:
     type: array
     format: comma-separated
     default: ""
-    example: my-repo-1, my-repo-2, owner/repo-3 ...
+    example: my-repo-1, my-repo-2, owner/repo-3, ...

source/plugins/music/README.md

@@ -78,14 +78,14 @@ This mode is not supported for now.
     plugin_music: yes
     plugin_music_limit: 4                   # Limit to 4 entries
     plugin_music_playlist: https://******** # Use extracted playlist link
-                                            #   (plugin_music_provider and plugin_music_mode will be set automatically)
+    # plugin_music_provider: (will be guessed through plugin_music_playlist)
+    # plugin_music_mode: (will be set to "playlist" when plugin_music_playlist is provided)
 ```
 
 ### Recently played & top modes
 
-Recently played: Display tracks you have played recently.
-
-Top: Display your top artists/tracks for a certain time period.
+- **Recently played**: Display tracks you have played recently.
+- **Top**: Display your top artists/tracks for a certain time period.
 
 Select a music provider below for additional instructions.
 
@@ -198,7 +198,6 @@ Register your API key to finish setup.
     plugin_music_limit: 4          # Limit to 4 entries
     plugin_music_user: .user.login # Use same username as GitHub login
     plugin_music_token: ${{ secrets.LASTFM_API_KEY }}
-
 ```
 
 ##### Top
@@ -210,8 +209,8 @@ Register your API key to finish setup.
     plugin_music: yes
     plugin_music_provider: spotify # Use Spotify as provider
     plugin_music_mode: top         # Set plugin mode
-    plugin_music_top_type: tracks  # Set type for "top" mode; either tracks or artists
     plugin_music_limit: 4          # Limit to 4 entries, maximum is 50 for "top" mode with spotify
+    plugin_music_top_type: tracks  # Set type for "top" mode; either tracks or artists
     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_CLIENT_ID }}, ${{ secrets.SPOTIFY_CLIENT_SECRET }}, ${{ secrets.SPOTIFY_REFRESH_TOKEN }}"
 ```
@@ -223,10 +222,9 @@ Register your API key to finish setup.
     plugin_music: yes
     plugin_music_provider: lastfm  # Use Last.fm as provider
     plugin_music_mode: top         # Set plugin mode
-    plugin_music_top_type: artists # Set type for "top" mode; either tracks or artists
     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 }}
-
 ```

source/plugins/music/metadata.yml

@@ -1,5 +1,4 @@
 name: "🎼 Music plugin"
-cost: N/A
 category: social
 index: 2
 supports:

source/plugins/nightscout/metadata.yml

@@ -1,5 +1,4 @@
 name: "💉 Nightscout"
-cost: N/A
 category: other
 index: 3
 supports:

source/plugins/notable/README.md

@@ -5,13 +5,23 @@ The *notable* plugin displays badges of organization where you commited at least
 <table>
   <td align="center">
     <img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.notable.svg">
-    <details open><summary>With repository name</summary>
+    <details><summary>With repository name</summary>
       <img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.notable.repositories.svg">
     </details>
+    <details open><summary>Indepth analysis</summary>
+      <img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.notable.indepth.svg">
+    </details>
     <img width="900" height="1" alt="">
   </td>
 </table>
 
+#### Using `indepth` statistics
+
+The `plugin_notable_indepth` option lets you get additional metrics about your contribution, such as:
+- Total number of commits within a repository or organization. The badge will have a circular gauge which is proportional to the percentage of total contribution. It will also determine the resulting color of the badge.
+
+> 🔣 On web instances, `indepth` is an extra feature and must be enabled globally in `settings.json`
+
 #### ℹ️ Examples workflows
 
 [➡️ Available options for this plugin](metadata.yml)
@@ -21,7 +31,8 @@ The *notable* plugin displays badges of organization where you commited at least
   with:
     # ... other options
     plugin_notable: yes
-    plugin_notable_filter: stars:>500    # Only display repositories with 500 stars or more (syntax based on GitHub search query)
-    plugin_notable_from: organization    # Only display contributions within organization repositories
-    plugin_notable_repositories: yes     # Display repositories name instead of only organization name
+    plugin_notable_filter: stars:>500 # Only display repositories with 500 stars or more (syntax based on GitHub search query)
+    plugin_notable_from: organization # Only display contributions within organization repositories
+    plugin_notable_repositories: yes  # Display repositories name instead of only organization name
+    plugin_notable_indepth: yes       # Gather additional informations about contributions
 ```

source/plugins/notable/metadata.yml

@@ -1,5 +1,4 @@
 name: "🎩 Notable contributions"
-cost: 1 GraphQL request per 100 repositories fetched
 category: github
 index: 20
 supports:

source/plugins/pagespeed/metadata.yml

@@ -1,5 +1,4 @@
 name: "⏱️ Website performances"
-cost: N/A
 category: social
 index: 1
 supports: