# mkdocs-badges
[](https://pypi.org/project/mkdocs-badges/)
This package allows you to add badges to your MkDocs site.
## Documentation
This README is just a short intro to the package.
For a quick start and detailed information please see the [documentation](https://mkdocs-badges.six-two.dev/).
The documentation is also available in the `docs` folder of the source code and can be built locally with [MkDocs](https://www.mkdocs.org/).
A development version built with the latest changes (`HEAD` commit) can be found at <https://mkdocs-badges-dev.six-two.dev/>.
## Testing
The documentation also serves as a test of the plugin, especially the files under the `Tests` menu item.
Build the documentation with the latest source code:
```bash
pip install . && mkdocs serve -t <theme>
```
Themes that should work are `mkdocs`, `readthedocs`, and `material`.
### Unit tests
The GitHub repository now contains some unit test.
You can run them against the current code with the following command (issued in the root directory of the repository):
```bash
pip install . && python -m unittest
```
## Known issues
- At least on iPhones (which only support Safari based engines) only one toast can be shown.
After that you need to reload the page to show the same toast again or to show another toast.
This seems to be an issue with <https://github.com/mlcheng/js-toast/> (used in `src/mkdocs_badges/assets/badge.js`) which seems no longer maintained.
## Notable changes
### Version 0.5.0
- Allow inline badges by surrounding them with `[` and `]`.
These values can be changed with the new settings `inline_badge_start` and `inline_badge_end` in your `mkdocs.yml`
- Added `winget` install badge data
- Added some sanity checks when parsing badge data
- Fix `pip_github` and `pip_gitlab` install badges
### Version 0.4.5
- Allow setting a custom separator with `separator` in your `mkdocs.yml`
- Allow specifying badges in tables.
This uses a different separator (by default `^`), which you can set using `table_separator` in your `mkdocs.yml`
- Fixed some CSS bugs
- Link badges (L) with non-URL values now cause a warning (instead of a crash)
- Allow adding optional angle brackets in link badges (L) to prevent [MD034 - Bare URL used](https://github.com/DavidAnson/markdownlint/blob/main/doc/md034.md) linter warnings
### Version 0.4.4
- Rewrite `-` to `_` in install badge types.
This allows using both `brew-formula` and `brew_formula` notation.
### Version 0.4.3
- Changed behavior of the `install_badge_data` option.
Instead of removing the defaults the specified file is merged with them
- Changed install badge data.
Renamed `brew` to `brew_formula` and added `brew_cask`, `docker_hub`, and `docker_ghcr`
- Fixed crash of JavaScript copy code if the text contains a single quote
### Version 0.4.2
- Detect markdown tables even if they have only a single dash in the header. Fixes [#4](https://github.com/six-two/mkdocs-badges/issues/4)
- Option to disable warnings (use this at your own risk) by adding `disable_warnings: True` to the plugin config in your `mkdocs.yml`
### Version 0.4.1
- Now requires MkDocs 1.5 or newer
- The included script is now marked as `async` by default, maybe improving loading times a tiny bit. This can be disabled by adding `async: False` to the plugin config in your `mkdocs.yml`
### Version 0.4.0
- Now requires MkDocs 1.4 or newer
- Updated the layout rules for badges. This should better handle oversized contents (like images or very long texts).
### Version 0.3.4
- Added single element badges
### Version 0.3.3
- Added tags badges
### Version 0.3.1
- Better error handling, fixed a crash
- Started adding unit tests
### Version 0.3.0
- Breaking changes to the badges formats. See the [migration guide](https://mkdocs-badges.six-two.dev/migration/)
- Added support for reference links
### Version 0.2.0
- Each badge now needs to be the only thing on its line
- Badges inside code blocks are no longer parsed
- The `|end` at the end of custom badges is no longer neccessary. A simple `|` is enough. This shorter form is recommended from now on.
- Documentation is now in the `docs` folder in the form of a mkdocs website
- Added link badges
Raw data
{
"_id": null,
"home_page": "https://github.com/six-two/mkdocs-badges",
"name": "mkdocs-badges",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "six-two",
"author_email": "pip@six-two.dev",
"download_url": "https://files.pythonhosted.org/packages/57/8b/213b273df9bae458b358c529744246b931d584de1f9c491b3dcfe7123d90/mkdocs_badges-0.5.0.tar.gz",
"platform": null,
"description": "# mkdocs-badges\n[](https://pypi.org/project/mkdocs-badges/)\n\n\n\nThis package allows you to add badges to your MkDocs site.\n\n## Documentation\n\nThis README is just a short intro to the package.\nFor a quick start and detailed information please see the [documentation](https://mkdocs-badges.six-two.dev/).\nThe documentation is also available in the `docs` folder of the source code and can be built locally with [MkDocs](https://www.mkdocs.org/).\n\nA development version built with the latest changes (`HEAD` commit) can be found at <https://mkdocs-badges-dev.six-two.dev/>.\n\n## Testing\n\nThe documentation also serves as a test of the plugin, especially the files under the `Tests` menu item.\n\nBuild the documentation with the latest source code:\n```bash\npip install . && mkdocs serve -t <theme>\n```\n\nThemes that should work are `mkdocs`, `readthedocs`, and `material`.\n\n### Unit tests\n\nThe GitHub repository now contains some unit test.\nYou can run them against the current code with the following command (issued in the root directory of the repository):\n\n```bash\npip install . && python -m unittest\n```\n\n## Known issues\n\n- At least on iPhones (which only support Safari based engines) only one toast can be shown.\n After that you need to reload the page to show the same toast again or to show another toast.\n This seems to be an issue with <https://github.com/mlcheng/js-toast/> (used in `src/mkdocs_badges/assets/badge.js`) which seems no longer maintained.\n\n## Notable changes\n\n### Version 0.5.0\n\n- Allow inline badges by surrounding them with `[` and `]`.\n These values can be changed with the new settings `inline_badge_start` and `inline_badge_end` in your `mkdocs.yml`\n- Added `winget` install badge data\n- Added some sanity checks when parsing badge data\n- Fix `pip_github` and `pip_gitlab` install badges\n\n### Version 0.4.5\n\n- Allow setting a custom separator with `separator` in your `mkdocs.yml`\n- Allow specifying badges in tables.\n This uses a different separator (by default `^`), which you can set using `table_separator` in your `mkdocs.yml`\n- Fixed some CSS bugs\n- Link badges (L) with non-URL values now cause a warning (instead of a crash)\n- Allow adding optional angle brackets in link badges (L) to prevent [MD034 - Bare URL used](https://github.com/DavidAnson/markdownlint/blob/main/doc/md034.md) linter warnings\n\n### Version 0.4.4\n\n- Rewrite `-` to `_` in install badge types.\n This allows using both `brew-formula` and `brew_formula` notation.\n\n### Version 0.4.3\n\n- Changed behavior of the `install_badge_data` option.\n Instead of removing the defaults the specified file is merged with them\n- Changed install badge data.\n Renamed `brew` to `brew_formula` and added `brew_cask`, `docker_hub`, and `docker_ghcr`\n- Fixed crash of JavaScript copy code if the text contains a single quote\n\n### Version 0.4.2\n\n- Detect markdown tables even if they have only a single dash in the header. Fixes [#4](https://github.com/six-two/mkdocs-badges/issues/4)\n- Option to disable warnings (use this at your own risk) by adding `disable_warnings: True` to the plugin config in your `mkdocs.yml`\n\n### Version 0.4.1\n\n- Now requires MkDocs 1.5 or newer\n- The included script is now marked as `async` by default, maybe improving loading times a tiny bit. This can be disabled by adding `async: False` to the plugin config in your `mkdocs.yml`\n\n### Version 0.4.0\n\n- Now requires MkDocs 1.4 or newer\n- Updated the layout rules for badges. This should better handle oversized contents (like images or very long texts).\n\n### Version 0.3.4\n\n- Added single element badges\n\n### Version 0.3.3\n\n- Added tags badges\n\n### Version 0.3.1\n\n- Better error handling, fixed a crash\n- Started adding unit tests\n\n### Version 0.3.0\n\n- Breaking changes to the badges formats. See the [migration guide](https://mkdocs-badges.six-two.dev/migration/)\n- Added support for reference links\n\n### Version 0.2.0\n\n- Each badge now needs to be the only thing on its line\n- Badges inside code blocks are no longer parsed\n- The `|end` at the end of custom badges is no longer neccessary. A simple `|` is enough. This shorter form is recommended from now on.\n- Documentation is now in the `docs` folder in the form of a mkdocs website\n- Added link badges\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Add badges to your MkDocs page",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/six-two/mkdocs-badges"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d3930bd75d80a78d1c6687cda4c173f6a94d075b2a48f43b3bcb9f879fbab715",
"md5": "ab5f5141b59ab248f0a98a1204aaadc3",
"sha256": "3dd82e4054fa7f79fed30aa9d7a5c08b76ad0ced7d00a163f47ac91dd1dc3614"
},
"downloads": -1,
"filename": "mkdocs_badges-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab5f5141b59ab248f0a98a1204aaadc3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21900,
"upload_time": "2025-08-24T16:50:54",
"upload_time_iso_8601": "2025-08-24T16:50:54.343736Z",
"url": "https://files.pythonhosted.org/packages/d3/93/0bd75d80a78d1c6687cda4c173f6a94d075b2a48f43b3bcb9f879fbab715/mkdocs_badges-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "578b213b273df9bae458b358c529744246b931d584de1f9c491b3dcfe7123d90",
"md5": "450111ead0f1286211182b2df6cf6771",
"sha256": "68e119406a8709fc89a8a4129545ff5d7935fee965d8cc11b73db649be8880de"
},
"downloads": -1,
"filename": "mkdocs_badges-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "450111ead0f1286211182b2df6cf6771",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20665,
"upload_time": "2025-08-24T16:50:55",
"upload_time_iso_8601": "2025-08-24T16:50:55.287479Z",
"url": "https://files.pythonhosted.org/packages/57/8b/213b273df9bae458b358c529744246b931d584de1f9c491b3dcfe7123d90/mkdocs_badges-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 16:50:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "six-two",
"github_project": "mkdocs-badges",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "babel",
"specs": [
[
"==",
"2.17.0"
]
]
},
{
"name": "backrefs",
"specs": [
[
"==",
"5.8"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.1.31"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.1"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.8"
]
]
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "ghp-import",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "importlib-metadata",
"specs": [
[
"==",
"8.6.1"
]
]
},
{
"name": "jinja2",
"specs": [
[
"==",
"3.1.6"
]
]
},
{
"name": "markdown",
"specs": [
[
"==",
"3.8"
]
]
},
{
"name": "markupsafe",
"specs": [
[
"==",
"3.0.2"
]
]
},
{
"name": "mergedeep",
"specs": [
[
"==",
"1.3.4"
]
]
},
{
"name": "mkdocs",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "mkdocs-get-deps",
"specs": [
[
"==",
"0.2.0"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"9.6.11"
]
]
},
{
"name": "mkdocs-material-extensions",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.2"
]
]
},
{
"name": "paginate",
"specs": [
[
"==",
"0.5.7"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.3.7"
]
]
},
{
"name": "pygments",
"specs": [
[
"==",
"2.19.1"
]
]
},
{
"name": "pymdown-extensions",
"specs": [
[
"==",
"10.14.3"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "pyyaml-env-tag",
"specs": [
[
"==",
"0.1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.17.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "watchdog",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "zipp",
"specs": [
[
"==",
"3.21.0"
]
]
}
],
"lcname": "mkdocs-badges"
}
JSON
