remark-gemoji

remark plugin to turn gemoji shortcodes (:+1:) into emoji (👍).

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(remarkGemoji)
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (remark) plugin to turn gemoji shortcodes into emoji.

When should I use this?

You can use this plugin to match how GitHub turns gemoji (G*itHub *Emoji) shortcodes into emoji. This plugin does not support other platforms such as Slack and what labels they support.

A different plugin, remark-gfm, adds support for GFM (GitHub Flavored Markdown). GFM is a set of extensions (autolink literals, footnotes, strikethrough, tables, and tasklists) to markdown that are supported everywhere on GitHub.

Another plugin, remark-frontmatter, adds support for YAML frontmatter. GitHub supports frontmatter for files in Gists and repos.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install remark-gemoji

In Deno with esm.sh:

import remarkGemoji from 'https://esm.sh/remark-gemoji@8'

In browsers with esm.sh:

<script type="module">
  import remarkGemoji from 'https://esm.sh/remark-gemoji@8?bundle'
</script>

Use

Say we have the following file example.md:

Look, the moon :new_moon_with_face:

Here’s a family :family_man_man_boy_boy:

Слава Україні!  :ukraine:

…and a module example.js:

import remarkGemoji from 'remark-gemoji'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkGemoji)
  .use(remarkStringify)
  .process(await read('example.md'))

console.log(String(file))

…then running node example.js yields:

Look, the moon 🌚

Here’s a family 👨‍👨‍👦‍👦

Слава Україні!  🇺🇦

API

This package exports no identifiers. The default export is remarkGemoji.

unified().use(remarkGemoji)

Turn gemoji shortcodes (:+1:) into emoji (👍).

Parameters

There are no parameters.

Returns

Transform (Transformer).

Syntax

This plugin looks for the regular expression /:(\+1|[-\w]+):/g in text in markdown (excluding code and such). If the value between the two colons matches a know gemoji shortcode, then its replaced by the corresponding emoji.

In EBNF, the grammar looks as follows:

gemoji ::=  ':' ('+' '1' | character+) ':'
character ::= '-' | '_' | letter | digit
letter ::= letterLowercase | letterUppercase
letterLowercase ::= 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z'
letterUppercase ::= 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z'
digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'

Types

This package is fully typed with TypeScript. It exports no additional types.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-gemoji@^8, compatible with Node.js 16.

This plugin works with unified version 3+ and remark version 4+.

Security

Use of remark-gemoji does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

Related

• remark-gfm — support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)
• remark-github — link references to commits, issues, pull-requests, and users, like on GitHub
• remark-breaks — support hard breaks without needing spaces or escapes
• remark-frontmatter — support frontmatter (YAML, TOML, and more)

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer