Emoji System API Reference: Clean and Simple

The definitive guide to using the emoji system in your Eleventy templates.

After cleaning up some API drift, here's the current, clean emoji system API with clear naming and purposes.

🎯 Three Main Use Cases

1. Convert Emoticons to Emojis - {{ text | emoji }}

Purpose: Convert emoticons like 🙂 and 😂 in your text to emojis 🙂 😂

Usage:

{{ "Hello world 🙂" | emoji | safe }}
{{ content | emoji | safe }}
{{ someVariable | emoji | safe }}

Examples:

<!-- Input: "Thanks for reading 😛" -->
{{ "Thanks for reading 😛" | emoji | safe }}
<!-- Output: "Thanks for reading 😛" -->

<!-- In post templates -->
<div class="post-content">
    {{ content | emoji | safe }}
</div>

2. Get AI Emoji Suggestions - {{ text | emojiSuggest }}

Purpose: Use AI to suggest relevant emojis based on content meaning

Usage:

{{ "documentation" | emojiSuggest }}
{{ title | emojiSuggest(1) }}
{{ "building software" | emojiSuggest(3) }}

Examples:

<!-- AI suggests emojis based on semantic meaning -->
{{ "writing documentation" | emojiSuggest }}
<!-- Output: "✍️ 📖" -->

{{ "celebration party" | emojiSuggest }}
<!-- Output: "🎉 🎊" -->

<!-- In headlines -->
<h1>{{ title }} {{ title | emojiSuggest(1) }}</h1>

3. Emoji Reactions - {% emojiReact "text" %}

Purpose: Add styled emoji reactions with tooltips showing AI confidence

Usage:

{% emojiReact "Site Info & Credits" %}
{% emojiReact title %}
{% emojiReact "documentation", 1, 0.7 %}

Examples:

<!-- Adds styled reactions with tooltips -->
<h2>{{ title }}{% emojiReact title %}</h2>

<!-- In footer -->
<summary>Site Info{% emojiReact "Site Info & Credits" %}</summary>

<!-- With custom parameters: maxEmojis=1, threshold=0.7 -->
{% emojiReact "technical writing", 1, 0.7 %}

🎛️ Advanced Options

4. Advanced Processing - {{ text | emojiAdvanced(options) }}

Purpose: Advanced emoji processing with debug mode and special options

Usage:

{{ content | emojiAdvanced({debugMode: true}) | safe }}
{{ text | emojiAdvanced({includeOriginal: true}) | safe }}

Options:

• debugMode: true - Shows transformation details
• includeOriginal: true - Includes both emoticons and emojis for toggle

🔧 Real-World Examples

Blog Post Content

<!-- _includes/post.njk -->
<div class="post-content">
    {{ content | emoji | safe }}
</div>

Enhanced Headlines

<!-- Add AI-suggested emojis to titles -->
<h1>{{ title }} {{ title | emojiSuggest(1) }}</h1>

<!-- Or add reaction emojis -->
<h2>{{ title }}{% emojiReact title %}</h2>

Footer with Mixed Approach

<!-- Convert emoticons AND add AI reactions -->
<summary>{{ "Site Info 🙂" | emoji | safe }}{% emojiReact "Site Info" %}</summary>

📊 Quick Comparison

🎨 Styling Emoji Reactions

The {% emojiReact %} shortcode generates HTML with classes you can style:

.emoji-reaction {
    font-size: 1.1em;
    margin-left: 0.5rem;
    opacity: 0.8;
    transition: opacity 0.2s ease;
}

.emoji-reaction:hover {
    opacity: 1;
    cursor: help;
}

🐛 Debug Features

• Debug Mode: Add ?debugEmojis=true to any URL
• Keyboard Shortcut: Press Ctrl+E to toggle emoji controls
• Nostalgia Mode: Toggle between emojis and emoticons
• Console Warnings: Deprecated filters show warnings in build logs

📝 Best Practices

1. Use | emoji for converting emoticons in content
2. Use | emojiSuggest for AI-powered emoji additions
3. Use {% emojiReact %} for styled reactions with tooltips
4. Always include | safe when using emoji filters
5. Test with debug mode to see what's being converted

🎯 Your Specific Use Case

For "Site Info & Credits" in the footer, you have options:

<!-- Option 1: Just convert any emoticons -->
{{ "Site Info & Credits 🙂" | emoji | safe }}

<!-- Option 2: Get AI emoji suggestions -->
Site Info & Credits {{ "Site Info & Credits" | emojiSuggest }}

<!-- Option 3: Add styled reactions -->
Site Info & Credits{% emojiReact "Site Info & Credits" %}

<!-- Option 4: Combine approaches -->
{{ "Site Info & Credits 🙂" | emoji | safe }}{% emojiReact "Site Info" %}

The cleaned-up API makes it clear what each function does and when to use it. No more confusion! 😄