feat: Native emoji w/ image-based fallbacks and improved parsing (#1746)

* Render native emoji with image fallback Fix #779 * Deprecate emoji plugin * Add emoji tests * Remove console.log statement * Fix emoji image alt attribute * Set nativeEmoji to false by default (non-breaking) * Fix parsing emoji in HTML comments and script tags * Add nativeEmoji and update noEmoji details * Add Emoji plugin deprecation notice * Fix ESLint issues * Create build:emoji task - Auto-generate emoji data from GitHub API - Auto-generate emoji markdown for website - Add emoji page to navigation * Fix rendering of GitHub emoji without unicode * Adjust and match size of native and image emoji * Update emoji test snapshot * Update docs test snapshot * Fix ci/codesandbox error * Update native emoji font-stack * Fix rendering of native multi-character emoji * Kick GitHub Workflow * Replace rollup’s uglify plugin with terser * Switch “npm ci” instead of “npm i” for stability * Change emoji data from default to named export * Revert "Replace rollup’s uglify plugin with terser" This reverts commit 7ba8513. * Revert "Switch “npm ci” instead of “npm i” for stability" This reverts commit d52b476. * Revert "Change emoji data from default to named export" This reverts commit 3f2dd46. * Specify codesandbox template and node version * Update codesandbox config * Revert "Revert "Replace rollup’s uglify plugin with terser"" This reverts commit e06fed4. * Revert "Revert "Revert "Replace rollup’s uglify plugin with terser""" This reverts commit 27d4952. * Update codesandbox config * Revert "Update codesandbox config" This reverts commit 5120dd2. * Fix codesandbox uglify error * Emoji docs tweaks * Restore and update emoji plugin code * Restore and update emoji plugin docs * Prettier updates * Match lowercase shortcodes only Co-authored-by: Koy Zhuang <369491420@qq.com>

.codesandbox/ci.json

@@ -1,4 +1,5 @@
 {
  "sandboxes": ["2d17z"],
- "packages": [".", "packages/docsify-server-renderer"]
+ "packages": [".", "packages/docsify-server-renderer"],
+ "node": "16"
 }

build/emoji.js

@@ -0,0 +1,91 @@
+const axios = require('axios');
+const fs = require('fs');
+const path = require('path');
+
+const filePaths = {
+ emojiMarkdown: path.resolve(process.cwd(), 'docs', 'emoji.md'),
+ emojiJS: path.resolve(
+ process.cwd(),
+ 'src',
+ 'core',
+ 'render',
+ 'emojify-data.js'
+ ),
+};
+
+async function getEmojiData() {
+ const emojiDataURL = 'https://api.github.com/emojis';
+ const response = await axios.get(emojiDataURL);
+ const baseURL = Object.values(response.data)
+ .find(url => /unicode\//)
+ .split('unicode/')[0];
+ const data = { ...response.data };
+
+ // Remove base URL from emoji URLs
+ Object.entries(data).forEach(
+ ([key, value]) => (data[key] = value.replace(baseURL, ''))
+ );
+
+ return {
+ baseURL,
+ data,
+ };
+}
+
+function writeEmojiPage(emojiData) {
+ const emojiPage =
+ (fs.existsSync(filePaths.emojiMarkdown) &&
+ fs.readFileSync(filePaths.emojiMarkdown, 'utf8')) ||
+ `<!-- START -->\n\n<!-- END -->`;
+ const emojiRegEx = /(<!--\s*START.*-->\n)([\s\S]*)(\n<!--\s*END.*-->)/;
+ const emojiMatch = emojiPage.match(emojiRegEx);
+ const emojiMarkdownStart = emojiMatch[1].trim();
+ const emojiMarkdown = emojiMatch[2].trim();
+ const emojiMarkdownEnd = emojiMatch[3].trim();
+ const newEmojiMarkdown = Object.keys(emojiData.data)
+ .reduce(
+ (preVal, curVal) =>
+ (preVal += `:${curVal}: ` + '`' + `:${curVal}:` + '`' + '\n\n'),
+ ''
+ )
+ .trim();
+
+ if (emojiMarkdown !== newEmojiMarkdown) {
+ const newEmojiPage = emojiPage.replace(
+ emojiMatch[0],
+ `${emojiMarkdownStart}\n${newEmojiMarkdown}\n${emojiMarkdownEnd}`
+ );
+
+ fs.writeFileSync(filePaths.emojiMarkdown, newEmojiPage);
+ console.info(`- Created new file: ${filePaths.emojiMarkdown}`);
+ } else {
+ console.info(`- No changes to file: ${filePaths.emojiMarkdown}`);
+ }
+}
+
+function writeEmojiJS(emojiData) {
+ const emojiJS =
+ fs.existsSync(filePaths.emojiJS) &&
+ fs.readFileSync(filePaths.emojiJS, 'utf8');
+ const newEmojiJS = `export default ${JSON.stringify(emojiData, {}, 2)}`;
+
+ if (!emojiJS || emojiJS !== newEmojiJS) {
+ fs.writeFileSync(filePaths.emojiJS, newEmojiJS);
+ console.info(`- Created new file: ${filePaths.emojiJS}`);
+ } else {
+ console.info(`- No changes to file: ${filePaths.emojiJS}`);
+ }
+}
+
+(async () => {
+ console.log('Build emoji');
+
+ try {
+ const emojiData = await getEmojiData();
+
+ writeEmojiPage(emojiData);
+ writeEmojiJS(emojiData);
+ } catch (e) {
+ console.error(e);
+ }
+})();

docs/_sidebar.md

@@ -13,6 +13,7 @@
  - [Write a Plugin](write-a-plugin.md)
  - [Markdown configuration](markdown.md)
  - [Language highlighting](language-highlight.md)
+ - [Emoji](emoji.md)
 
 - Guide
 

docs/configuration.md

@@ -16,7 +16,7 @@ The config can also be defined as a function, in which case the first argument i
 
 ```html
 <script>
- window.$docsify = function(vm) {
+ window.$docsify = function (vm) {
  return {
  markdown: {
  renderer: {
@@ -319,14 +319,14 @@ window.$docsify = {
  markdown: {
  smartypants: true,
  renderer: {
- link: function() {
+ link: function () {
  // ...
  },
  },
  },
 
  // function
- markdown: function(marked, renderer) {
+ markdown: function (marked, renderer) {
  // ...
  return marked;
  },
@@ -398,19 +398,97 @@ window.$docsify = {
 
 Note that if you are running an external script, e.g. an embedded jsfiddle demo, make sure to include the [external-script](plugins.md?id=external-script) plugin.
 
+## nativeEmoji
+
+- type: `Boolean`
+- default: `false`
+
+Render emoji shorthand codes using GitHub-style emoji images or platform-native emoji characters.
+
+```js
+window.$docsify = {
+ nativeEmoji: true,
+};
+```
+
+```markdown
+:smile:
+:partying_face:
+:joy:
+:+1:
+:-1:
+```
+
+GitHub-style images when `false`:
+
+<output data-lang="output">
+ <img class="emoji" src="https://github.githubassets.com/images/icons/emoji/unicode/1f604.png" alt="smile">
+ <img class="emoji" src="https://github.githubassets.com/images/icons/emoji/unicode/1f973.png" alt="partying_face">
+ <img class="emoji" src="https://github.githubassets.com/images/icons/emoji/unicode/1f602.png" alt="joy">
+ <img class="emoji" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" alt="+1">
+ <img class="emoji" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" alt="-1">
+</output>
+
+Platform-native characters when `true`:
+
+<output data-lang="output">
+ <span class="emoji">😄︎</span>
+ <span class="emoji">🥳︎</span>
+ <span class="emoji">😂︎</span>
+ <span class="emoji">👍︎</span>
+ <span class="emoji">👎︎</span>
+</output>
+
+To render shorthand codes as text, replace `:` characters with the `&colon;` HTML entity.
+
+```markdown
+&colon;100&colon;
+```
+
+<output data-lang="output">
+
+&colon;100&colon;
+
+</output>
+
 ## noEmoji
 
 - type: `Boolean`
+- default: `false`
 
-Disabled emoji parse.
+Disabled emoji parsing and render all emoji shorthand as text.
 
 ```js
 window.$docsify = {
  noEmoji: true,
 };
 ```
 
-?> If this option is `false` but you don't want to emojify some specific colons, [refer to this](https://github.com/docsifyjs/docsify/issues/742#issuecomment-586313143)
+```markdown
+:100:
+```
+
+<output data-lang="output">
+
+&colon;100&colon;
+
+</output>
+
+To disable emoji parsing of individual shorthand codes, replace `:` characters with the `&colon;` HTML entity.
+
+```markdown
+:100:
+
+&colon;100&colon;
+```
+
+<output data-lang="output">
+
+:100:
+
+&colon;100&colon;
+
+</output>
 
 ## mergeNavbar
 
@@ -435,7 +513,7 @@ See https://github.com/lukeed/tinydate#patterns
 window.$docsify = {
  formatUpdated: '{MM}/{DD} {HH}:{mm}',
 
- formatUpdated: function(time) {
+ formatUpdated: function (time) {
  // ...
 
  return time;