mkdocs-badges

License
Python versions

This package allows you to add badges to your MkDocs site.

Note on Zensical, MkDocs 1.x, ProperDocs, etc

To make it easy to keep it up to date for all my plugins, I hosted my intentions of what platforms to support on my website.

For this plugin there is a standalone Markdown preprocessor, that you can execute before using any Markdown based static site generator.

Documentation

This README is just a short intro to the package.
For a quick start and detailed information please see the documentation.
The documentation is also available in the docs folder of the source code and can be built locally with MkDocs.

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:

poetry install && poetry run mkdocs serve -t <theme>

Themes that should work are mkdocs, readthedocs, and material.

Lint source code:

poetry run mypy

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):

poetry install && poetry run 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.6.0

Removed dependency declaration of mkdocs
Added standalone preprocessor markdown-badges-standalone for non-MkDocs site generators (Zensical, etc)

Version 0.5.2

Fix warning on Python 3.14 (thanks @dstam)

Version 0.5.1

Parse lines starting with whitespace (lists, admonitions, etc.), which were previously ignored.
This may cause issues if you use indented code blocks, since any badges in them will be replaced and visible as HTML code.
To fix this I recommend you use a fenced code block (using triple backticks).
You can also revert to the old behavior by setting the new option ignore_lines_starting_with_whitespace to true.
Migrated build process to poetry
Fixed unit tests

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 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
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
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

Package profile

mkdocs-badges

Dependencies

Details

Package description

Package profile

mkdocs-badges

Releases

Release table

PyPI Downloads

Dependencies

Details

Package description

Releases

Release table

PyPI Downloads