sudacode/metrics
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(templates/community): rewrite documentation

Browse Source
This commit is contained in:
lowlighter
2022-01-14 22:10:04 -05:00
parent 2d6c9e16d6
commit 7228fc3b6d
3 changed files with 71 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
source/templates/community/README.md
View File

@@ -1,25 +1,62 @@
### 📕 Community templates
<table>
<tr><th colspan="2"><h3>📕 Community templates</h3></th></tr>
<tr><td colspan="2" align="center">A template capable of rendering markdown from a given template file.</td></tr>
<tr>
<td colspan="2" align="center">
<img src="https://github.com/lowlighter/lowlighter/blob/master/metrics.markdown.png" alt=""></img>
<img width="900" height="1" alt="">
</td>
</tr>
</table>
It is possible to use official releases with templates from forked repositories (whether you own them or not).
___
Use `setup_community_templates` option to specify additional external sources using following format: `user/repo@branch:template`.
Templates added this way will be downloaded through git and can be used by prefixing their name with an `@`.
Community templates are a way to use official releases of [lowlighter/metrics](https://github.com/lowlighter/metrics) while using templates from external repositories (owned or not).
By default, community templates use `template.mjs` from official `classic` template instead of their own, to prevent executing malicious code and avoid token leaks.
## 📮 Using community templates
If you trust it, append `+trust` after their name.
```yaml
- uses: lowlighter/metrics@latest
with:
# ... other options
template: "@super-metrics"
# Download "super-metrics" and "trusted-metrics" templates from "octocat/metrics@master"
# "@trusted-metrics" template can execute remote JavaScript code
setup_community_templates: octocat/metrics@master:super-metrics, octocat/metrics@master:trusted-metrics+trust
Use `setup_community_templates` option to specify additional external sources using following format:
```
user/repo@branch:template
```
To create a new community template, fork this repository and create a new folder in `/source/templates` with same structure as current templates.
Then, it's just as simple as HTML and CSS with a bit of JavaScript!
These templates will be downloaded through git and will be usable by prefixing their name with an `@`.
If you made something awesome, please share it here!
*Example: using `my-theme` template by downloading it from `user/repo`*
```yml
- uses: lowlighter/metrics@latest
with:
template: "@my-theme"
setup_community_templates: "user/repo@main:my-theme"
```
For security reasons, community templates will use the `classic` template `template.mjs` instead of their own.
If you trust a community template, append `+trust` to it.
*Example: using and trusting `my-theme` template by downloading it from `user/repo`*
```yml
- uses: lowlighter/metrics@latest
with:
template: "@my-theme"
setup_community_templates: "user/repo@main:my-theme+trust"
```
> ⚠️ Note that it basically allow remote code execution and the template may have access to **sensitive data** along with **tokens**! Use this feature only from a trusted source. Remember that its content may also change at any time...
## 📪 Creating community templates
To create a new template, start a new repository and create a new folder in `/source/templates` with the same file structure as in [lowlighter/metrics](https://github.com/lowlighter/metrics) templates:
* `/source/templates`
* `{template-name}`
* `README.md`,
* `metadata.yml`,
* `image.svg`
* `partials/`
* `_.json`
* `*.ejs`
Then use HTML, CSS, and [EJS](https://github.com/mde/ejs) to create something awesome!
Do not hesitate to share it on [GitHub discussions](https://github.com/lowlighter/metrics/discussions)!
For more information, see [contribution guide](/CONTRIBUTING.md).