With Material 5.0, it is now possible to customize the icons used in the documentation with
.svg icons. It ships three icon sets, providing over 5k icons:
However, you can add your own custom icons or third party icon sets to your documentation.
Because icons are directly inlined into the html, they must be in the
.svg vector format. If you have a bitmap (e.g.
.png), you will need to trace them using inkscape or similar tools so that they can be converted to a
With this tutorial, we will add Bootstrap Icons, a ready-to-use icon set. These icons will be used to customize the icons available in within
theme.icon and the social icons
extra.social.icon. Furthermore, we will configure Material to access these icons from within any markdown file.
All icons provided by Material are placed within the
.icons folder. Each icon set provided is placed within its own sub-folder to avoid naming conflicts for the same icon name. They are accessible using the relative file name (without extension):
In order to add the Bootstrap Icons, we will need to extend the theme to gain access to your
.icons folder. For that, we create an folder
theme (or any other name) within the project root and specify it as
theme: name: material custom_dir: theme
Theme extension may be used for the following use cases:
- Overwrite assets locally provided by Material by specifying the exact relative file name (e.g.
- Add custom assets to be discoverable by Material.
When adding custom assets, please make sure that you do not accidentally overwrite other assets of Material by choosing a unique name for them. A list of provided assets can be found here.
In order to avoid accidentally overwriting any provided icons, it is recommended to create a unique folder (e.g.
bootstrap) and place it in the
theme/.icons folder, so that Material can find the icons.
A fully functional project structure should look like this:
docs index.md theme .icons bootstrap *.svg mkdocs.yml
Embed Icon Sets in Markdown (optional)¶
To allow Material to access the icons for markdown files, we will use the pymdownx.emoji extension with a custom icon index.
The extension will pick up the provided icon sets on its own. However, since the extension does not have access to your MkDocs environment, it cannot read your customized icons directly. If you have custom icons set specified, please refer to the "Custom Icon Set" tab below.
markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg
markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg # Specify the relative path to your theme/.icons folder options: custom_icons: - theme/.icons
Some YAML linters display an error when specifying these python functions in the YAML file. Please do not escape them, because then MKDocs will throw an error when building.
You can find all provided icons here. For easy reference, please refer to the official links to the icon sets.
You can now place any
.svg icon within your folder
theme/.icons/bootstrap to make them accessible (e.g. copy over all downloaded Bootstrap Icons). They are referenced similar to the provided icon sets.
theme: name: material custom_dir: theme icon: logo: bootstrap/bootstrap repo: bootstrap/archive extra: social: - icon: bootstrap/bootstrap-fill link: https://getbootstrap.com/
If you configured Material to embed icons in Markdown, you can simply specify the icon by its path, separated by hyphens:
bootstrap/circle-square.svg would become
- – Material Design icons
- – FontAwesome icons
- – GitHub's Octicons
- - Custom Icons
* :material-account-circle: – Material Design icons * :fontawesome-regular-laugh-wink: – FontAwesome icons * :octicons-octoface: – GitHub's Octicons * :bootstrap-circle-square: - Custom Icons