From e825d08362def15f57f57f1e66120c1f3d32ffa1 Mon Sep 17 00:00:00 2001 From: lowlighter <22963968+lowlighter@users.noreply.github.com> Date: Sun, 16 Jan 2022 18:14:36 -0500 Subject: [PATCH] docs: move templated files to a dedicated folder --- .../readme/{ => partials/templated}/README.md | 2 +- .../partials/templated/compatibility.md | 31 +++++ .../partials/{ => templated}/documentation.md | 4 +- .../partials/{ => templated}/introduction.md | 0 .../{documentation => templated}/plugins.md | 0 .../{documentation => templated}/templates.md | 0 .github/scripts/build.mjs | 8 +- source/templates/community/README.md | 118 ------------------ 8 files changed, 39 insertions(+), 124 deletions(-) rename .github/readme/{ => partials/templated}/README.md (84%) create mode 100644 .github/readme/partials/templated/compatibility.md rename .github/readme/partials/{ => templated}/documentation.md (75%) rename .github/readme/partials/{ => templated}/introduction.md (100%) rename .github/readme/partials/{documentation => templated}/plugins.md (100%) rename .github/readme/partials/{documentation => templated}/templates.md (100%) diff --git a/.github/readme/README.md b/.github/readme/partials/templated/README.md similarity index 84% rename from .github/readme/README.md rename to .github/readme/partials/templated/README.md index 557e1821..bc3308e5 100644 --- a/.github/readme/README.md +++ b/.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`) %> <% } %> diff --git a/.github/readme/partials/templated/compatibility.md b/.github/readme/partials/templated/compatibility.md new file mode 100644 index 00000000..3c7cc379 --- /dev/null +++ b/.github/readme/partials/templated/compatibility.md @@ -0,0 +1,31 @@ +# 🧰 Template/Plugin compatibility matrix + + + + <%# -%> + <% for (const [plugin, {name, icon}] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) { %> + <% } %> + <%# -%> + <% for (const [template, {name, readme}] of Object.entries(templates).filter(([key, value]) => (value)&&(!["community"].includes(key)))) { %> + + <%# -%> + <% for (const [plugin] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) { %> + <% } %> + <% } %> + + + + + <%# -%> + <% for (const [plugin, {name, icon}] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) { %> + <% } %> + <%# -%> + <% for (const {mode, icon} of [{mode:"user", icon:"👤"}, {mode:"organization", icon:"đŸ‘Ĩ"}, {mode:"repository", icon:"📓"}]) { %> + + <%# -%> + <% for (const [plugin, {supports}] of Object.entries(plugins).filter(([key, value]) => (value)&&(!["core"].includes(key))&&(value.category !== "community"))) {%> + <% } %> + <% } %> +
Template/Plugin<%= icon %>
<%- name %><%= {true:"✔ī¸", false:"❌", embed:"✓"}[readme.compatibility[plugin]] %>
Mode/Plugin<%= icon %>
<%= icon %> <%- `${mode.charAt(0).toLocaleUpperCase()}${mode.substring(1)}` %><%= supports.includes(mode) ? "✔ī¸" : "❌" %>
+ +*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)* diff --git a/.github/readme/partials/documentation.md b/.github/readme/partials/templated/documentation.md similarity index 75% rename from .github/readme/partials/documentation.md rename to .github/readme/partials/templated/documentation.md index cb6af72b..50b9cfc7 100644 --- a/.github/readme/partials/documentation.md +++ b/.github/readme/partials/templated/documentation.md @@ -4,6 +4,6 @@ > *⚠ī¸ 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).* <% } %> -<% for (const partial of ["setup", "templates", "plugins", "contributing"]) { %> -<%- await include(`/partials/documentation/${partial}.md`) -%> +<% for (const partial of ["documentation/setup", "templated/templates", "templated/plugins", "documentation/contributing"]) { %> +<%- await include(`/partials/${partial}.md`) -%> <% } %> diff --git a/.github/readme/partials/introduction.md b/.github/readme/partials/templated/introduction.md similarity index 100% rename from .github/readme/partials/introduction.md rename to .github/readme/partials/templated/introduction.md diff --git a/.github/readme/partials/documentation/plugins.md b/.github/readme/partials/templated/plugins.md similarity index 100% rename from .github/readme/partials/documentation/plugins.md rename to .github/readme/partials/templated/plugins.md diff --git a/.github/readme/partials/documentation/templates.md b/.github/readme/partials/templated/templates.md similarity index 100% rename from .github/readme/partials/documentation/templates.md rename to .github/readme/partials/templated/templates.md diff --git a/.github/scripts/build.mjs b/.github/scripts/build.mjs index 4281ce30..447a4770 100644 --- a/.github/scripts/build.mjs +++ b/.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(__readme, "partials/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, "README.md"), output: "README.md", options: { root: __readme } }) + await update({ source: paths.join(__documentation, "plugins.md"), output: "source/plugins/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 } } diff --git a/source/templates/community/README.md b/source/templates/community/README.md index 68651c41..02d7fae4 100644 --- a/source/templates/community/README.md +++ b/source/templates/community/README.md @@ -76,124 +76,6 @@ with: ``` - -## đŸ“Ē 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 -``` - -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 - - - - - - -
- <% for (const partial of [...partials]) { %> - <%- await include(`partials/${partial}.ejs`) %> - <% } %> - -
-
- - - -``` - -#### 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 - - -``` - -`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 - - - ``` ### đŸ’Ŧ Creating partials