Skip to content

Commit 3b9c481

Browse files
lowlighterlowlighter
committed
docs(templates/markdown): rewrite documentation
1 parent 93a821f commit 3b9c481

File tree

3 files changed

+105
-77
lines changed

3 files changed

+105
-77
lines changed

‎source/templates/markdown/README.md‎

Lines changed: 99 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,118 @@
1-
### 📒 Markdown template
1+
<!--header-->
2+
<!--/header-->
23

3-
Markdown template can render a **markdown template** by interpreting **templating brackets** `{{` and `}}`.
4+
#### ℹ️ Examples workflows
45

5-
<table>
6-
<td align="center">
7-
<img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.markdown.png">
8-
<img width="900" height="1" alt="">
9-
</td>
10-
</table>
6+
<!--examples-->
7+
<!--/examples-->
118

12-
It can be used to render custom markdown which include data gathered by metrics.
13-
Unlike SVG templates, it is possible to include revelant hyperlinks since it'll be rendered as regular markdown.
9+
___
1410

15-
You can even mix it with SVG plugins for even more customization using `embed` function.
11+
This template can be used to a *markdown template file* with data gathered by metrics.
1612

17-
See [example.md](/source/templates/markdown/example.md) for a markdown template example.
13+
Since the resulting output is a markdown file, it is possible to do additional formatting such as creating hyperlinks and adding custom texts.
1814

19-
> Note that available data still depends on which plugins have been enabled.
20-
> You may need to handle errors and setup plugins correctly in order to access to their output data.
15+
## 🈂️ Templating syntax:
2116

