Skip to content

Icons & Emojis

Material for MkDocs provides extensive support for icons and emojis through the emoji extension, including thousands of icons from popular icon sets and standard emoji support.

Overview

Icons and emojis provide:

  • Visual communication - Enhance text with visual elements
  • 8000+ icons - Material Design, FontAwesome, Octicons, and more
  • Standard emojis - Full Unicode emoji support
  • Custom icons - Add your own SVG icons
  • Search functionality - Find icons by name or keyword
  • Accessibility - Proper ARIA labels

Configuration

Enable icons and emojis in mkdocs.yml:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

Theme Configuration

theme:
  icon:
    logo: material/library
    repo: fontawesome/brands/github
  features:
    - content.tooltips  # Enable icon tooltips

Using Icons

Material Design Icons

Use :material-icon-name: syntax:

:material-account: User account
:material-calendar: Calendar
:material-delete: Delete
:material-download: Download
:material-email: Email
:material-file: File
:material-folder: Folder
:material-heart: Favorite
:material-home: Home
:material-information: Info
:material-menu: Menu
:material-search: Search
:material-settings: Settings
:material-share: Share
:material-star: Star

Result:

User account Calendar Delete Download Email File Folder Favorite Home Info Menu :material-search: Search :material-settings: Settings Share Star

FontAwesome Icons

Use :fontawesome-type-name: syntax:

:fontawesome-brands-github: GitHub
:fontawesome-brands-twitter: Twitter
:fontawesome-brands-facebook: Facebook
:fontawesome-brands-youtube: YouTube
:fontawesome-solid-code: Code
:fontawesome-solid-book: Documentation
:fontawesome-solid-download: Download
:fontawesome-regular-file-pdf: PDF

Result:

GitHub Twitter Facebook YouTube Code Documentation Download PDF

Octicons

Use :octicons-icon-name: syntax:

:octicons-git-branch-16: Branch
:octicons-git-commit-16: Commit
:octicons-git-merge-16: Merge
:octicons-git-pull-request-16: Pull Request
:octicons-issue-opened-16: Issue
:octicons-check-16: Check
:octicons-x-16: Close
:octicons-link-16: Link

Result:

Branch Commit Merge Pull Request Issue Check Close Link

Using Emojis

Standard Emojis

Use :emoji-name: syntax:

:smile: :laughing: :blush: :heart_eyes:
:sunglasses: :thinking: :thumbsup: :thumbsdown:
:clap: :fire: :rocket: :star:
:warning: :white_check_mark: :x: :bell:
:email: :calendar: :clock1: :mag:

Result:

😄 😆 😊 😍 😎 🤔 👍 👎 👏 🔥 🚀 ⭐ ⚠ ✅ ❌ 🔔 📧 📆 🕐 🔍

Unicode Emojis

You can also use Unicode emojis directly:

😀 😁 😂 🤣 😃 😄 😅 😆
👍 👎 👌 ✌️ 🤞 🤟 🤘 🤙
❤️ 🧡 💛 💚 💙 💜 🖤 🤍
✅ ❌ ⚠️ 📌 🔔 📧 📅 🔍

Result:

😀 😁 😂 🤣 😃 😄 😅 😆 👍 👎 👌 ✌️ 🤞 🤟 🤘 🤙 ❤️ 🧡 💛 💚 💙 💜 🖤 🤍 ✅ ❌ ⚠️ 📌 🔔 📧 📅 🔍

Practical Applications

Status Indicators

Service Status Uptime
API Operational 99.99%
Database Operational 99.95%
CDN Degraded 98.50%
Email Down 95.00%

Feature Comparison

Feature Free Pro Enterprise
Basic Features
Advanced Search
API Access
Custom Branding
Priority Support
SLA

File Type Icons

  • README.md - Documentation
  • script.py - Python file
  • config.yml - Configuration
  • logo.png - Image file
  • report.pdf - PDF document
  • data.xlsx - Spreadsheet
  • archive.zip - Compressed file

Icon Styling

