Sphinx extension to use GitHub markdown emoji in Sphinx?

Question

Problem

I have been using (Python) Sphinx doc, along with CommonMark parser, to write Sphinx documentation containing files written in both reStructuredText and Markdown. So far so good, it works really fine (see this line in an example of Sphinx conf.py file).

However, CommonMark's support for GitHub flavored Markdown (GFM) is not perfect, and one important feature it lacks are emoji. I searched for other Markdown parser, more specific to GFM, for instance py-gfm, but none of them seem to support emoji.

For instance, the screenshot below shows the Sphinx output on the left, and the GitHub rendered version on the right:

So my question is:

• Does anyone know a Sphinx extension that could add support to GFM-like emoji, in rST and/or Markdown? (ie, emoji written like :boom: this).
• Or a trick I could use to convert any emoji, eg, :boom:, to a small image? (as that's what GitHub is doing anyway, see for instance the :boom: image) The trick should probably be on the HTML pages created by Sphinx, not on the source Markdown files (I want them to still be readable with GitHub file viewer).

Thanks in advance. Regards.

---

2 partial solutions

• A partial solution is this small Python script I wrote, using carpedm20's emoji package. It will convert any :emoji: alias (written :like_this:) to it's UTF-8 version, if possible.

• I also tried to use pymdownx.emoji package, to write this second script. It will convert any :emoji: alias to a piece of HTML code loading a distant PNG (or SVG) version (from JsDelivr's CDN). Still not perfect, the size/scaling is not good, and even emojis in ... are replaced. (I will improve this).

Both can be used with this tiny Bash for loop:

BUILDDIR=_build/html  # Adapt to the location of your Sphinx output
for i in "$BUILDDIR"/*.html; do
    emojize.py "$i" > "$i".new
    # or emojize_pngorsvg.py "$i" > "$i".new
    wdiff -3 "$i" "$i".new;
    mv -vf "$i".new "$i"
done

Demo:

• With UTF-8 codes for emojis:
• With PNG images for emojis (still not perfect):

Answer 1

You don't need to convert the emoji to a small image or use an extension, because Sphinx actually supports emoji as they're copy-pasted right out of the box.

If you copy any emoji and add it to a doc file, your editor might not show it correctly, but as long as the emoji was inserted it should show up in your doc.

Try it out with the siren emoji:

🚨

I know this works for reStructuredText files, so hopefully it should work for Markdown files too.

One thing to make this easier is to put substitutions for all the emoji you want to use in your rst_epilog for the reStructuredText files. This way you can use something like this in the epilog:

.. |siren| replace:: 🚨 

Every time you'd want to use a siren in your reStructuredText documents, you just use |siren|.