Metadata-Version: 2.4
Name: mkdocs-external-custom-emojis
Version: 0.2.0
Summary: Sync custom emojis from external providers (Slack, etc.) into MkDocs Material
Author-email: Julie Dujardin <julie@dujardin.pw>
License: MIT
License-File: LICENSE
Keywords: documentation,emoji,material,mkdocs,slack
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: mkdocs-material>=9.4.0
Requires-Dist: mkdocs>=1.4.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Description-Content-Type: text/markdown

# External Emojis for MkDocs

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

[![CI](https://github.com/julie-dujardin/mkdocs-external-custom-emojis/workflows/CI/badge.svg)](https://github.com/julie-dujardin/mkdocs-external-custom-emojis/actions)
[![Python Version](https://img.shields.io/pypi/pyversions/mkdocs-external-custom-emojis.svg)](https://pypi.org/project/mkdocs-external-custom-emojis/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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

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

### 2. Configure

Create `emoji-config.toml`:

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

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

```yaml
plugins:
  - external-emojis

markdown_extensions:
  - pymdownx.emoji
```

### 3. Use

```markdown
# Welcome! :partyparrot:

We love cats: :catjam: :shipit:
```

```bash
mkdocs build  # Emojis sync automatically!
```

## CLI

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

## Documentation

📚 **[Full Documentation](https://julie-dujardin.github.io/mkdocs-external-custom-emojis/)**

- [Quick Start Guide](https://julie-dujardin.github.io/mkdocs-external-custom-emojis/getting-started/quickstart/)
- [Configuration](https://julie-dujardin.github.io/mkdocs-external-custom-emojis/getting-started/configuration/)
- [CLI Commands](https://julie-dujardin.github.io/mkdocs-external-custom-emojis/user-guide/cli/)
- [Deployment](https://julie-dujardin.github.io/mkdocs-external-custom-emojis/getting-started/deployment/)

## License

MIT License - see [LICENSE](LICENSE) for details.