Size Modifiers

:material-home:{ .small } Small
:material-home: Normal
:material-home:{ .medium } Medium
:material-home:{ .large } Large
:material-home:{ .x-large } Extra Large

Color Modifiers

:material-check-circle:{ .success } Success
:material-information:{ .info } Information
:material-alert:{ .warning } Warning
:material-close-circle:{ .error } Error

Custom CSS

/* Icon colors */
.md-typeset .success { color: #4caf50; }
.md-typeset .info { color: #2196f3; }
.md-typeset .warning { color: #ff9800; }
.md-typeset .error { color: #f44336; }

/* Icon sizes */
.md-typeset .small svg { width: 1em; height: 1em; }
.md-typeset .medium svg { width: 1.5em; height: 1.5em; }
.md-typeset .large svg { width: 2em; height: 2em; }
.md-typeset .x-large svg { width: 3em; height: 3em; }

/* Icon animations */
.md-typeset .rotate svg {
    animation: rotate 2s linear infinite;
}

@keyframes rotate {
    from { transform: rotate(0deg); }
    to { transform: rotate(360deg); }
}

.md-typeset .pulse svg {
    animation: pulse 2s ease-in-out infinite;
}

@keyframes pulse {
    0%, 100% { opacity: 1; }
    50% { opacity: 0.5; }
}

Custom Icons

Adding Custom Icons

  1. Create directory structure: 

    overrides/
  .icons/
    custom/
      my-icon.svg

  2. Use in documentation: 

    :custom-my-icon: My Custom Icon

SVG Icon Example

<!-- overrides/.icons/custom/rocket.svg -->
<svg viewBox="0 0 24 24">
  <path d="M12 2C12 2 7 4 7 12C7 16 9 19 9 19L12 22L15 19C15 19 17 16 17 12C17 4 12 2 12 2Z"/>
</svg>

Icon Lists

Development Icons

  • Python
  • JavaScript
  • TypeScript
  • HTML5
  • CSS3
  • React
  • Vue.js
  • Angular
  • Node.js
  • Docker
  • Git
  • GitHub

Action Icons

  • Add/Create
  • Edit
  • Delete
  • Save
  • Copy
  • Paste
  • Undo
  • Redo
  • Refresh
  • Download
  • Upload
  • Share

Status Icons

  • Success/Complete
  • Error/Failed
  • Warning
  • Information
  • Help
  • Pending/In Progress
  • Locked/Secure
  • Unlocked
  • Verified
  • Bug/Issue

Best Practices

1. Meaningful Usage

Use icons to enhance understanding:

✅ Good:
:material-alert: **Warning:** This action cannot be undone.

❌ Bad:
:material-alert: :material-alert: :material-alert: Warning!!! :material-alert:

2. Consistency

Use the same icon for the same concept:

✅ Good:
Always use :material-download: for downloads

❌ Bad:
Mix :material-download:, :material-cloud-download:, :material-file-download:

3. Accessibility

Provide text alongside icons:

✅ Good:
:material-download: Download PDF

❌ Bad:
:material-download:

4. Restraint

Don't overuse icons:

✅ Good:
## :material-cog: Settings

❌ Bad:
## :material-cog: Settings :material-wrench: Configuration :material-tune:

Common Patterns

Feature Cards

Fast Lightning-fast build times

Customizable Extensive theming options

Searchable Built-in search functionality

Responsive Works on all devices

Process Steps

  1. Initialize Project Set up the basic structure

  2. Install Dependencies Add required packages

  3. Configure Settings Customize for your needs

  4. Deploy Publish your documentation

Notification Types

Note

This is a general note with additional information.

Tip

Here's a helpful tip to improve your workflow.

Warning

Be careful with this operation.

Danger

This action is potentially destructive.

Connect with us: GitHub Twitter LinkedIn Discord Slack

To find available icons:

  1. Visit Material Design Icons
  2. Search for your desired icon
  3. Use the name with :material- prefix
  4. For FontAwesome, visit FontAwesome Icons

See Also