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.

Configuration¶

Logo¶

Source · Default: material/library

There're two ways to specify a logo: it must be a valid path to any icon bundled with the theme, or to a user-provided image located in the docs folder. Both can be set via mkdocs.yml:

theme:
  icon:
    logo: material/library

theme:
  logo: assets/logo.png

Favicon¶

Source · Default: assets/images/favicon.png

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 mkdocs.yml:

theme:
  favicon: images/favicon.png

Icons¶

Source · Extension

The Emoji extension, which is part of Python Markdown Extensions, adds the ability to integrate icons in the *.svg file format, which are inlined when building your site:

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:

• – Material Design
• :fontawesome-brands-font-awesome-flag: – FontAwesome
• – Octicons

If you want to add additional icons, read on.

Customization¶

Additional icons¶

Source · Difficulty: moderate

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 mkdocs.yml:

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.