or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-markdown-it-emoji

Emoji plugin for markdown-it markdown parser with support for emoji shortcodes and emoticon shortcuts.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/markdown-it-emoji@3.0.x

To install, run

npx @tessl/cli install tessl/npm-markdown-it-emoji@3.0.0

index.mddocs/

markdown-it-emoji

markdown-it-emoji is a plugin for the markdown-it markdown parser that adds comprehensive emoji and emoticon support. It converts emoji shortcodes (like :smile:) and emoticon shortcuts (like :) and :-() into Unicode emoji characters or custom renderers. The plugin offers three configuration levels (full, light, bare) with different emoji sets and supports both ESM and CommonJS module formats.

Package Information

  • Package Name: markdown-it-emoji
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install markdown-it-emoji

Core Imports

import { full as emoji } from 'markdown-it-emoji'
import markdownit from 'markdown-it'

const md = markdownit().use(emoji)

For CommonJS:

const { full: emoji } = require('markdown-it-emoji')
const markdownit = require('markdown-it')

const md = markdownit().use(emoji)

Importing specific configurations:

import { bare, light, full } from 'markdown-it-emoji'

Accessing emoji data directly:

import fullEmojiDefs from 'markdown-it-emoji/lib/data/full.mjs'
import lightEmojiDefs from 'markdown-it-emoji/lib/data/light.mjs'
import emojiShortcuts from 'markdown-it-emoji/lib/data/shortcuts.mjs'

Basic Usage

import { full as emoji } from 'markdown-it-emoji'
import markdownit from 'markdown-it'

const md = markdownit().use(emoji)

// Convert emoji shortcodes
const result = md.render('Hello from mars :satellite:')
// Output: '<p>Hello from mars 📡</p>'

// Convert emoticon shortcuts  
const emoticons = md.render('I am happy :) and sad :(')
// Output: '<p>I am happy 😃 and sad 😞</p>'

With custom options:

const md = markdownit().use(emoji, {
  defs: { 
    custom: '🎯',
    heart: '💖'
  },
  shortcuts: { 
    custom: ':target:',
    heart: '<3'
  },
  enabled: ['smile', 'custom', 'heart']
})

Architecture

markdown-it-emoji integrates with markdown-it's processing pipeline through several key components:

  • Plugin Variants: Three pre-configured plugins (bare, light, full) with different emoji sets
  • Options Processing: Normalizes user options and compiles regular expressions for efficient matching
  • Core Ruler Integration: Adds emoji replacement after the linkify stage in markdown-it's core processing
  • Token Generation: Creates emoji tokens that can be customized through renderer rules
  • Renderer Integration: Provides default emoji rendering with customization support

Capabilities

Plugin Variants

Three main plugin configurations offering different levels of emoji support.

Full Plugin

Complete emoji support with all Unicode emojis and emoticon shortcuts.

/**
 * Full emoji plugin with complete emoji set and shortcuts
 * @param md - markdown-it instance
 * @param options - Plugin configuration options
 */
function full(md: MarkdownIt, options?: EmojiOptions): void;

Light Plugin

Lightweight version with commonly used emojis only.

/**
 * Light emoji plugin with common emoji subset and shortcuts
 * @param md - markdown-it instance  
 * @param options - Plugin configuration options
 */
function light(md: MarkdownIt, options?: EmojiOptions): void;

Bare Plugin

Minimal plugin with no default emojis, requires custom emoji definitions.

/**
 * Bare emoji plugin with no default emojis
 * @param md - markdown-it instance
 * @param options - Plugin configuration options (defs required)
 */
function bare(md: MarkdownIt, options: EmojiOptions): void;

Plugin Configuration

Configure emoji definitions, shortcuts, and enabled emojis.

interface EmojiOptions {
  /** Emoji name to Unicode character mapping */
  defs?: { [emojiName: string]: string };
  /** Emoticon shortcuts mapping to emoji names */
  shortcuts?: { 
    [emojiName: string]: string | string[]
  };
  /** Whitelist of enabled emoji names (empty array enables all) */
  enabled?: string[];
}

Usage Examples:

// Custom emoji definitions
const customEmojis = {
  defs: {
    rocket: '🚀',
    star: '⭐',
    custom: '🎯'
  }
}

// Custom shortcuts
const customShortcuts = {
  shortcuts: {
    heart: ['<3', '</3'],
    smile: [':)', ':-)', ':D'],
    wink: [';)', ';-)']
  }
}

// Whitelist specific emojis
const enabledOnly = {
  enabled: ['smile', 'heart', 'rocket']
}

// Combined configuration
const md = markdownit().use(full, {
  defs: { custom: '🎯' },
  shortcuts: { custom: ':target:' },
  enabled: ['smile', 'custom']
})

Data Access

Direct access to emoji definitions and shortcut mappings for advanced usage.

