Jemoji is a Jekyll plugin that converts GitHub-flavored emoji shortcodes like :+1: into emoji image tags in static sites, maintained by the Jekyll organization. It integrates into Jekyll's build pipeline to replace emoji codes such as :smile: with <img> tags that point to emoji image files, making it the standard way to display GitHub-style emoji on Jekyll-powered sites.
What is Jemoji?
Jemoji is a Ruby gem that acts as a Jekyll plugin, processing page and post content during site generation to replace emoji shortcodes with image tags. It takes Markdown or HTML content containing GitHub-style emoji shortcodes as input, and produces static HTML where each shortcode is replaced by an <img> tag referencing an emoji image. The plugin runs on Jekyll sites, requires no JavaScript, and is used by adding a single line to the site's Gemfile and declaring it in _config.yml under plugins.
What makes Jemoji stand out?
- GitHub-native emoji — Uses the Gemoji library to map GitHub's full set of emoji shortcodes to their corresponding Unicode images, ensuring consistency with GitHub.com.
- CDN-based images by default — For GitHub Pages sites, emoji images are served from
https://github.githubassets.com, producing URLs likehttps://github.githubassets.com/images/icons/emoji/unicode/1f604.png. - GitHub Enterprise support — On GitHub Enterprise, the build receives an
ASSET_HOST_URLenvironment variable, and Jemoji uses it to construct image URLs such ashttps://assets.ghe.my-company.com/images/icons/emoji/unicode/1f604.png. - Customizable source — You can serve emoji locally or from a custom source by setting an
emoji.srcpath in_config.yml, for exampleemoji: { src: "/assets/images/emoji" }. - Simple installation — Works with Jekyll 3.5.0 and newer through the
pluginskey; older Jekyll versions use thegemskey instead. - No runtime dependencies — Emoji are converted at build time, so the generated site has no extra JavaScript or external requests beyond the emoji images themselves.
Who should use Jemoji?
- Jekyll site developers — Anyone building a static site with Jekyll who wants to use GitHub's standard emoji set without hand-coding image tags.
- GitHub Pages users — Site owners publishing with GitHub Pages get emoji images served from GitHub's own CDN automatically, with no additional configuration.
- Enterprise GitHub users — Teams on GitHub Enterprise can use Jemoji to serve emoji from their enterprise asset host, keeping images within their own infrastructure.
- Blog authors — Writers using Jekyll for blogs can type
:smile:and:+1:in Markdown and have the emoji render correctly in the published post.
What can you do with Jemoji?
- Add emoji to posts and pages — Write emoji shortcodes like
:rocket:directly in Markdown and they become image tags in the generated HTML. - Serve emoji from your own domain — Configure a custom emoji source path to host emoji images locally, useful for offline sites or privacy-conscious deployments.
- Maintain consistent branding — Use a custom set of emoji images to match your site's visual identity, since the
emoji.srcconfig lets you point to any directory of emoji PNGs.
How does Jemoji work?
Add gem 'jemoji' to your site's Gemfile, then add plugins: [jemoji] to your _config.yml (or gems: [jemoji] for Jekyll versions below 3.5.0). After that, any emoji shortcode you write in a page or post is replaced with the corresponding image tag during the Jekyll build process.
FAQ
How do I install Jemoji?
Add the gem to your Gemfile with gem 'jemoji', then register it as a plugin in _config.yml under the plugins key (or gems key for Jekyll versions before 3.5.0). Run bundle install and your site will process emoji shortcodes on the next build.
Does Jemoji work with GitHub Pages?
Yes. For sites built on GitHub.com, Jemoji automatically uses the GitHub CDN at https://github.githubassets.com to serve emoji images, so there's no configuration required beyond installing the plugin.
Can I use custom emoji images with Jemoji?
Yes. Set an emoji.src path in your _config.yml to point to a local directory or custom URL where your emoji images are stored. The Gemoji documentation provides guidance on generating the necessary image files.
What Jekyll versions are supported?
Jemoji works with Jekyll 3.5.0 and later when listed under the plugins key. For older Jekyll versions, use the gems key instead. The plugin relies on Jekyll's plugin mechanism, which has been available since Jekyll 3.0.
Does Jemoji affect page load speed?
Emoji images are loaded from an external CDN by default, which adds one HTTP request per unique emoji per page. However, since the images are served from a fast CDN and the conversion happens at build time, there is no client-side JavaScript overhead.
