0
# markdown-it-emoji
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: markdown-it-emoji
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install markdown-it-emoji`
10

11
## Core Imports
12

13
```javascript
14
import { full as emoji } from 'markdown-it-emoji'
15
import markdownit from 'markdown-it'
16

17
const md = markdownit().use(emoji)
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { full: emoji } = require('markdown-it-emoji')
24
const markdownit = require('markdown-it')
25

26
const md = markdownit().use(emoji)
27
```
28

29
Importing specific configurations:
30

31
```javascript
32
import { bare, light, full } from 'markdown-it-emoji'
33
```
34

35
Accessing emoji data directly:
36

37
```javascript
38
import fullEmojiDefs from 'markdown-it-emoji/lib/data/full.mjs'
39
import lightEmojiDefs from 'markdown-it-emoji/lib/data/light.mjs'
40
import emojiShortcuts from 'markdown-it-emoji/lib/data/shortcuts.mjs'
41
```
42

43
## Basic Usage
44

45
```javascript
46
import { full as emoji } from 'markdown-it-emoji'
47
import markdownit from 'markdown-it'
48

49
const md = markdownit().use(emoji)
50

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

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

60
With custom options:
61

62
```javascript
63
const md = markdownit().use(emoji, {
64
  defs: { 
65
    custom: '🎯',
66
    heart: '💖'
67
  },
68
  shortcuts: { 
69
    custom: ':target:',
70
    heart: '<3'
71
  },
72
  enabled: ['smile', 'custom', 'heart']
73
})
74
```
75

76
## Architecture
77

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

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

86
## Capabilities
87

88
### Plugin Variants
89

90
Three main plugin configurations offering different levels of emoji support.
91

92
#### Full Plugin
93

94
Complete emoji support with all Unicode emojis and emoticon shortcuts.
95

96
```javascript { .api }
97
/**
98
 * Full emoji plugin with complete emoji set and shortcuts
99
 * @param md - markdown-it instance
100
 * @param options - Plugin configuration options
101
 */
102
function full(md: MarkdownIt, options?: EmojiOptions): void;
103
```
104

105
#### Light Plugin
106

107
Lightweight version with commonly used emojis only.
108

109
```javascript { .api }
110
/**
111
 * Light emoji plugin with common emoji subset and shortcuts
112
 * @param md - markdown-it instance  
113
 * @param options - Plugin configuration options
114
 */
115
function light(md: MarkdownIt, options?: EmojiOptions): void;
116
```
117

118
#### Bare Plugin
119

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

122
```javascript { .api }
123
/**
124
 * Bare emoji plugin with no default emojis
125
 * @param md - markdown-it instance
126
 * @param options - Plugin configuration options (defs required)
127
 */
128
function bare(md: MarkdownIt, options: EmojiOptions): void;
129
```
130

131
### Plugin Configuration
132

133
Configure emoji definitions, shortcuts, and enabled emojis.
134

135
```javascript { .api }
136
interface EmojiOptions {
137
  /** Emoji name to Unicode character mapping */
138
  defs?: { [emojiName: string]: string };
139
  /** Emoticon shortcuts mapping to emoji names */
140
  shortcuts?: { 
141
    [emojiName: string]: string | string[]
142
  };
143
  /** Whitelist of enabled emoji names (empty array enables all) */
144
  enabled?: string[];
145
}
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
// Custom emoji definitions
152
const customEmojis = {
153
  defs: {
154
    rocket: '🚀',
155
    star: '⭐',
156
    custom: '🎯'
157
  }
158
}
159

160
// Custom shortcuts
161
const customShortcuts = {
162
  shortcuts: {
163
    heart: ['<3', '</3'],
164
    smile: [':)', ':-)', ':D'],
165
    wink: [';)', ';-)']
166
  }
167
}
168

169
// Whitelist specific emojis
170
const enabledOnly = {
171
  enabled: ['smile', 'heart', 'rocket']
172
}
173

174
// Combined configuration
175
const md = markdownit().use(full, {
176
  defs: { custom: '🎯' },
177
  shortcuts: { custom: ':target:' },
178
  enabled: ['smile', 'custom']
179
})
180
```
181

182
### Data Access
183

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