22-
To find which data can be used, you can run a workflow with `config_output: json`.
23-
For convenience, several useful properties are aliased in [/source/templates/markdown/template.mjs](/source/templates/markdown/template.mjs).
17+
The templating engine is [EJS](https://github.com/mde/ejs) and can be used to interpolate any data retrieved by metrics.
2418

25-
#### ℹ️ Examples workflows
19+
* `<%=` and `%>` are used to display escaped output
20+
* `{{` and `}}` is also supported as syntaxic sugar
21+
* `<%-` and `%>` are used to display raw output
22+
* `<%` and `%>` are used to execute JavaScript, and can also contains control statements such as conditionals and loops
23+
24+
*Example: basic templating*
25+
```markdown
26+
<!-- template -->
27+
I joined GitHub on `{{ f.date(REGISTRATION_DATE, {date:true}) }}`.
28+
I contributed to `{{ REPOSITORIES_CONTRIBUTED_TO }}` repositories and made `{{ COMMITS }}` commits.
29+
30+
<!-- render -->
31+
I joined GitHub on `20 Oct 2016`.
32+
I contributed to `37` repositories and made `5947` commits.
33+
```
34+
35+
## 🔣 Available data
2636

27-
[➡️ Supported formats and inputs](metadata.yml)
37+
Any data fetched by metrics and exposed formatting helpers can be used.
2838

29-
```yaml
30-
# Markdown output
39+
It also means that to access plugins data they must be enabled and configured beforehand.
40+
41+
*Example: enabling `plugin_activity` exposes `plugins.activity` data*
42+
```yml
3143
- uses: lowlighter/metrics@latest
3244
with:
33-
# ... other options
3445
template: markdown
35-
filename: README.md # Output file
36-
markdown: TEMPLATE.md # Template file
37-
markdown_cache: .cache # Cache folder
46+
plugin_activity: yes
47+
```
48+
49+
> 💡 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.
50+
51+
> ⚠️ 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.
52+
53+
A few properties are aliased in [/source/templates/markdown/template.mjs](/source/templates/markdown/template.mjs) for convenience.
54+
55+
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.
56+
57+
For a quick overview, it is also possible to use [metrics.lecoq.io/{username}?config.output=json](https://metrics.lecoq.io).
58+
59+
> 💡 Note however that [metrics.lecoq.io](https://metrics.lecoq.io) has a caching system which may prevent any new result.
60+
61+
## 🧩 Plugins with markdown version
62+
63+
Several plugins have a markdown version which provides better usability, usually with hyperlinks and better text formatting.
64+
65+
*Example: using `✒️ posts` plugin markdown version*
66+
```ejs
67+
<%- await include(`partials/posts.ejs`) %>
3868
```
3969

40-
```yaml
41-
# PDF output
70+
**[✒️ Recent posts from dev.to](https://dev.to/lowlighter)**
71+
<table>
72+
<tr>
73+
<td rowspan="2" width="280">
74+
<img src="https://res.cloudinary.com/practicaldev/image/fetch/s--rbmokFTg--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://dev-to-uploads.s3.amazonaws.com/i/idot5ak9irxtu948bgzs.png" alt="" width="280">
75+
</td>
76+
<th>
77+
<a href="https://dev.to/lowlighter/metrics-v3-0-the-ultimate-tool-to-pimp-your-github-profile-g7p">Metrics v3.0, the ultimate tool to pimp your GitHub profile!</a>
78+
</th>
79+
</tr>
80+
<tr>
81+
<td>
82+
Metrics is an extensive SVG images generator plugged with various APIs (GitHub, Twitter, Spotify, ......
83+
<br>
84+
<i>Published on 4 Jan 2021</i>
85+
</td>
86+
</tr>
87+
</table>
88+
89+
> 💡 Remember, plugins still need to be enabled and configured in workflow file!
90+
91+
## 🎈 Embedding SVG metrics on-the-fly
92+
93+
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.
94+
95+
These renders will automatically be pushed to `markdown_cache` folder and included in the markdown render.
96+
97+
```yml
4298
- uses: lowlighter/metrics@latest
4399
with:
44-
# ... other options
45100
template: markdown
46-
filename: render.pdf # Output file
47-
markdown: TEMPLATE.md # Template file
48-
markdown_cache: .cache # Cache folder
49-
config_output: markdown-pdf # Output as pdf file
101+
markdown_cache: .cache
102+
```
103+
104+
The `embed()` function takes two arguments:
105+
1. An unique file identifier (which will be used to store render in `${markdown_cache}/${file_identifier}`)
106+
2. Configuration options
107+
- Note that `token` options are automatically passed down from overall configuration, do not pass them again (especially in clear) in it
108+
109+
*Example: embed a `🈷️ languages` SVG render*
110+
```ejs
111+
<%- await embed(`example-languages-pdf`, {languages:true, languages_details:"percentage, bytes-size", config_display:"large"}) %>
50112
```
113+
114+
<img src="https://github.com/lowlighter/lowlighter/blob/master/.cache/example-languages-pdf.svg">
115+
116+
> 💡 The `plugin_` prefix can be dropped for convenience
117+
118+
> 💡 The `embed()` function does not have `🗃️ base` plugin enabled by default. To use it, it is required to explicitely pass them through `base` option.

‎source/templates/markdown/example.md‎

Lines changed: 5 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,8 @@
11
# 📒 Markdown template example
22

3-
This is a markdown template example which explain the basic usage of this template.
4-
53
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).
64

7-
## 🈂️ Templating syntax:
8-
9-
* Regular EJS syntax is supported
10-
* `{{` and `}}` will be interpolated as EJS brackets (syntaxic sugar)
11-
* `{%` and `%}` can be used as control statements
12-
* Use [metrics.lecoq.io](https://metrics.lecoq.io/) with `config.output=json` to see available data
13-
* 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
14-
* Same formatting helpers available in templates can be used too
15-
16-
```markdown
17-
I joined GitHub on `{{ f.date(REGISTRATION_DATE, {date:true}) }}`.
18-
I contributed to `{{ REPOSITORIES_CONTRIBUTED_TO }}` repositories and made `{{ COMMITS }}` commits.
19-
```
20-
21-
## 🧩 Plugins
22-
23-
### Using markdown plugins
24-
25-
Some plugins have their own **markdown** version which includes hyperlinks and reduce image overhead.
26-
27-
See [compatibility matrix](https://github.com/lowlighter/metrics#-plugin-compatibility-matrix) for more informations.
28-
29-
___
5+
## 🧩 Plugins with markdown version
306

317
<%- await include(`partials/activity.ejs`) %>
328

@@ -46,28 +22,14 @@ ___
4622

4723
<%- await include(`partials/topics.ejs`) %>
4824

49-
### Embedding SVG metrics
50-
51-
To include SVGs metrics images without creating additional jobs, use the `embed` function:
25+
## 🎈 Embedding SVG metrics on-the-fly
5226

5327
<%- await embed(`example-isocalendar`, {isocalendar:true, isocalendar_duration:"full-year", config_display:"large"}) %>
5428

29+
___
30+
5531
<%- await embed(`example-languages-pdf`, {languages:true, languages_details:"percentage, bytes-size", config_display:"large"}) %>
5632

57-
It takes two arguments:
58-
- An unique identifier which will be used as filename withing `markdown_cache` folder
59-
- Configuration options (see [action.yml](https://github.com/lowlighter/metrics/blob/master/action.yml))
60-
- Tokens options are automatically passed down from your workflow job, do not pass them again
61-
62-
Embed plugins must still be enabled at top-level in order to work:
63-
```yml
64-
- uses: lowlighter/metrics@latest
65-
with:
66-
isocalendar: yes
67-
languages: yes
68-
```
69-
70-
Note that unlike regular workflow jobs, `embed` function does not have `base` plugin enabled by default.
71-
If you wish to diplay parts of it, they must be explicitely enabled:
33+
___
7234

7335
<%- await embed(`example-base-pdf`, {base:"activity, community, repositories"}) %>

‎source/templates/markdown/example.pdf.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
11
# 📒 Markdown template example (pdf)
22

3-
When using **markdown template**, it is possible to export output as PDF.
4-
53
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).
64

75
## 🧩 Plugins
86

9-
You can customize your template with both markdown plugins and SVG plugins like below:
7+
All markdown features are supported, meaning that both markdown plugins and SVG renders can be used.
108

119
<%- await include(`partials/rss.ejs`) %>
1210

0 commit comments

Comments
 (0)