rehype-github-emoji

rehype plugin to enhance emoji and gemoji.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • defaultBuild(info, value)
  • defaultCustom
  • defaultIgnore
  • rehypeGithubEmoji(options?)
  • Build
  • Gemoji
  • Options
• Authoring
• HTML
• CSS
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• Notice
• License

What is this?

This plugin enhances unicode emoji (👍), gemoji shortcodes (:+1:), and custom gemoji (:shipit:, :shipit:). By default it wraps them with a custom element, specific to GitHub, which you will want to change.

This plugin is part of a monorepo rehype-github. See its readme for more info.

When should I use this?

You can use this plugin when you want to match how github.com works or when you want to build similar pipelines that enhance emoji.

Install

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

npm install rehype-github-emoji

In Deno with esm.sh:

import rehypeGithubEmoji from 'https://esm.sh/rehype-github-emoji@1'

In browsers with esm.sh:

<script type="module">
  import rehypeGithubEmoji from 'https://esm.sh/rehype-github-emoji@1?bundle'
</script>

Use

Say our module example.js looks as follows:

import rehypeGithubEmoji from 'rehype-github-emoji'
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeGithubEmoji)
  .use(rehypeStringify)
  .process(':shipit: 👍')

console.log(String(file))

…now running node example.js yields:

<img class="emoji" title=":shipit:" alt=":shipit:" src="https://github.githubassets.com/images/icons/emoji/shipit.png" height="20" width="20" align="absmiddle"> 👍

API

This package exports the identifiers defaultBuild, defaultCustom, and defaultIgnore. The default export is rehypeGithubEmoji.

defaultBuild(info, value)

The default builder to turn an emoji or gemoji into rich content.

Parameters

• info (Gemoji or string) — info on the known emoji or gemoji, or the custom gemoji name
• value (string) — literal match the way it was written

Returns

Markup for the emoji or gemoji (Element).

defaultCustom

Default custom gemoji names (Array<string>).

defaultIgnore

Default tests for elements to not enhance (Array<string>).

rehypeGithubEmoji(options?)

Plugin to enhance emoji and gemoji.

Parameters

• options (Options, optional) — configuration

Build

Make rich content from an emoji or a gemoji (TypeScript type).

Parameters

• info (Gemoji or string) — info on the known emoji or gemoji, or the custom gemoji name
• value (string) — literal match the way it was written

Returns

Rich content (ElementContent, Array<ElementContent>, false).

Gemoji

Info on an emoji (TypeScript type).

Fields

• emoji (string) — example: '😀'
• names (Array<string>) — example: ['grinning']
• tags (Array<string>) — example: ['smile', 'happy']
• description (string) — example: 'grinning face'
• category (string) — example: 'Smileys & Emotion'

Options

Configuration (TypeScript type).

Fields

• build (Build, default: defaultBuild) — make rich content from an emoji or a gemoji
• custom (Array<string>, default: defaultCustom) — custom gemoji names to enable without colons, such as ['shipit']; the default is to enable ±20 custom GitHub-specific shortcodes
• ignore (Test, default: defaultIgnore) — custom test for elements to not enhance; the default is to ignore pre, code, tt, and g-emoji

Authoring

If you want the text representation of an emoji, add VS 15 (\uFE0E) after it.

See § Writing on GitHub for more info.

HTML

The markup for known emoji on github.com used to be a g-emoji but is now just the unicide itself:

👍

For custom emoji, they generate:

<img class="emoji" title=":shipit:" alt=":shipit:" src="https://github.githubassets.com/images/icons/emoji/shipit.png" height="20" width="20" align="absmiddle">

You could generate a g-emoji and enhance custom element (such as with @github/g-emoji-element) or you can generate anything you want.

CSS

The following CSS is needed to make emoji markup look like GitHub.

.emoji {
  background-color: transparent;
  box-sizing: content-box;
  vertical-align: text-top;
}

Syntax

The syntax for emoji and gemoji cannot be captured in BNF. Or at least, it doesn’t get more readable than the source code. Check out lib/index.js for how things work!

Types

This package is fully typed with TypeScript. It exports the additional types Build, Gemoji, and Options.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 16+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with rehype-parse version 3+, rehype-stringify version 3+, rehype version 5+, and unified version 6+.

Security

This package is safe. The build option is unsafe when used with user content as it allows for arbitrary HTML.

Related

• remark-gfm — support GFM in remark

Contribute

See contributing.md in rehypejs/.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.

Notice

This project is not affiliated with GitHub.

License

MIT © Titus Wormer