Changing the logo and icons¶
When installing Material for MkDocs, you immediately get access to over 7.000 icons ready to be used for customization of specific parts of the theme and/or when writing your documentation in Markdown. Not enough? You can also add additional icons with minimal effort.
The logo can be changed to a user-provided image (any type, incl.
*.svg) located in the
docs folder, or to any icon bundled with the theme. Add the following lines to
theme: logo: assets/logo.png
theme: icon: logo: material/library
Normally, the logo in the header and sidebar links to the homepage of the documentation, which is the same as
site_url. This behavior can be changed with the following configuration:
extra: homepage: https://example.com
Source · Default:
The favicon can be changed to a path pointing to a user-provided image, which must be located in the
docs folder. It can be set via
theme: favicon: images/favicon.png
markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg
The following icon sets are bundled with Material for MkDocs:
If you want to add additional icons, read on.
Source · Difficulty: easy
In order to add additional icons, extend the theme, and create a folder named
.icons in the
custom_dir you want to use for overrides. Next, add your
*.svg icons into a subfolder of the
.icons folder. Let's say you downloaded and unpacked the Bootstrap icon set, and want to add it to your project documentation. The structure of your project should look like this:
. ├─ overrides/ │ └─ .icons/ │ └─ bootstrap/ │ └─ *.svg └─ mkdocs.yml
Then, add the following lines to
markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg options: custom_icons: - overrides/.icons
You should now be able to use the Bootstrap icons.