Skip to content

Icon Sets

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:

  1. Material Design icons
  2. FontAwesome icons
  3. GitHub's Octicons

However, you can add your own custom icons or third party icon sets to your documentation.

Tip

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 .svg format.

Goal

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 mkdocs.yml, namely theme.icon and the social icons extra.social.icon. Furthermore, we will configure Material to access these icons from within any markdown file.

Setup

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): fontawesome/brands/github.

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 custom_dir.

theme:
    name: material
    custom_dir: theme

Warning

Theme extension may be used for the following use cases:

  1. Overwrite assets locally provided by Material by specifying the exact relative file name (e.g. .icons/logo.svg).
  2. 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

Warning

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.

Usage

Tip

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 :bootstrap-circle-square:.

Example

  • – 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