Icons + Emojis¶

One of the best features of Material for MkDocs is the possibility to use more than 7.000 icons and thousands of emojis in your project documentation with practically zero additional effort. Furthermore, custom icons can be added and used in mkdocs.yml, documents and templates.

Configuration¶

Emoji¶

Source · Extension

The Emoji extension, which is part of Python Markdown Extensions, adds the ability to integrate emojis and 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

You can also add additional icons. When using emojis, it's recommended to consult the official documentation of Python Markdown Extensions to learn about configuration options.

Attribute List¶

The Attribute List extension, which is part of the standard Markdown library, allows to add HTML attributes and CSS classes to Markdown elements, and can be enabled via mkdocs.yml

markdown_extensions:
  - attr_list

Usage¶

Using emojis¶

Emojis can be integrated in Markdown by putting the shortcode of the emoji between two colons. If you're using Twemoji (recommended), you can look up the shortcodes at Emojipedia.

Example:

:smile: 

Result:

Using icons¶

When Emoji is enabled, icons can be used similar to emojis, by referencing a valid path to any icon bundled with the theme, which are located in the .icons directory, and replacing / with -:

Example:

- :material-account-circle: – `.icons/material/account-circle.svg`
- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
- :octicons-octoface-16: – `.icons/octicons/octoface-16.svg`

Result:

• – .icons/material/account-circle.svg
• :fontawesome-regular-laugh-wink: – .icons/fontawesome/regular/laugh-wink.svg
• :octicons-octoface-16: – .icons/octicons/octoface-16.svg

with colors¶

When the Attribute List extension is enabled, custom CSS classes and attributes can be added to icons by suffixing the icon with a special syntax. While HTML and CSS allow to use inline styles, it's always best to add an additional stylesheet and put styles into dedicated CSS classes:

.medium {
  color: #00AB6C;
}
.twitter {
  color: #1DA1F2;
}
.facebook {
  color: #4267B2;
}

Then, simply add the CSS class to the icon.

Example:

- :fontawesome-brands-medium:{: .medium } – Medium
- :fontawesome-brands-twitter:{: .twitter } – Twitter
- :fontawesome-brands-facebook:{: .facebook } – Facebook

Result:

• – Medium
• – Twitter
• – Facebook

with animations¶

Similar to adding colors, it's just as easy to add CSS animations to icons by using an additional stylesheet, defining a @keyframes rule and adding the dedicated CSS class to the icon:

@keyframes heart {
  0%, 40%, 80%, 100% {
    transform: scale(1);
  }
  20%, 60% {
    transform: scale(1.15);
  }
}
.heart {
  animation: heart 1000ms infinite;
}

Then, simply add the CSS class to the icon.

Example:

:octicons-heart-fill-24:{: .heart }

Result:

Customization¶

Using icons in templates¶

When you're extending the theme with partials or blocks, you can simply reference any icon that's bundled with the theme with Jinja's include function and wrap it with the twemoji class:

<span class="twemoji">
  {% include ".icons/fontawesome/brands/twitter.svg" %}
</span>

This is exactly what Material for MkDocs does in its templates.