📕 Community templates

A template capable of rendering markdown from a given template file.
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). ## 📮 Using community templates Use `setup_community_templates` option to specify additional external sources using following format: ``` user/repo@branch:template ``` These templates will be downloaded through git and will be usable by prefixing their name with an `@`. *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... Some templates may accept additional custom parameters that can be passed through the `query` option, using a JSON formatted string. *Example: using and trusting `my-theme` template by downloading it from `user/repo`* ```yaml - uses: lowlighter/metrics@latest with: template: "@my-theme" query: | { "header_color": "#FF0000" } ``` ## ℹī¸ Examples workflows ```yaml name: Using a community template uses: lowlighter/metrics@latest with: token: ${{ secrets.METRICS_TOKEN }} template: "@classic" setup_community_templates: lowlighter/metrics@master:classic ``` ```yaml name: Using a trusted community template uses: lowlighter/metrics@latest with: token: ${{ secrets.METRICS_TOKEN }} template: "@terminal" setup_community_templates: lowlighter/metrics@master:terminal+trust ``` ``` ### đŸ’Ŧ Creating partials Just create a new `.ejs` file in `partials` folder, and reference it into `partials/_.json`. It should be able to handle gracefully plugins state and errors. Below is a minimal snippet of a partial: ```ejs <% if (plugins.gists) { %> <% if (plugins.gists.error) { %> <%= plugins.gists.error.message %> <% } else { %> <%# content %> <% } %> <% } %> ``` Partials should have the match the same name as plugin handles, as they're used to display plugin compatibility in auto-generated header. ### đŸ’Ŧ Adding custom fonts > ⚠ī¸ This significantly increases rendered metrics filesize and thus not recommended. You should restrict charset when using this feature Here's a quick step-by-step tutorial to create base64 encoded fonts: - 1. Find a font on [fonts.google.com](https://fonts.google.com) - Select regular, bold, italic and bold+italic fonts - Open `embed` tab and extract `href` - 2. Open extracted `href` in a browser and append `&text=` parameter with list of used characters - e.g. `&text=0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz` - 3. Download each font file from urls present in generated stylesheet - 4. Convert them into base64 with `woff` format on [transfonter.org](https://transfonter.org) - 5. Download archive and extract it - 6. Copy content of generated stylesheet to `fonts.css` - 7. Update `style.css` to use the new font