rehype plugin to enhance emoji and gemoji
npm install rehype-github-emoji[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]
[rehype][] plugin to enhance emoji and gemoji.
* 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
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][monorepo].
See its readme for more info.
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.
This package is [ESM only][esm].
In Node.js (version 16+),
install with [npm][]:
``sh`
npm install rehype-github-emoji
In Deno with [esm.sh][esmsh]:
`js`
import rehypeGithubEmoji from 'https://esm.sh/rehype-github-emoji@1'
In browsers with [esm.sh][esmsh]:
`html`
Say our module example.js looks as follows:
`js
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:
`html`
π
This package exports the identifiers
[defaultBuild][api-default-build],defaultCustom
[][api-default-custom],defaultIgnore
and
[][api-default-ignore].rehypeGithubEmoji
The default export is
[][api-rehype-github-emoji].
The default builder to turn an emoji or gemoji into rich content.
###### Parameters
* info ([Gemoji][api-gemoji] or string)value
β info on the known emoji or gemoji,
or the custom gemoji name
* (string)
β literal match the way it was written
###### Returns
Markup for the emoji or gemoji ([Element][element]).
Default custom gemoji names (Array).
Default tests for elements to not enhance (Array).
Plugin to enhance emoji and gemoji.
###### Parameters
* options ([Options][api-options], optional)
β configuration
Make rich content from an emoji or a gemoji (TypeScript type).
###### Parameters
* info ([Gemoji][api-gemoji] or string)value
β info on the known emoji or gemoji,
or the custom gemoji name
* (string)
β literal match the way it was written
###### Returns
Rich content ([ElementContent][element],Array,false).
Info on an emoji (TypeScript type).
###### Fields
* emoji (string)'π'
β example: names
* (Array)['grinning']
β example: tags
* (Array)['smile', 'happy']
β example: description
* (string)'grinning face'
β example: category
* (string)'Smileys & Emotion'
β example:
Configuration (TypeScript type).
###### Fields
* build ([Build][api-build],defaultBuild
default: [][api-default-build])custom
β make rich content from an emoji or a gemoji
* (Array,defaultCustom
default: [][api-default-custom])['shipit']
β custom gemoji names to enable without colons,
such as ;ignore
the default is to enable Β±20 custom GitHub-specific shortcodes
* ([Test][test],defaultIgnore
default: [][api-default-ignore])pre
β custom test for elements to not enhance;
the default is to ignore , code, tt, and g-emoji
If you want the text representation of an emoji,
add VS 15 (\uFE0E) after it.
See [Β§ Writing on GitHub][github-docs] for more info.
The markup for known emoji on github.com used to be a g-emoji but is now
just the unicide itself:
`html`
π
For custom emoji,
they generate:
`html`![]()
You could generate a g-emoji and enhance custom element@github/g-emoji-element
(such as with [][g-emoji])
or you can generate anything you want.
The following CSS is needed to make emoji markup look like GitHub.
`css`
.emoji {
background-color: transparent;
box-sizing: content-box;
vertical-align: text-top;
}
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!
This package is fully typed with [TypeScript][].
It exports the additional types [Build][api-build],Gemoji
[][api-gemoji],Options
and [][api-options].
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+,unified
and version 6+.
This package is safe.
The build option is unsafe when used with user content as it allows for
arbitrary HTML.
* remark-gfm
β support GFM in remark
See [contributing.md in rehypejs/.github][contributing] for ways to getsupport.md`][support] for ways to get help.
started.
See [
This project has a [code of conduct][coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
This project is not affiliated with GitHub.
[MIT][license] Β© [Titus Wormer][author]
[build-badge]: https://github.com/rehypejs/rehype-github/workflows/main/badge.svg
[build]: https://github.com/rehypejs/rehype-github/actions
[coverage-badge]: https://img.shields.io/codecov/c/github/rehypejs/rehype-github.svg
[coverage]: https://codecov.io/github/rehypejs/rehype-github
[downloads-badge]: https://img.shields.io/npm/dm/rehype-github-emoji.svg
[downloads]: https://www.npmjs.com/package/rehype-github-emoji
[size-badge]: https://img.shields.io/bundlephobia/minzip/rehype-github-emoji.svg
[size]: https://bundlephobia.com/result?p=rehype-github-emoji
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
[collective]: https://opencollective.com/unified
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
[chat]: https://github.com/rehypejs/rehype/discussions
[npm]: https://docs.npmjs.com/cli/install
[esmsh]: https://esm.sh
[license]: ../../license
[author]: https://wooorm.com
[contributing]: https://github.com/rehypejs/.github/blob/main/contributing.md
[support]: https://github.com/rehypejs/.github/blob/main/support.md
[coc]: https://github.com/rehypejs/.github/blob/main/code-of-conduct.md
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[typescript]: https://www.typescriptlang.org
[monorepo]: https://github.com/rehypejs/rehype-github
[rehype]: https://github.com/rehypjs/rehype
[element]: https://github.com/syntax-tree/hast#element
[test]: https://github.com/syntax-tree/hast-util-is-element/tree/main#test
[github-docs]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#using-emoji
[g-emoji]: https://github.com/github/g-emoji-element#readme
[api-build]: #build
[api-default-build]: #defaultbuildinfo-value
[api-default-custom]: #defaultcustom
[api-default-ignore]: #defaultignore
[api-gemoji]: #gemoji
[api-options]: #options
[api-rehype-github-emoji]: #rehypegithubemojioptions