diff --git a/source/templates/community/README.md b/source/templates/community/README.md index af9e6c59..68651c41 100644 --- a/source/templates/community/README.md +++ b/source/templates/community/README.md @@ -54,24 +54,6 @@ Some templates may accept additional custom parameters that can be passed throug } ``` -## 📪 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). - ## ℹ️ Examples workflows @@ -93,4 +75,158 @@ with: setup_community_templates: lowlighter/metrics@master:terminal+trust ``` - \ No newline at end of file + + +## 📪 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 + +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