186
```javascript { .api }
187
/**
188
 * Full emoji definitions mapping emoji names to Unicode characters
189
 * Contains all Unicode emojis (1000+ emojis)
190
 */
191
const fullEmojiDefs: { [emojiName: string]: string };
192

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

199
/**
200
 * Emoticon shortcuts mapping emoji names to shortcut patterns
201
 * Maps emoji names to arrays of emoticon patterns like ':)', ':('
202
 */
203
const emojiShortcuts: { [emojiName: string]: string[] };
204
```
205

206
**Usage Examples:**
207

208
```javascript
209
// Access full emoji definitions (ESM)
210
import fullEmojiDefs from 'markdown-it-emoji/lib/data/full.mjs'
211
console.log(fullEmojiDefs.rocket) // '🚀'
212
console.log(Object.keys(fullEmojiDefs).length) // 1000+ emojis
213

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

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

223
// Create custom plugin with specific emojis
224
import { bare } from 'markdown-it-emoji'
225
const customPlugin = (md, options) => {
226
  const selectedEmojis = {
227
    rocket: fullEmojiDefs.rocket,
228
    star: fullEmojiDefs.star,
229
    heart: fullEmojiDefs.heart
230
  }
231
  
232
  return bare(md, {
233
    defs: selectedEmojis,
234
    shortcuts: {
235
      heart: emojiShortcuts.heart,
236
      ...options.shortcuts
237
    }
238
  })
239
}
240
```
241

242
### Custom Rendering
243

244
Customize how emojis are rendered in the final output.
245

246
```javascript { .api }
247
/**
248
 * Default emoji renderer function
249
 * @param tokens - Array of tokens
250
 * @param idx - Current token index
251
 * @returns Rendered emoji string
252
 */
253
function emojiRenderer(tokens: Token[], idx: number): string;
254

255
interface EmojiToken extends Token {
256
  /** The emoji name (e.g., 'smile') */
257
  markup: string;
258
  /** The Unicode emoji character or custom content */
259
  content: string;
260
}
261
```
262

263
**Usage Examples:**
264

265
```javascript
266
// Custom CSS class renderer
267
md.renderer.rules.emoji = function(tokens, idx) {
268
  const token = tokens[idx]
269
  return '<span class="emoji emoji_' + token.markup + '"></span>'
270
}
271

272
// Twemoji integration
273
import twemoji from 'twemoji'
274

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

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

286
## Types
287

288
```javascript { .api }
289
interface MarkdownIt {
290
  /** Add plugin to markdown-it instance */
291
  use(plugin: Function, options?: any): MarkdownIt;
292
  /** Render markdown to HTML */
293
  render(markdown: string): string;
294
  /** Renderer rules for token types */
295
  renderer: {
296
    rules: {
297
      [tokenType: string]: (tokens: Token[], idx: number) => string;
298
    };
299
  };
300
}
301

302
interface Token {
303
  /** Token type identifier */
304
  type: string;
305
  /** Token markup content */
306
  markup: string;
307
  /** Token content */
308
  content: string;
309
  /** Nesting level */
310
  level: number;
311
}
312

313
interface EmojiOptions {
314
  /** Emoji definitions mapping names to Unicode characters */
315
  defs?: { [emojiName: string]: string };
316
  /** Shortcut patterns mapping to emoji names */  
317
  shortcuts?: { [emojiName: string]: string | string[] };
318
  /** Array of enabled emoji names (empty = all enabled) */
319
  enabled?: string[];
320
}
321
```
322

323
## Common Patterns
324

325
### Multiple Format Support
326

327
```javascript
328
// Support both import styles
329
import { full } from 'markdown-it-emoji'  // ESM
330
const { full } = require('markdown-it-emoji')  // CommonJS
331

332
// Browser global (when loaded via script tag)
333
const { full } = window.markdownitEmoji
334
```
335

336
### Error Handling
337

338
```javascript
339
// Validate emoji exists before using
340
const md = markdownit().use(full, {
341
  enabled: ['smile', 'nonexistent']  // nonexistent will be ignored
342
})
343

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

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

357
### Performance Optimization
358

359
```javascript
360
// Use light version for better performance
361
import { light } from 'markdown-it-emoji'
362

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