/**
 * Full emoji definitions mapping emoji names to Unicode characters
 * Contains all Unicode emojis (1000+ emojis)
 */
const fullEmojiDefs: { [emojiName: string]: string };

/**
 * Light emoji definitions mapping emoji names to Unicode characters  
 * Contains commonly used emoji subset (~100 emojis)
 */
const lightEmojiDefs: { [emojiName: string]: string };

/**
 * Emoticon shortcuts mapping emoji names to shortcut patterns
 * Maps emoji names to arrays of emoticon patterns like ':)', ':('
 */
const emojiShortcuts: { [emojiName: string]: string[] };

Usage Examples:

// Access full emoji definitions (ESM)
import fullEmojiDefs from 'markdown-it-emoji/lib/data/full.mjs'
console.log(fullEmojiDefs.rocket) // '🚀'
console.log(Object.keys(fullEmojiDefs).length) // 1000+ emojis

// Access light emoji definitions
import lightEmojiDefs from 'markdown-it-emoji/lib/data/light.mjs' 
console.log(lightEmojiDefs.smile) // '😄'

// Access shortcut mappings
import emojiShortcuts from 'markdown-it-emoji/lib/data/shortcuts.mjs'
console.log(emojiShortcuts.smile) // [':)', ':-)']
console.log(emojiShortcuts.heart) // ['<3']

// Create custom plugin with specific emojis
import { bare } from 'markdown-it-emoji'
const customPlugin = (md, options) => {
  const selectedEmojis = {
    rocket: fullEmojiDefs.rocket,
    star: fullEmojiDefs.star,
    heart: fullEmojiDefs.heart
  }
  
  return bare(md, {
    defs: selectedEmojis,
    shortcuts: {
      heart: emojiShortcuts.heart,
      ...options.shortcuts
    }
  })
}

Custom Rendering

Customize how emojis are rendered in the final output.

/**
 * Default emoji renderer function
 * @param tokens - Array of tokens
 * @param idx - Current token index
 * @returns Rendered emoji string
 */
function emojiRenderer(tokens: Token[], idx: number): string;

interface EmojiToken extends Token {
  /** The emoji name (e.g., 'smile') */
  markup: string;
  /** The Unicode emoji character or custom content */
  content: string;
}

Usage Examples:

// Custom CSS class renderer
md.renderer.rules.emoji = function(tokens, idx) {
  const token = tokens[idx]
  return '<span class="emoji emoji_' + token.markup + '"></span>'
}

// Twemoji integration
import twemoji from 'twemoji'

md.renderer.rules.emoji = function(tokens, idx) {
  return twemoji.parse(tokens[idx].content)
}

// Custom image renderer  
md.renderer.rules.emoji = function(tokens, idx) {
  const emojiName = tokens[idx].markup
  return `<img src="/emojis/${emojiName}.png" alt=":${emojiName}:" class="emoji">`
}

Types

interface MarkdownIt {
  /** Add plugin to markdown-it instance */
  use(plugin: Function, options?: any): MarkdownIt;
  /** Render markdown to HTML */
  render(markdown: string): string;
  /** Renderer rules for token types */
  renderer: {
    rules: {
      [tokenType: string]: (tokens: Token[], idx: number) => string;
    };
  };
}

interface Token {
  /** Token type identifier */
  type: string;
  /** Token markup content */
  markup: string;
  /** Token content */
  content: string;
  /** Nesting level */
  level: number;
}

interface EmojiOptions {
  /** Emoji definitions mapping names to Unicode characters */
  defs?: { [emojiName: string]: string };
  /** Shortcut patterns mapping to emoji names */  
  shortcuts?: { [emojiName: string]: string | string[] };
  /** Array of enabled emoji names (empty = all enabled) */
  enabled?: string[];
}

Common Patterns

Multiple Format Support

// Support both import styles
import { full } from 'markdown-it-emoji'  // ESM
const { full } = require('markdown-it-emoji')  // CommonJS

// Browser global (when loaded via script tag)
const { full } = window.markdownitEmoji

Error Handling

// Validate emoji exists before using
const md = markdownit().use(full, {
  enabled: ['smile', 'nonexistent']  // nonexistent will be ignored
})

// Check if emoji is supported (ESM)
import emojiDefs from 'markdown-it-emoji/lib/data/full.mjs'
if (emojiDefs.rocket) {
  console.log('Rocket emoji supported:', emojiDefs.rocket)
}

// CommonJS version would need to use dynamic import:
// const emojiDefs = await import('markdown-it-emoji/lib/data/full.mjs')
// if (emojiDefs.default.rocket) {
//   console.log('Rocket emoji supported:', emojiDefs.default.rocket)
// }

Performance Optimization

// Use light version for better performance
import { light } from 'markdown-it-emoji'

// Limit enabled emojis for faster processing
const md = markdownit().use(full, {
  enabled: ['smile', 'heart', 'thumbsup', 'thumbsdown']
})