Skip to content

Mkdocs & Material Mkdocs extensions

Here some notes about the material Mkdocs extensions more information in the documentation

Icons

To add custom Icons we need to use Icons+Emojis We star with the configuration that give use access to some basic icons and emojies, later we explore the addition of customized icons.

Configuration

add the following lines to mkdocs.yml 

1
2
3
4
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

emojis 😄

it is recommended to use the shortcodes at Emojipedia we have the example of 

1
:smile:
😄

Using icons

We can use icons too, in some case we need to make some extra modifications to the mkdocs.yml 

1
2
3
4
5
6
7
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons
and in the root directory next to mkdocs.yml we create a new folder called overrides and inside other call .icons and inside we put the svg of the icons.

Now to call that icons we replace the / of the path for - like 

1
:faces-guy-fawkes-mask:

We can find more icons here materialdesignicons

Color can be added to the icons, we will need to add some CSS rules to later reference next to the icon, like this 

1
2
3
.purple{
    color: #512DA8;
}

1
:faces-panda:{ .purple }

colors for icons

.purple: #6745c2 .dark-purple: #6745c2 .royal-blue: #000062 .orange: #E66C10 .light-green: #629749 .dark-green: #003d00 .green: #32681

Admonitions

These are basically call-outs.

Configuration

1
2
markdown_extensions:
  - admonition

They are enabled by putting !!! later a key word and bellow indented the content, like this

1
2
!!!note
    this is an admonition

Note

this is an admonition

We can modify the name by putting a different key word ( see admonitions documentation) or by adding the title in ".

1
2
!!!note "this is the title"
    this is an admonition

This is the title

this is an admonition

we can make a dropdown close by default

1
2
???note "This is az dropdown admonition"
    this is an admonition
This is a dropdown admonition

this is an admonition

and open by adding "+"

1
2
???+ note "This is a dropdown call-out"
    this is an admonition
This is a dropdown call-out

this is an admonition

Here some example of other admonitions

1
2
!!! warning
    This is a warning

Warning

This is a warning

Definition List

Footnotes

Metadata

pymdownx.details

attr_list

smarty

md_in_html