How do I replicate the 'conventions' icons used in the Material-for-mkdocs documentation site?

[rathboma]

Hi everyone,

First, wow is this an amazing project. The docs produced are fantastic.

Quick question - I'd like to replicate the icons used in the project documentation, like these:

I can see in the code that they use this block to achieve this:

<!-- md:version 9.2.0 -->
<!-- md:plugin -->
<!-- md:flag experimental -->

I can't figure out if this is a built in feature? How would I achieve the same thing?

Thanks anyone for your help!

[kamilkrzyskow]

Hello @rathboma,
this was asked many times in different ways in the discussions, searching with conventions I got to this discussion:

• what it is? #6045

To answer in short again:

0. This is currently a custom feature of the mkdocs-material docs, and isn't exported in a straightforward way for other users to use. However, this will likely change, as people often ask for it.
1. The <!-- md:plugin --> tokens/identifiers/shortcodes are processed by the shortcodes hook:
   https://github.com/squidfunk/mkdocs-material/blob/master/src/overrides/hooks/shortcodes.py
2. The hook replaces the shortcodes with a Markdown structure
3. The HTML is styled additionally with a custom CSS (mkdocs-material uses SCSS, which is later compiled and minified):
   

   mkdocs-material/src/overrides/assets/stylesheets/custom/_typeset.scss

   Line 97 in 175df61

   .mdx-badge {

To enable the hook, you need to add it to the mkdocs.yml file, as described here:
https://www.mkdocs.org/user-guide/configuration/#hooks

[rathboma]

Thanks for the response!

[squidfunk]

In the future, we'll evaluate whether we can somehow generalize the shortcodes, but for now, copying and adapting our hook is the best solution. Please understand that we must prioritize what we work on, and our current focus is tags, projects and search. However, we're planning to do a face lift in 2024 and make Material for MkDocs even more easily customizable.