rehype-github-emoji v1.0.0
rehype-github-emoji
rehype plugin to enhance emoji and gemoji.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- 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
orstring
) β info on the known emoji or gemoji, or the custom gemoji namevalue
(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
orstring
) β info on the known emoji or gemoji, or the custom gemoji namevalue
(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 gemojicustom
(Array<string>
, default:defaultCustom
) β custom gemoji names to enable without colons, such as['shipit']
; the default is to enable Β±20 custom GitHub-specific shortcodesignore
(Test
, default:defaultIgnore
) β custom test for elements to not enhance; the default is to ignorepre
,code
,tt
, andg-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
7 months ago