hugo-mod-twemoji 📦

Twemoji (Twitter Emoji) is an open-source library of every Unicode emoji (all 3,500+ of them!) uniquely redesigned in both SVG and PNG formats. It also provides a script to swap out system-native emojis for these graphics to achieve a uniform appearance across all browsers and platforms. 🙌

This Hugo Module can be used to import the Twemoji graphics and scripts locally into your Hugo project, rather than making external calls to Twitter's CDN for each individual icon.

🤖 Usage

Give the Hugo Modules documentation a read to prepare your project, and then add this module to your Hugo project's config.toml:

[module]
[[module.imports]]
  path = "github.com/jakejarvis/hugo-mod-twemoji"

The graphics will be mounted in static/twemoji/svg and static/twemoji/png, and the minified script in static/twemoji/js.

Before you start, you'll probably want to add Twitter's recommended CSS to your stylesheet to make sure the Twemojis match the size and alignment of the surrounding text — otherwise they'll be humongous:

img.emoji {
  height: 1em;
  width: 1em;
  margin: 0 .05em 0 .1em;
  vertical-align: -0.1em;
}

⚡ Quick Start

For a quick start, an optional partial template is mounted at layouts/partials/twemoji.html, which does everything described in the section below for you. Include this somewhere near the bottom of your base template, before </body>:

{{ partial "twemoji" . }}

⚙️ Manual

If you don't use the partial, you'll want to call the js/twemoji.min.js asset as a resource somewhere in your template or theme's <head>, for example:

{{ $twemoji := resources.Get "js/twemoji.min.js" }}
<script src="https://github.com/jakejarvis/hugo-mod-twemoji/raw/master/{{ $twemoji.Permalink }}"></script>

...and then in order to actually swap out the emojis, you need to call the script's twemoji.parse method. This is where you can choose between SVGs (recommended) or 72x72 PNGs and tell the script where we've placed the graphics. The official readme has a lot of information about the API, but a good starting point is this one-liner:

<script>
  twemoji.parse(document.body, {{ dict "base" ("twemoji/" | absURL) "folder" "svg" "ext" ".svg" | jsonify | safeJS }})
</script>

Simply change svg and .svg to png and .png respectively to use the provided 72x72 PNG icons instead.

After building the site this small script will turn into something like:

<script>
  twemoji.parse(document.body, {"base": "https://hugo-mod-twemoji.netlify.com/twemoji/", "ext": ".svg", "folder": "svg"})
</script>

🌎 Examples

https://jarv.is/ (Source)

📜 Licenses

Twemoji graphics are licensed under Creative Commons Attribution 4.0 International (CC-BY-4.0) by Twitter, Inc. and other contributors. Code (both Twitter's and this repository) is released under the MIT License.

Refer to the main Twemoji repository or website for more information.

jakejarvis / hugo-mod-twemoji

readme