Skip to content

:partyparrot: External Emojis for MkDocs :reverseparrot:

Sync custom emojis from external providers (Slack, Discord, etc.) into MkDocs Material

CI Python Version License

Overview

Use your organization's custom Slack or Discord emojis directly in MkDocs Material documentation with the familiar :emoji-name: syntax.

:catjam: :cat-dance: :meow_party: :meow-bongo-cat: :typingcat: :shipit: :stonks: :this_is_fine:

Installation :rocket_animated:

pip install mkdocs-external-custom-emojis

Or with uv :stonks:

uv add mkdocs-external-custom-emojis

Quick Example :fastparrot:

emoji-config.toml
[[providers]]
type = "slack"
namespace = "slack"
token_env = "SLACK_TOKEN"

[[providers]]
type = "discord"
namespace = "discord"
token_env = "DISCORD_BOT_TOKEN"
tenant_id = "DISCORD_GUILD_ID"
mkdocs.yml
plugins:
  - external-emojis

markdown_extensions:
  - pymdownx.emoji  # The plugin auto-configures this

# My Awesome Docs

Custom emojis work everywhere:
- In headings :slack-partyparrot:
- In lists :slack-shipit:
- In admonitions :slack-catjam:

!!! tip "Pro Tip"
    Use emojis to make your docs more engaging!

Key Features

  • Automatic Sync - Emojis sync automatically during MkDocs build
  • Smart Caching - TTL-based caching to minimize API calls
  • Extensible - Easy to add new providers
  • Multiple Providers - Support multiple Slack or Discord workspaces/servers
  • Filtering - Include/exclude emoji patterns
  • CLI Tools - Manage emojis with built-in CLI commands
  • Accessible - Screen reader friendly with proper alt text

How It Works :claudethinking:

graph LR
    A[mkdocs build] --> B[Load config]
    B --> C[Fetch emojis]
    C --> D[Cache locally]
    D --> E[Sync to assets]
    E --> F[":partyparrot:"]
  1. Build Start - MkDocs plugin activates
  2. Fetch Emoji List - Provider API called (cached if fresh)
  3. Download Emojis - Missing/stale emojis downloaded
  4. Sync to Icons Dir - Emojis placed in overrides/assets/emojis/<namespace>/
  5. MkDocs Renders - Material theme finds custom icons automatically :tada-animated:

Next Steps

License

This project is licensed under the MIT License - see the LICENSE file for details.