Enhancement: Move emoji short code to separate plugin

[jhildenbiddle]

👉 Note: This is a post-v5 feature request (see Milestone)

Feature request

1. Remove emoji short code support from Docsify core bundle
2. Create a new emoji official plugin:
   • Provide short code support (e.g., :+1: = 👍)
   • Provides ability to render native emoji characters or GitHub-style emoji images

Proposal

Significantly reduce the file size of the core Docsify library by removing emoji short code support and instead offering it as an official plugin.

• Docsify with emoji short code support: 164KB (minified)
• Docsify without emoji short code support: 94KB (minified)

Removing short code support (/src/core/render/emoji-data.js) provides a 53% reduction in the minified Docsify.js bundle size.

An official Docsify emoji plugin would provide both short code support (e.g., :+1: = 👍) and the ability to render GitHub-style emoji images instead of OS-native emoji characters for those who want consistent emoji across all platforms (as Docsify v4 does today by default).

IMPORTANT: Removing short code support does not mean Docsify will be unable to render emoji without the plugin. This change only requires markdown authors to use their OS-native emoji picker to add emoji to their markdown documents instead of short codes. Those emoji will work as expected in Docsify, GitHub, and in other markdown applications, which arguably makes their markdown more portable since not all markdown environments support GitHub short codes.

For context...

Docsify's emoji short code support has been included in Docsify since v4 was released in 2017. This was a convenient way for those familiar with GitHub short codes to render emoji in their Docsify sites. More importantly, it was also the only way for Windows and Ubuntu users to easily add emoji to their Docsify and GitHub-flavored markdown because those operating systems lacked a native emoji picker:

• MacOS emoji picker: released ~2013
• Windows emoji picker: released ~2020
• Ubuntu emoji picker: released ~2018

Thankfully, all major operating systems now support native emoji pickers which are easily accessible via a keyboard shortcut:

• Mac: Command + Control + Spacebar
  
• Windows: Win + .
  
• Ubuntu: Control + .
  

These native emoji pickers reduce--but do not eliminate--the need for emoji short codes because users can now easily add native emoji characters to their markdown documents.

[trusktr]

👍

[Koooooo-7]

Nice solution. 👍

And I think we should mention that this plugin recommend to use the latest version instead of @version (unlike the docsify itself) to get the latest emoji changes when we update the emojiData and do new release of this plugin.

[trusktr]

If it is published with Docsify, not a separate package, users will need to use the Docsify version. It will be easier to manage it that way instead of a separate package. F.e. it would be in here: https://unpkg.com/browse/docsify@4.13.1/lib/plugins/

Thoughts?

[Koooooo-7]

If it is published with Docsify, not a separate package, users will need to use the Docsify version. It will be easier to manage it that way instead of a separate package. F.e. it would be in here: https://unpkg.com/browse/docsify@4.13.1/lib/plugins/

Thoughts?

I think It can not published with Docsify since they have different releases purpose.

• When we have new changes and update for docsify --- Docsify release
• When the emojiData changes or plugin updates --- emoji plugin release

When user use the emoji-plugin@latest, they can always get the latest emoji data no matter which docsify version is used.

[trusktr]

That may be true unless at some point we change the plugin system in a breaking way. hmmm

[Koooooo-7]

That may be true unless at some point we change the plugin system in a breaking way. hmmm

Yes...The compatibility between the plugin and docsify is a qustion.
Or instead, we may recommend user to use the x version and we do the plugin or emojiData release follow the x.y.z semantic. They can access the latest suitable changes as well.

[jhildenbiddle]

When user use the emoji-plugin@latest, they can always get the latest emoji data no matter which docsify version is used.

I think we are best served by advising users to include consistent version locks in all of their CDN URLs specifically for the reason @trusktr mentioned:

...at some point we [may] change the plugin system in a breaking way

For sites using Docsify v5, all Docsify CDN URLs should contain at least a major @5 version lock in CDN URLs. When v6 is released, these sites will be unaffected because all CDN URLs contain @5. To update from v5 to v6, site admins will need to update all @5 URL version locks to @6. Easy.

If site admins want to mix-and-match bundles from different Docsify versions, there is nothing stopping them from doing so. For example, a v5 site could load the v6 emoji plugin using @6 in the emoji plugin CDN URL and @5 in all other Docsify URLs. If it works, great. If it breaks, that's not our issue to solve.

This approach is easy for us to explain, easy for users to understand, and it prevents sites from breaking when new versions are released. It's also how everyone's phone and computer emoji updates work: new emoji require an update; If you don't update, you don't get new emoji; and when a new major version of a platform is released (iOS 17 => 18, macOS 14 => 15, or Docsify 5 => 6) older versions typically stop receiving updates for things like new emoji so you probably want to upgrade if having the latest emoji is important.

[Koooooo-7]

Hi @jhildenbiddle .
My question is the version mapping from emoji-plugin to docsify.
Do you mean we gonna release the emoji-plugin from v5/vX (same to docsify) directly？
If all the changes follow docsify and no breaking changes, it will works and easy to maintain.
If not, we can not say when we release the emoji-plugin to v7, we need release the docsify to v7.

I suppose we should do the emoji-plugin release in the x.y.z rules and recommend users to use the @x version.
We provide a table in the emoji-plugin project.

emoji-plugin	docsify	emojiData last sync date
v1	<=v5	2025-05-20
v2	latest	now

[jhildenbiddle]

Do you mean we gonna release the emoji-plugin from v5/vX (same to docsify) directly？

Yes.

Until we have a reason to do otherwise, I think we should keep doing what we've been doing in v4: releasing plugin updates as part of each new Docsify release. I believe this is the simplest method of maintaining and publishing plugins for Docsify. The downside is that any time we want to publish a change to a plugin, we're forced to publish a new Docsify version. This sounds bad in theory, but in practice it hasn't been an issue at any point during Docsify v4 (that I am aware of).

An important benefit of bundling plugins with Docsify release is that all Docsify resource (library, plugins, and themes) are guaranteed to work together so long as a user's version locks are consistent (e.g., @5, @5.1, or @5.1.2). If we start releasing plugins independently with their own version numbers, this is no longer the true.

If all the changes follow docsify and no breaking changes, it will works and easy to maintain.
If not, we can not say when we release the emoji-plugin to v7, we need release the docsify to v7.

For Docsify, this feels more like a theoretical problem than a real-world one. It's far more likely that the driver of breaking changes and new major releases will be Docsify itself, not our plugins. Worst case scenario: breaking plugin changes just have to wait until the next major Docsify release. If this ever becomes an issue, we can re-evaluate our approach then.

[jhildenbiddle]

Adding another option to consider if/when this issue is worked on...

An emoji font (e.g. Noto Emoji) would be an interesting alternative to image-based emoji for consistent emoji across operating systems.

In addition to making this option available as part of our emoji plugin, we could also provide instructions for installing one of these fonts in our Quick Start guide for those who want consistent emoji but prefer not to use our emoji plugin for shortcode support to to optimize site performance.