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 detailed information please see the documentation. The documentation is also available in the docs folder of the source code and can be built localy with MkDocs.

Setup

Install the plugin using pip:

pip install mkdocs-badges

Then, add the plugin to your mkdocs.yml:

plugins:
  - search
  - badges

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

More information about plugins in the MkDocs documentation.

Usage

Badges are defined like this:

|@github:six-two/mkdocs-badges|
|"Height":1.58m|
|t:Password|c:Tr0ub4dor&3|v:Tr0ub4dor&3|l:https://xkcd.com/936/|end

This should create badges that look like this (actual colors will depend on your theme):

There are different types of badges.

Normal badges

Normal badges use the syntax |"Name":value|. They just render a badge, but do not react to clicks. If you want to link to something, you can put the badge in a link like this:

[|"Github":mkdocs-badges|](q)

Install badges

Install badges can be used to tell users how to install software. They are defined like this:

|@github:six-two/mkdocs-badges|

Clicking on the badge name Github will copy the command used to install the software (git clone https://github.com/six-two/mkdocs-badges). Clicking on the badge's value six-two/mkdocs-badges will bring the user to the package's site (https://github.com/six-two/mkdocs-badges).

The currently supported badge names can be seen in src/mkdocs_badges/assets/install_badge_data.json. You can define also your own badge data and use the install_badge_data setting to use it as your data file.

Custom badges

Custom badges allow users to use the features from install badges (such as copying text on click) for their own custom badges.

They have the following structure:

|t:Badge type|c:Text to copy on click|v:Value to show|l:Link to follow when the badge is clicked|end

Some of the fields are optional, but they need to be supplied in the correct order:

|t:Badge with|v:example link|https://example.com|end
|t:Normal|v:badge|end

See the following table for more details:

Configuration

Notable changes

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