From 3b9c481bc28b7f787fe903d50b97887a4c75b7cd Mon Sep 17 00:00:00 2001 From: lowlighter <22963968+lowlighter@users.noreply.github.com> Date: Fri, 14 Jan 2022 21:38:44 -0500 Subject: [PATCH] docs(templates/markdown): rewrite documentation --- source/templates/markdown/README.md | 148 +++++++++++++++++------ source/templates/markdown/example.md | 48 +------- source/templates/markdown/example.pdf.md | 4 +- 3 files changed, 114 insertions(+), 86 deletions(-) diff --git a/source/templates/markdown/README.md b/source/templates/markdown/README.md index 1d63a0b9..011fb4cf 100644 --- a/source/templates/markdown/README.md +++ b/source/templates/markdown/README.md @@ -1,50 +1,118 @@ -### 📒 Markdown template - -Markdown template can render a **markdown template** by interpreting **templating brackets** `{{` and `}}`. - - - -
- - -
- -It can be used to render custom markdown which include data gathered by metrics. -Unlike SVG templates, it is possible to include revelant hyperlinks since it'll be rendered as regular markdown. - -You can even mix it with SVG plugins for even more customization using `embed` function. - -See [example.md](/source/templates/markdown/example.md) for a markdown template example. - -> Note that available data still depends on which plugins have been enabled. -> You may need to handle errors and setup plugins correctly in order to access to their output data. - -To find which data can be used, you can run a workflow with `config_output: json`. -For convenience, several useful properties are aliased in [/source/templates/markdown/template.mjs](/source/templates/markdown/template.mjs). + + #### ℹī¸ Examples workflows -[➡ī¸ Supported formats and inputs](metadata.yml) + + -```yaml -# Markdown output -- uses: lowlighter/metrics@latest - with: - # ... other options - template: markdown - filename: README.md # Output file - markdown: TEMPLATE.md # Template file - markdown_cache: .cache # Cache folder +___ + +This template can be used to a *markdown template file* with data gathered by metrics. + +Since the resulting output is a markdown file, it is possible to do additional formatting such as creating hyperlinks and adding custom texts. + +## 🈂ī¸ Templating syntax: + +The templating engine is [EJS](https://github.com/mde/ejs) and can be used to interpolate any data retrieved by metrics. + +* `<%=` and `%>` are used to display escaped output + * `{{` and `}}` is also supported as syntaxic sugar +* `<%-` and `%>` are used to display raw output +* `<%` and `%>` are used to execute JavaScript, and can also contains control statements such as conditionals and loops + +*Example: basic templating* +```markdown + +I joined GitHub on `{{ f.date(REGISTRATION_DATE, {date:true}) }}`. +I contributed to `{{ REPOSITORIES_CONTRIBUTED_TO }}` repositories and made `{{ COMMITS }}` commits. + + +I joined GitHub on `20 Oct 2016`. +I contributed to `37` repositories and made `5947` commits. ``` -```yaml -# PDF output +## đŸ”Ŗ Available data + +Any data fetched by metrics and exposed formatting helpers can be used. + +It also means that to access plugins data they must be enabled and configured beforehand. + +*Example: enabling `plugin_activity` exposes `plugins.activity` data* +```yml - uses: lowlighter/metrics@latest with: - # ... other options template: markdown - filename: render.pdf # Output file - markdown: TEMPLATE.md # Template file - markdown_cache: .cache # Cache folder - config_output: markdown-pdf # Output as pdf file + plugin_activity: yes ``` + +> 💡 To avoid failures while accessing data, use [optional chaining operator `?.`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) or ensure that no errors where reported by a given plugin. + +> ⚠ī¸ Although rare, data schemas may change in-between metrics version without any notice (these changes are not documented in release notes). It is advised to use a pinned version or a fork when using this template. + +A few properties are aliased in [/source/templates/markdown/template.mjs](/source/templates/markdown/template.mjs) for convenience. + +Use `config_output: json` to dump all available data for a given configuration. Power users can also directly read [metrics source code](https://github.com/lowlighter/metrics) to know what is exposed. + +For a quick overview, it is also possible to use [metrics.lecoq.io/{username}?config.output=json](https://metrics.lecoq.io). + +> 💡 Note however that [metrics.lecoq.io](https://metrics.lecoq.io) has a caching system which may prevent any new result. + +## 🧩 Plugins with markdown version + +Several plugins have a markdown version which provides better usability, usually with hyperlinks and better text formatting. + +*Example: using `✒ī¸ posts` plugin markdown version* +```ejs +<%- await include(`partials/posts.ejs`) %> +``` + +**[✒ī¸ Recent posts from dev.to](https://dev.to/lowlighter)** + + + + + + + + +
+ + + Metrics v3.0, the ultimate tool to pimp your GitHub profile! +
+ Metrics is an extensive SVG images generator plugged with various APIs (GitHub, Twitter, Spotify, ...... +
+ Published on 4 Jan 2021 +
+ +> 💡 Remember, plugins still need to be enabled and configured in workflow file! + +## 🎈 Embedding SVG metrics on-the-fly + +An additional feature which makes the markdown template more powerful than its counterparts is that it can also render SVG on the fly using `embed()` function, without creating any additional jobs. + +These renders will automatically be pushed to `markdown_cache` folder and included in the markdown render. + +```yml +- uses: lowlighter/metrics@latest + with: + template: markdown + markdown_cache: .cache +``` + +The `embed()` function takes two arguments: +1. An unique file identifier (which will be used to store render in `${markdown_cache}/${file_identifier}`) +2. Configuration options + - Note that `token` options are automatically passed down from overall configuration, do not pass them again (especially in clear) in it + +*Example: embed a `🈷ī¸ languages` SVG render* +```ejs +<%- await embed(`example-languages-pdf`, {languages:true, languages_details:"percentage, bytes-size", config_display:"large"}) %> +``` + + + +> 💡 The `plugin_` prefix can be dropped for convenience + +> 💡 The `embed()` function does not have `🗃ī¸ base` plugin enabled by default. To use it, it is required to explicitely pass them through `base` option. diff --git a/source/templates/markdown/example.md b/source/templates/markdown/example.md index 39ab7e83..c2c15d28 100644 --- a/source/templates/markdown/example.md +++ b/source/templates/markdown/example.md @@ -1,32 +1,8 @@ # 📒 Markdown template example -This is a markdown template example which explain the basic usage of this template. - See [rendering of this file here](https://github.com/lowlighter/lowlighter/blob/master/metrics.markdown.full.md) and [original template source here](https://github.com/lowlighter/metrics/blob/master/source/templates/markdown/example.md). -## 🈂ī¸ Templating syntax: - -* Regular EJS syntax is supported -* `{{` and `}}` will be interpolated as EJS brackets (syntaxic sugar) - * `{%` and `%}` can be used as control statements -* Use [metrics.lecoq.io](https://metrics.lecoq.io/) with `config.output=json` to see available data - * You can also use `config_output: json` in GitHub Actions and/or inspect [metrics](https://github.com/lowlighter/metrics) code to get available data too -* Same formatting helpers available in templates can be used too - -```markdown -I joined GitHub on `{{ f.date(REGISTRATION_DATE, {date:true}) }}`. -I contributed to `{{ REPOSITORIES_CONTRIBUTED_TO }}` repositories and made `{{ COMMITS }}` commits. -``` - -## 🧩 Plugins - -### Using markdown plugins - -Some plugins have their own **markdown** version which includes hyperlinks and reduce image overhead. - -See [compatibility matrix](https://github.com/lowlighter/metrics#-plugin-compatibility-matrix) for more informations. - -___ +## 🧩 Plugins with markdown version <%- await include(`partials/activity.ejs`) %> @@ -46,28 +22,14 @@ ___ <%- await include(`partials/topics.ejs`) %> -### Embedding SVG metrics - -To include SVGs metrics images without creating additional jobs, use the `embed` function: +## 🎈 Embedding SVG metrics on-the-fly <%- await embed(`example-isocalendar`, {isocalendar:true, isocalendar_duration:"full-year", config_display:"large"}) %> +___ + <%- await embed(`example-languages-pdf`, {languages:true, languages_details:"percentage, bytes-size", config_display:"large"}) %> -It takes two arguments: -- An unique identifier which will be used as filename withing `markdown_cache` folder -- Configuration options (see [action.yml](https://github.com/lowlighter/metrics/blob/master/action.yml)) - - Tokens options are automatically passed down from your workflow job, do not pass them again - -Embed plugins must still be enabled at top-level in order to work: -```yml -- uses: lowlighter/metrics@latest - with: - isocalendar: yes - languages: yes -``` - -Note that unlike regular workflow jobs, `embed` function does not have `base` plugin enabled by default. -If you wish to diplay parts of it, they must be explicitely enabled: +___ <%- await embed(`example-base-pdf`, {base:"activity, community, repositories"}) %> diff --git a/source/templates/markdown/example.pdf.md b/source/templates/markdown/example.pdf.md index 49cf5c78..2f8f80e9 100644 --- a/source/templates/markdown/example.pdf.md +++ b/source/templates/markdown/example.pdf.md @@ -1,12 +1,10 @@ # 📒 Markdown template example (pdf) -When using **markdown template**, it is possible to export output as PDF. - See [rendering of this file here](https://github.com/lowlighter/lowlighter/blob/master/metrics.markdown.pdf) and [original template source here](https://github.com/lowlighter/metrics/blob/master/source/templates/markdown/example.pdf.md). ## 🧩 Plugins -You can customize your template with both markdown plugins and SVG plugins like below: +All markdown features are supported, meaning that both markdown plugins and SVG renders can be used. <%- await include(`partials/rss.ejs`) %>