mkdocs-external-custom-emojis 0.2.0

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

External Emojis for MkDocs

Sync custom emojis from Slack, Discord, and more into MkDocs Material

Use your organization's custom emojis directly in MkDocs with the familiar :emoji-name: syntax.

Features

• 🔄 Automatic Sync - Emojis sync during MkDocs build
• 🔌 Multiple Providers - Slack, Discord, multiple workspaces
• 🔧 Extensible - Easy to add new providers
• 💾 Smart Caching - TTL-based caching minimizes API calls
• 🎯 Filtering - Include/exclude emoji patterns
• 🖥️ CLI Tools - Manage emojis from the command line
• ♿ Accessible - Screen reader friendly with proper alt text

Quick Start

1. Install

uv add mkdocs-external-custom-emojis
# or: pip install mkdocs-external-custom-emojis

2. Configure

Create 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"

[[providers]]
type = "discord"
namespace = "secret_discord"
token_env = "SECOND_DISCORD_BOT_TOKEN"
tenant_id = "SECOND_DISCORD_GUILD_ID"

Set your token:

export SLACK_TOKEN="xoxp-your-token-here"
export DISCORD_BOT_TOKEN="MTIz..."
export DISCORD_GUILD_ID="123456789012345678"
export SECOND_DISCORD_BOT_TOKEN="MTIz..."
export SECOND_DISCORD_GUILD_ID="987654321012345678"

Add to mkdocs.yml:

plugins:
  - external-emojis

markdown_extensions:
  - pymdownx.emoji

3. Use

# Welcome! :partyparrot:

We love cats: :catjam: :shipit:

mkdocs build  # Emojis sync automatically!

CLI

mkdocs-emoji init      # Create config
mkdocs-emoji sync      # Download emojis
mkdocs-emoji list      # List available emojis
mkdocs-emoji validate  # Check configuration

Documentation

📚 Full Documentation

• Quick Start Guide
• Configuration
• CLI Commands
• Deployment

License

MIT License - see LICENSE for details.