Skip to content
Return to: MkDocs-MaterialX Start Page

Icons-Emojis

Icons-Emojis

Icons-Emojis

One of the best features of MaterialX for MkDocs is the possibility to use more than 10,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 Tip

    Enter some keywords to find icons and emojis and click on the shortcode to copy it to your clipboard.

    Configuration⚓︎

    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:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

    The following icon sets are bundled with Material for MkDocs:

    • Material Design
      Go to

      Material Design Icons.

    • FontAwesome
      Go to

      Font Awesome Icons.

    • Octicons
      Go to

      Octicons Icons.

    • Simple Icons
      Go to

      Simple Icons.

    • Lucide
      Go to

      Lucide Icons.

    • MaterialX-MkDocs
      Return to

      MaterialX-MkDocs.

    👉 Open Official Icon Search Database

    See additional configuration options:

    Usage⚓︎

    Using Emojis⚓︎

    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:

    Emoji
    :smile:

    😄

    smile

    <div class="result" markdown>

:smile:

</div>

    😄

    Using Icons⚓︎

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

    Icon
    :fontawesome-regular-face-laugh-wink:



    With Colours⚓︎

    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:

    Info

    .youtube {
color: #EE0F0F;
}

    extra_css:
  - stylesheets/extra.css

    Apply Customization

    After applying the customization, add the CSS class to the icon shortcode:

    Icon with color
    :fontawesome-brands-youtube:{ .youtube }

    With Animations⚓︎

    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:

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

    extra_css:
  - stylesheets/extra.css

    Add CSS Class

    After applying the customization, add the CSS class to the icon shortcode:

    Icon with animation
    :octicons-heart-fill-24:{ .heart }

    Icons, emojis in sidebars 😄⚓︎

    With the help of the built-in typeset plugin, you can use icons and emojis in headings, which will then be rendered in the sidebars. The plugin preserves Markdown and HTML formatting.

    Customization⚓︎

    Using Icons in Templates⚓︎

    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/youtube.svg" %} <!-- (1)! -->
</span>

    1. Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:







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

      Press Ctrl ＋ Alt ＋ Del to log in.

      • Installation Guide
        View Guide

        Step-by-step instructions to get MkDocs up and running.

      • Configuration (docs_dir)
        View Config

        Learn how to set up your source directory structure.

      • Deploying Your Docs
        View Guide

        How to publish your documentation to the web.

      • Documentation Layout
        View Layout

        Configure the navigation and global site structure.

      • GitHub Discussions
        Join Discussions

        Ask questions and engage with the community.

      • GitHub Issues
        View Issues

        Report bugs or request new features.

      • Site Name
        View Settings

        Define the title of your project and browser tab.

      • Theme
        View Theme

        Customise the look and feel of your documentation.

      • User Guide
        Open Guide

        The complete manual for all MkDocs features.

      Back to: #Advanced-Configuration