[](https://pypi.org/project/foliantcontrib.badges/) [](https://github.com/foliant-docs/foliantcontrib.badges)
# Badges
Preprocessor for Foliant which helps to add badges to your documents. It uses [Shields.io](https://shields.io) to generate badges.
# Installation
```bash
$ pip install foliantcontrib.badges
```
# Config
To enable the preprocessor, add `badges` to `preprocessors` section in the project config:
```yaml
preprocessors:
- badges
```
The preprocessor has a number of options:
```yaml
preprocessors:
- badges:
server: 'https://img.shields.io'
as_object: true
add_link: true
vars:
jira_path: localhost:3000/jira
package: foliant
# badge look parameters
style: flat-square
logo: jira
```
`server`
: Shields server URL, which hosts badges. default: `https://img.shields.io`
`as_object`
: If `true` — preprocessor inserts `svg` badges with HTML `<object>` tag, instead of Markdown image tag. This is required for links and hints to work. default: `true`
`add_link`
: If `true` preprocessor tries to determine the link which should be added to badge (for example, link to jira issue page for jira issue badge). Only works with `as_object = true`. default: `true`
> Please note that right now only links for **pypi** and **jira-issue** badges are being added automatically. Please contribute or contact author for adding other services.
`vars`
: Dictionary with variables which will be replaced in badge urls. See **variables** section.
Also you may add parameters specified on the shields.io website which alter the badge view like: `label`, `logo`, `style` etc.
# Usage
Just add the `badge` tag and specify path to badge in the tag body:
```
<badge>jira/issue/https/issues.apache.org/jira/kafka-2896.svg</badge>
```
All options from config may be overriden in tag parameters:
```
<badge style="social" as_object="false">jira/issue/https/issues.apache.org/jira/kafka-2896.svg</badge>
```
## Variables
You can use variables in your badges to replace parts which repeat often. For example, if we need to add many badges to our Jira tracker, we may put the protocol and host parameters into a variable like this:
```yaml
preprocessors:
- badges:
vars:
jira: https/issues.apache.org/jira
```
To reference a variable in a badge path use syntax `${variable}`:
```
<badge>jira/issue/${jira}/kafka-2896.svg</badge>
Description of the issue goes here. But it's not the only one.
<badge>jira/issue/${jira}/KAFKA-7951.svg</badge>
Description of the second issue.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/foliant-docs/foliantcontrib.badges",
"name": "foliantcontrib.badges",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Daniil Minukhin",
"author_email": "ddddsa@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/81/5c/6cf120c60e85e11a1b7fa4d3b4c4218a10852397d8e590cf45a0887cb104/foliantcontrib.badges-1.0.4.tar.gz",
"platform": "any",
"description": "[](https://pypi.org/project/foliantcontrib.badges/) [](https://github.com/foliant-docs/foliantcontrib.badges)\n\n# Badges\n\nPreprocessor for Foliant which helps to add badges to your documents. It uses [Shields.io](https://shields.io) to generate badges.\n\n# Installation\n\n```bash\n$ pip install foliantcontrib.badges\n```\n\n# Config\n\nTo enable the preprocessor, add `badges` to `preprocessors` section in the project config:\n\n```yaml\npreprocessors:\n - badges\n```\n\nThe preprocessor has a number of options:\n\n```yaml\npreprocessors:\n - badges:\n server: 'https://img.shields.io'\n as_object: true\n add_link: true\n vars:\n jira_path: localhost:3000/jira\n package: foliant\n # badge look parameters\n style: flat-square\n logo: jira\n```\n\n`server`\n: Shields server URL, which hosts badges. default: `https://img.shields.io`\n\n`as_object`\n: If `true` \u2014 preprocessor inserts `svg` badges with HTML `<object>` tag, instead of Markdown image tag. This is required for links and hints to work. default: `true`\n\n`add_link`\n: If `true` preprocessor tries to determine the link which should be added to badge (for example, link to jira issue page for jira issue badge). Only works with `as_object = true`. default: `true`\n\n> Please note that right now only links for **pypi** and **jira-issue** badges are being added automatically. Please contribute or contact author for adding other services.\n\n`vars`\n: Dictionary with variables which will be replaced in badge urls. See **variables** section.\n\nAlso you may add parameters specified on the shields.io website which alter the badge view like: `label`, `logo`, `style` etc.\n\n# Usage\n\nJust add the `badge` tag and specify path to badge in the tag body:\n\n```\n<badge>jira/issue/https/issues.apache.org/jira/kafka-2896.svg</badge>\n```\n\nAll options from config may be overriden in tag parameters:\n\n```\n<badge style=\"social\" as_object=\"false\">jira/issue/https/issues.apache.org/jira/kafka-2896.svg</badge>\n```\n\n## Variables\n\nYou can use variables in your badges to replace parts which repeat often. For example, if we need to add many badges to our Jira tracker, we may put the protocol and host parameters into a variable like this:\n\n```yaml\npreprocessors:\n - badges:\n vars:\n jira: https/issues.apache.org/jira\n```\n\nTo reference a variable in a badge path use syntax `${variable}`:\n\n```\n<badge>jira/issue/${jira}/kafka-2896.svg</badge>\n\nDescription of the issue goes here. But it's not the only one.\n\n<badge>jira/issue/${jira}/KAFKA-7951.svg</badge>\n\nDescription of the second issue.\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Badges for Foliant.",
"version": "1.0.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "493fd531cda8fc167175c79de7f348439d663da44923f33ed14fcd3855f98cc3",
"md5": "0c41a0284743523be69cbdad24923488",
"sha256": "048eba635374879957d2ba24a6ceac356fff14178605fa3f5fec71adc5d91643"
},
"downloads": -1,
"filename": "foliantcontrib.badges-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c41a0284743523be69cbdad24923488",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5276,
"upload_time": "2023-01-25T10:45:34",
"upload_time_iso_8601": "2023-01-25T10:45:34.036085Z",
"url": "https://files.pythonhosted.org/packages/49/3f/d531cda8fc167175c79de7f348439d663da44923f33ed14fcd3855f98cc3/foliantcontrib.badges-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "815c6cf120c60e85e11a1b7fa4d3b4c4218a10852397d8e590cf45a0887cb104",
"md5": "644c6450a12d9439e9acd7e9ac6239d7",
"sha256": "96b0e408a5effe0291569b4cbc12625385a272a037ffbc13039464d505600751"
},
"downloads": -1,
"filename": "foliantcontrib.badges-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "644c6450a12d9439e9acd7e9ac6239d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5013,
"upload_time": "2023-01-25T10:45:35",
"upload_time_iso_8601": "2023-01-25T10:45:35.308916Z",
"url": "https://files.pythonhosted.org/packages/81/5c/6cf120c60e85e11a1b7fa4d3b4c4218a10852397d8e590cf45a0887cb104/foliantcontrib.badges-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-25 10:45:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "foliant-docs",
"github_project": "foliantcontrib.badges",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "foliantcontrib.badges"
}
JSON
