doc(plugins/contributors): update

source/plugins/contributors/README.md

@@ -1,40 +1,29 @@
-### 🏅 Repository contributors
-
-The *contributors* plugin lets you display repositories contributors from a commit range, that can be specified through either sha, tags, branch, etc.
-
-It's especially useful to acknowledge contributors on release notes.
-
+<!--header-->
 <table>
-  <td align="center">
-    <details open><summary>By contribution types</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.categories.svg">
-    </details>
-    <details><summary>By number of contributions</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.contributions.svg">
-    </details>
-    <img width="900" height="1" alt="">
-  </td>
+  <tr><th colspan="2"><h3>🏅 Repository contributors</h3></th></tr>
+  <tr><td colspan="2" align="center"><p>This plugin display repositories contributors from a commit range along with additional stats.</p>
+</td></tr>
+  <tr>
+    <th rowspan="3">Supported features<br><sub><a href="metadata.yml">→ Full specification</a></sub></th>
+    <td><a href="/source/templates/repository"><code>📘 Repository template</code></a></td>
+  </tr>
+  <tr>
+    <td><code>📓 Repositories</code></td>
+  </tr>
+  <tr>
+    <td><code>🔑 (scopeless)</code> <code>read:org (optional)</code> <code>read:user (optional)</code> <code>repo (optional)</code></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center">
+      <details open><summary>By contribution types</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.categories.svg" alt=""></img></details>
+      <details><summary>By number of contributions</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.contributions.svg" alt=""></img></details>
+      <img width="900" height="1" alt="">
+    </td>
+  </tr>
 </table>
+<!--/header-->
 
-**Displaying contributors per categories**
-
-> 🔣 On web instances, sorting contributors per categories is an extra feature and must be enabled globally in `settings.json`
-
-To configure contributions categories, pass a JSON object to `plugin_contributors_categories` (use `|` multiline operator for better readability) with categories names as keys and an array of file glob as values:
-
-```yaml
-plugin_contributors_categories: |
-  {
-    "📚 Documentation": ["README.md", "docs/**"],
-    "💻 Code": ["source/**", "src/**"],
-    "#️⃣ Others": ["*"]
-  }
-```
-
-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
+## ➡️ Available options
 
 <!--options-->
 <table>
@@ -43,7 +32,7 @@ Matching is performed in keys order.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_contributors</code></td>
-    <td rowspan="2"><p>Display repository contributors</p>
+    <td rowspan="2"><p>Enable contributors plugin</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -53,7 +42,7 @@ Matching is performed in keys order.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_contributors_base</code></td>
-    <td rowspan="2"><p>Base reference</p>
+    <td rowspan="2"><p>Base reference (commit, tag, branch, etc.)</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -62,7 +51,7 @@ Matching is performed in keys order.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_contributors_head</code></td>
-    <td rowspan="2"><p>Head reference</p>
+    <td rowspan="2"><p>Head reference (commit, tag, branch, etc.)</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -72,19 +61,19 @@ Matching is performed in keys order.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_contributors_ignored</code></td>
-    <td rowspan="2"><p>Contributors to ignore</p>
+    <td rowspan="2"><p>Ignored users</p>
+<p>Useful to ignore bots activity</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
     <td nowrap="nowrap">⏩ Inherits <code>users_ignored</code><br>
 <b>type:</b> <code>array</code>
 <i>(comma-separated)</i>
-<br>
-<b>default:</b> github-actions[bot], dependabot[bot], dependabot-preview[bot]<br></td>
+<br></td>
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_contributors_contributions</code></td>
-    <td rowspan="2"><p>Display contributions</p>
+    <td rowspan="2"><p>Toggle number of contributions display</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -94,7 +83,11 @@ Matching is performed in keys order.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_contributors_sections</code></td>
-    <td rowspan="2"><p>Sections to display</p>
+    <td rowspan="2"><p>Displayed sections</p>
+<ul>
+<li><code>contributors</code>: all contributors</li>
+<li><code>categories</code>: contributors sorted by contributions categories</li>
+</ul>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -106,7 +99,9 @@ Matching is performed in keys order.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_contributors_categories</code></td>
-    <td rowspan="2"><p>Contributions categories</p>
+    <td rowspan="2"><p>Configure contribution categories</p>
+<p>This option required <code>plugin_contributors_sections</code> to have <code>categories</code> in it to be effective
+Pass a JSON object mapping category with fileglobs</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -123,9 +118,30 @@ Matching is performed in keys order.
 </table>
 <!--/options-->
 
-*[→ Full specification](metadata.yml)*
+## 🗂️ Setting up contribution categories
 
-#### ℹ️ Examples workflows
+Pass a JSON object to `plugin_contributors_categories` with categories names as keys and arrays of fileglobs as values to configure contributions categories.
+
+Each modified file by a contributor matching a fileglob will add them in said category.
+
+> 💡 File matching respect keys order
+
+> 💡 Use `|` YAML multiline operator for better readability
+
+*Example: *
+```yaml
+- uses: lowlighter/metrics@latest
+  with:
+    plugin_contributors: yes
+    plugin_contributors_categories: |
+      {
+        "📚 Documentation": ["README.md", "docs/**"],
+        "💻 Code": ["source/**", "src/**"],
+        "#️⃣ Others": ["*"]
+      }
+```
+
+## ℹ️ Examples workflows
 
 <!--examples-->
 ```yaml
@@ -160,4 +176,4 @@ with:
     }
 
 ```
-<!--/examples-->
+<!--/examples-->