docs: move templated files to a dedicated folder

.github/readme/partials/templated/README.md

@@ -2,6 +2,6 @@
 
 [![Continuous integration](https://github.com/lowlighter/metrics/actions/workflows/ci.yml/badge.svg)](https://github.com/lowlighter/metrics/actions/workflows/ci.yml)
 
-<% for (const partial of ["introduction", "documentation", "license"]) { -%>
+<% for (const partial of ["templated/introduction", "templated/documentation", "license"]) { -%>
 <%- await include(`/partials/${partial}.md`) %>
 <% } %>

.github/readme/partials/templated/compatibility.md

@@ -0,0 +1,31 @@
+# 🧰 Template/Plugin compatibility matrix
+
+<table>
+  <tr>
+    <th nowrap="nowrap">Template/Plugin</th><%# -%>
+    <% for (const [plugin, {name, icon}] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) { %>
+    <th nowrap="nowrap" align="center" title="<%= name %>"><%= icon %></th><% } %>
+  </tr><%# -%>
+  <% for (const [template, {name, readme}] of Object.entries(templates).filter(([key, value]) => (value)&&(!["community"].includes(key)))) { %>
+  <tr>
+    <td nowrap="nowrap"><%- name %></td><%# -%>
+    <% for (const [plugin] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) { %>
+    <td nowrap="nowrap" align="center" data-plugin="<%= plugin %>"><%= {true:"✔️", false:"❌", embed:"✓"}[readme.compatibility[plugin]] %></td><% } %>
+  </tr><% } %>
+  <tr>
+    <td colspan="<%= Object.keys(plugins).length %>"></td>
+  </tr>
+  <tr>
+    <th nowrap="nowrap">Mode/Plugin</th><%# -%>
+    <% for (const [plugin, {name, icon}] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) { %>
+    <th nowrap="nowrap" align="center" title="<%= name %>"><%= icon %></th><% } %>
+  </tr><%# -%>
+  <% for (const {mode, icon} of [{mode:"user", icon:"👤"}, {mode:"organization", icon:"👥"}, {mode:"repository", icon:"📓"}]) { %>
+  <tr>
+    <td nowrap="nowrap"><%= icon %> <%- `${mode.charAt(0).toLocaleUpperCase()}${mode.substring(1)}` %></td><%# -%>
+    <% for (const [plugin, {supports}] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) {%>
+    <td nowrap="nowrap" align="center" data-plugin="<%= plugin %>"><%= supports.includes(mode) ? "✔️" : "❌" %></td><% } %>
+  </tr><% } %>
+</table>
+
+*Note: **markdown template** can actually render any kind of SVG metrics using [`embed` function](https://github.com/lowlighter/metrics/blob/master/source/templates/markdown/example.md#embedding-svg-metrics)*

.github/readme/partials/templated/documentation.md

@@ -4,6 +4,6 @@
 > <sup>*⚠️ This is the documentation of **v<%= packaged.version.replace(/[.]0-beta$/, "") %>-beta** (`@master`/`@main` branches) which includes [unreleased features](https://github.com/lowlighter/metrics/compare/latest...master). See documentation for [**v<%= (Number(packaged.version.replace(/[.]0-beta$/, ""))-0.01).toFixed(2).replace(/[.]0/, ".") %>** (`@latest` branch) here](https://github.com/lowlighter/metrics/blob/latest/README.md).*</sup>
 <% } %>
 
-<% for (const partial of ["setup", "templates", "plugins", "contributing"]) { %>
+<% for (const partial of ["documentation/setup", "templated/templates", "templated/plugins", "documentation/contributing"]) { %>
-<%- await include(`/partials/documentation/${partial}.md`) -%>
+<%- await include(`/partials/${partial}.md`) -%>
 <% } %>

.github/scripts/build.mjs

@@ -17,6 +17,7 @@ const __metrics = paths.join(paths.dirname(url.fileURLToPath(import.meta.url)),
 const __action = paths.join(__metrics, "source/app/action")
 const __web = paths.join(__metrics, "source/app/web")
 const __readme = paths.join(__metrics, ".github/readme")
+const __documentation = paths.join(__metrics, ".github/readme/partials/templated")
 const __templates = paths.join(paths.join(__metrics, "source/templates/"))
 const __plugins = paths.join(paths.join(__metrics, "source/plugins/"))
 const __test_cases = paths.join(paths.join(__metrics, "tests/cases"))
@@ -37,9 +38,10 @@ for (const step of ["config", "documentation"]) {
       await update({ source: paths.join(__web, "settings.example.json"), output: "settings.example.json" })
       break
     case "documentation":
-      await update({ source: paths.join(__readme, "README.md"), output: "README.md", options: { root: __readme } })
+      await update({ source: paths.join(__documentation, "README.md"), output: "README.md", options: { root: __readme } })
-      await update({ source: paths.join(__readme, "partials/documentation/plugins.md"), output: "source/plugins/README.md" })
+      await update({ source: paths.join(__documentation, "plugins.md"), output: "source/plugins/README.md" })
-      await update({ source: paths.join(__readme, "partials/documentation/templates.md"), output: "source/templates/README.md" })
+      await update({ source: paths.join(__documentation, "templates.md"), output: "source/templates/README.md" })
+      await update({ source: paths.join(__documentation, "compatibility.md"), output: ".github/readme/partials/documentation/compatibility.md" })
       break
   }
 }

source/templates/community/README.md

@@ -76,124 +76,6 @@ with:
 
 ```
 <!--/examples-->
-
-## 📪 Creating community templates
-
-Templates creation requires you to be comfortable with HTML, CSS and JavaScript ([EJS](https://github.com/mde/ejs) flavored).
-
-To create a new template, clone and setup this repository first:
-```shell
-git clone https://github.com/lowlighter/metrics.git
-cd metrics/
-npm install
-```
-
-Find a cool name for your new template and run the following:
-```shell
-npm run quickstart template <template_name>
-```
-
-It will create a new directory in `/source/templates` with the following file structure:
-* `/source/templates/{template-name}`
-  * `README.md`,
-  * `metadata.yml`,
-  * `image.svg`
-  * `partials/`
-    * `_.json`
-    * `*.ejs`
-
-Templates are auto-loaded based on their folder existence, so there's no need to register them somewhere.
-
-### 💬 Understanding `image.svg`
-
-Usually `image.svg` doesn't need to be edited too much, but let's explain it how it works.
-
-```html
-<svg xmlns="http://www.w3.org/2000/svg" width="480" height="99999" class="<%= !animated ? 'no-animations' : '' %>">
-
-  <defs><style><%= fonts %></style></defs>
-  <style data-optimizable="true"><%= style %></style>
-
-  <foreignObject x="0" y="0" width="100%" height="100%">
-    <div xmlns="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink">
-      <% for (const partial of [...partials]) { %>
-        <%- await include(`partials/${partial}.ejs`) %>
-      <% } %>
-
-      <div id="metrics-end"></div>
-    </div>
-  </foreignObject>
-
-</svg>
-```
-
-#### EJS syntax
-
-[EJS](https://github.com/mde/ejs) framework is used to programmatically create content through the help of templating tags (`<% %>`).
-
-#### Styling
-
-`fonts` and `style` variables are respectively populated with `fonts.css` and `styles.css` files content (or will fallback to those of `classic` template inexistent).
-
-These will define the global design of the output.
-
-`data-optimizable="true"` tells that a `style` tag can be safely minified and purged by CSS post-processors.
-
-#### Partials
-
-`partials` variable is populated with `partials/_.json` file content and define which files should be included along with default ordering.
-
-The loop iterates over this array to include all defined partials. Each partial should handle whether it should be displayed by itself.
-
-### `#metrics-end` tag
-
-`#metrics-end` is a special HTML tag which must remain at the bottom of SVG template.
-
-It is used to compute height dynamically through a [puppeteer](https://github.com/puppeteer/puppeteer) headless instance. Initial height should remain a high number so it doesn't get cropped accidentally while [puppeteer](https://github.com/puppeteer/puppeteer) compute [element.getBoundingClientRect()](https://developer.mozilla.org/fr/docs/Web/API/Element/getBoundingClientRect).
-
-### 💬 Filling `metadata.yml`
-
-`metadata.yml` is a file which describes supported account types, output formats, scopes, etc.
-
-```yaml
-name: "🖼️ Template name"
-extends: classic
-description: Short description
-examples:
-  default: https://via.placeholder.com/468x60?text=No%20preview%20available
-supports:
-  - user
-  - organization
-  - repository
-formats:
-  - svg
-  - png
-  - jpeg
-  - json
-  - markdown
-  - markdown-pdf
-```
-
-[`🧱 core`](/source/plugins/core/README.md) plugin will automatically check user inputs with your defined supported `supports` and `formats` key and throw an error in case of incompatibility.
-
-`name`, `description` and `examples` are used to auto-generate documentation in the `README.md` by replacing the following:
-
-```markdown
-<!--header-->
-<!--/header-->
-```
-
-`extends` is used to define upon which template it should inherits its `template.mjs` when it is not trusted by user.
-
-### 💬 Filling `examples.yml`
-
-Workflow examples from `examples.yml` are used to auto-generate documentation in the `README.md` by replacing the following:
-
-```markdown
-#### ℹ️ Examples workflows
-
-<!--examples-->
-<!--/examples-->
 ```
 
 ### 💬 Creating partials