hexo-filter-github-emojis/README.md

188 lines
4.8 KiB
Markdown
Raw Normal View History

2016-12-22 19:11:28 +08:00
# hexo-filter-github-emojis
[![Npm Version](https://img.shields.io/npm/v/hexo-filter-github-emojis.svg)](https://npmjs.org/package/hexo-filter-github-emojis)
2016-12-22 19:11:28 +08:00
[![Npm Downloads Month](https://img.shields.io/npm/dm/hexo-filter-github-emojis.svg)](https://npmjs.org/package/hexo-filter-github-emojis)
[![Npm Downloads Total](https://img.shields.io/npm/dt/hexo-filter-github-emojis.svg)](https://npmjs.org/package/hexo-filter-github-emojis)
[![License](https://img.shields.io/npm/l/hexo-filter-github-emojis.svg)](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
2018-10-04 19:07:24 +08:00
inject: true
2017-06-26 15:52:34 +08:00
styles:
2018-10-04 19:07:24 +08:00
customEmojis:
2016-12-22 19:11:28 +08:00
```
2020-10-03 11:10:42 +08:00
- **enable** `boolean=true` - Enable `::` emoji parsing. If off the [tag](#tag) and [helper](#helper) still work.
2016-12-22 19:11:28 +08:00
2020-10-03 11:10:42 +08:00
- **className** `string="github-emoji"` - Emoji class name.
For example :sparkles: `:sparkles:` the filter will generate something like this:
2016-12-23 01:02:51 +08:00
```html
2020-10-03 11:10:42 +08:00
<span class="github-emoji"><span>&#x2728;</span><img src="https://assets-cdn.github.com/images/icons/emoji/unicode/2728.png?v8"></span>
2016-12-23 01:02:51 +08:00
```
2020-10-03 11:10:42 +08:00
- **inject** `boolean=true` - Inject emoji styles and fallback script.
2020-10-03 11:34:27 +08:00
If `true`, the filter will inject a `<style>` to the html.
2020-10-03 11:10:42 +08:00
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.
2018-10-04 19:07:24 +08:00
2020-10-03 11:10:42 +08:00
Below is the injected `<style>`. The class name changes according to option.
2018-10-04 19:07:24 +08:00
```html
2020-10-03 11:10:42 +08:00
<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>
2016-12-23 01:02:51 +08:00
```
2020-10-03 11:10:42 +08:00
- **styles** `object={}` - inline styles. For example:
2017-06-26 15:52:34 +08:00
```yaml
githubEmojis:
styles:
2018-10-04 19:07:24 +08:00
font-size: 2em
font-weight: bold
2017-06-26 15:52:34 +08:00
```
outputs:
```html
2020-10-03 11:10:42 +08:00
<span class="github-emoji" style="font-size:2em;font-weight:bold" ...>
2017-06-26 15:52:34 +08:00
```
2020-10-03 11:10:42 +08:00
- **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.
2016-12-23 18:46:01 +08:00
For example:
2016-12-23 18:50:32 +08:00
```yaml
2016-12-23 18:46:01 +08:00
githubEmojis:
2018-10-04 19:07:24 +08:00
customEmojis:
2016-12-23 18:46:01 +08:00
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:
2016-12-23 18:50:32 +08:00
```yaml
2016-12-23 18:46:01 +08:00
githubEmojis:
2018-10-04 19:07:24 +08:00
customEmojis:
2016-12-23 18:46:01 +08:00
man_juggling:
2016-12-23 18:50:32 +08:00
src: https://path/to/man_juggling.png
2016-12-23 18:46:01 +08:00
codepoints: ["1f939", "2642"]
arrow_right: https://path/to/arrow_right.png
```
2017-06-26 15:52:34 +08:00
## Tag
If you do not like the `::`-style keywords, you can always use tags:
```html
{% github_emoji sparkles %}
```
2018-01-05 14:30:59 +08:00
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
2020-10-03 11:10:42 +08:00
<h1><%- github_emoji('octocat') %></h1>
```
2020-10-03 11:21:03 +08:00
## Fancybox
If you are using theme that enables fancybox(e.g. the default landscape theme) it is recommended to skip the github emoji imgs.
Edit `themes/landscape/source/script.js`
```diff
// Caption
$('.article-entry').each(function(i){
$(this).find('img').each(function(){
if ($(this).parent().hasClass('fancybox')) return;
+ if ($(this).parent().hasClass('github-emoji')) return;
var alt = this.alt;
if (alt) $(this).after('<span class="caption">' + alt + '</span>');
$(this).wrap('<a href="' + this.src + '" title="' + alt + '" class="fancybox"></a>');
});
$(this).find('.fancybox').each(function(){
$(this).attr('rel', 'article' + i);
});
});
```
2016-12-22 19:11:28 +08:00
[ghemojis]: https://api.github.com/emojis