mkdocs-material/docs/reference/icons-emojis.md

template	icon
overrides/main.html	material/emoticon-happy-outline

Icons + Emojis

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

Search

:octicons-light-bulb-16: **Tip:** Enter some keywords to find icons and emojis and click on the shortcode to copy it to your clipboard.

Configuration

This configuration enables the use of icons and emojis by using simple shortcodes which can be discovered through the icon search. 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

The following icon sets are bundled with Material for MkDocs:

• :material-material-design: – Material Design
• :fontawesome-brands-font-awesome: – FontAwesome
• :octicons-mark-github-16: – Octicons

See additional configuration options:

• Emoji

• Emoji with custom icons

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: – `material/account-circle.svg`
- :fontawesome-regular-laugh-wink: – `fontawesome/regular/laugh-wink.svg`
- :octicons-repo-push-16: – `octicons/repo-push-16.svg`

Result:

• :material-account-circle: – material/account-circle.svg

• :fontawesome-regular-laugh-wink: – fontawesome/regular/laugh-wink.svg

• :octicons-repo-push-16: – octicons/repo-push-16.svg

with colors

When Attribute Lists is enabled, custom CSS classes can be added to icons by suffixing the icon with a special syntax. While HTML allows to use inline styles, it's always recommended to add an additional style sheet and move declarations into dedicated CSS classes.

Example:

=== ":octicons-file-code-16: docs/example.md"

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

=== ":octicons-file-code-16: docs/stylesheets/extra.css"

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

=== ":octicons-file-code-16: mkdocs.yml"

``` yaml
extra_css:
  - stylesheets/extra.css
```

Result:

• :fontawesome-brands-medium:{ .medium } – Medium

• :fontawesome-brands-twitter:{ .twitter } – Twitter

• :fontawesome-brands-facebook:{ .facebook } – Facebook

with animations

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

Example:

=== ":octicons-file-code-16: docs/example.md"

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

=== ":octicons-file-code-16: docs/stylesheets/extra.css"

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

=== ":octicons-file-code-16: mkdocs.yml"

``` yaml
extra_css:
  - stylesheets/extra.css
```

Result:

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

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 CSS class:

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

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