161 lines
4.1 KiB
Markdown
161 lines
4.1 KiB
Markdown
# hexo-filter-github-emojis
|
|
|
|
[](https://npmjs.org/package/hexo-filter-github-emojis)
|
|
[](https://npmjs.org/package/hexo-filter-github-emojis)
|
|
[](https://npmjs.org/package/hexo-filter-github-emojis)
|
|
[](https://npmjs.org/package/hexo-filter-github-emojis)
|
|
|
|
A Hexo plugin that adds emoji support, using [Github Emojis API][ghemojis].
|
|
|
|
Check out the [Emoji Cheat Sheet](http://www.webpagefx.com/tools/emoji-cheat-sheet/) for all the emojis it supports.
|
|
|
|
## Installation
|
|
|
|
``` bash
|
|
$ npm install hexo-filter-github-emojis --save
|
|
```
|
|
|
|
## Options
|
|
|
|
You can configure this plugin in `_config.yml`. Default options:
|
|
|
|
``` yaml
|
|
githubEmojis:
|
|
enable: true
|
|
className: github-emoji
|
|
inject: true
|
|
styles:
|
|
customEmojis:
|
|
```
|
|
|
|
- **enable** `boolean=true` - Enable `::` emoji parsing. If off the [tag](#tag) and [helper](#helper) still work.
|
|
|
|
- **className** `string="github-emoji"` - Emoji class name.
|
|
For example :sparkles: `:sparkles:` the filter will generate something like this:
|
|
|
|
```html
|
|
<span class="github-emoji"><span>✨</span><img src="https://assets-cdn.github.com/images/icons/emoji/unicode/2728.png?v8"></span>
|
|
```
|
|
|
|
- **inject** `boolean=true` - Inject emoji styles and fallback script.
|
|
If `true`, the filter will inject a `<style>` to document `<head>`.
|
|
If `false`, the filter will not inject any style. If you can modify source style files you may turn this off and add them yourself.
|
|
|
|
Below is the injected `<style>`. The class name changes according to option.
|
|
|
|
```html
|
|
<style>
|
|
.github-emoji {
|
|
position: relative;
|
|
display: inline-block;
|
|
width: 1.2em;
|
|
min-height: 1.2em;
|
|
overflow: hidden;
|
|
vertical-align: top;
|
|
color: transparent;
|
|
}
|
|
|
|
.github-emoji > span {
|
|
position: relative;
|
|
z-index: 10;
|
|
}
|
|
|
|
.github-emoji img,
|
|
.github-emoji .fancybox {
|
|
margin: 0 !important;
|
|
padding: 0 !important;
|
|
border: none !important;
|
|
outline: none !important;
|
|
text-decoration: none !important;
|
|
user-select: none !important;
|
|
cursor: auto !important;
|
|
}
|
|
|
|
.github-emoji img {
|
|
height: 1.2em !important;
|
|
width: 1.2em !important;
|
|
position: absolute !important;
|
|
left: 50% !important;
|
|
top: 50% !important;
|
|
transform: translate(-50%, -50%) !important;
|
|
user-select: none !important;
|
|
cursor: auto !important;
|
|
}
|
|
|
|
.github-emoji-fallback {
|
|
color: inherit;
|
|
}
|
|
|
|
.github-emoji-fallback img {
|
|
opacity: 0 !important;
|
|
}
|
|
</style>
|
|
```
|
|
|
|
- **styles** `object={}` - inline styles. For example:
|
|
|
|
```yaml
|
|
githubEmojis:
|
|
styles:
|
|
font-size: 2em
|
|
font-weight: bold
|
|
```
|
|
|
|
outputs:
|
|
|
|
```html
|
|
<span class="github-emoji" style="font-size:2em;font-weight:bold" ...>
|
|
```
|
|
|
|
- **customEmojis** `object={}` - You can specify your own list. An object or JSON string is valid. The filter will first check the `customEmojis` then fallback to the [Github Emojis][ghemojis] list.
|
|
|
|
For example:
|
|
|
|
```yaml
|
|
githubEmojis:
|
|
customEmojis:
|
|
arrow_left: https://path/to/arrow_left.png
|
|
arrow_right: https://path/to/arrow_right.png
|
|
```
|
|
|
|
If you need to add code points that are not in the Github list, you can do this:
|
|
|
|
```yaml
|
|
githubEmojis:
|
|
customEmojis:
|
|
man_juggling:
|
|
src: https://path/to/man_juggling.png
|
|
codepoints: ["1f939", "2642"]
|
|
arrow_right: https://path/to/arrow_right.png
|
|
```
|
|
|
|
## Tag
|
|
|
|
If you do not like the `::`-style keywords, you can always use tags:
|
|
|
|
```html
|
|
{% github_emoji sparkles %}
|
|
```
|
|
|
|
Add `no-emoji: true` to front-matter to stop replacing `::`:
|
|
|
|
```md
|
|
---
|
|
title: Hello World
|
|
no-emoji: true
|
|
---
|
|
|
|
:tada: as it is.
|
|
|
|
{% github_emoji tada %} still works.
|
|
```
|
|
|
|
## Helper
|
|
|
|
You can also render a GitHub emoji from a template using the `github_emoji` helper:
|
|
|
|
```html
|
|
<h1><%- github_emoji('octocat') %></h1>
|
|
```
|
|
|
|
[ghemojis]: https://api.github.com/emojis
|