emoji-shortname

Replace emoji short names with their corresponding emojis.

Overview

The short names we are familiar with (e.g. the ones used on sites like GitHub) are not inline with the CLDR short names defined in the Unicode standard. This makes mapping short codes to emojis a bit of a challenge. So, I punt on this issue, and defer to the emoji package created by Taehoon Kim and Kevin Wurster. Their wonderful library does the heavy lifting.

This extension amounts to a find-and-replace. Find the short name, replace it with the appropriate emoji. It works with both Markdown and reStructuredText.

Details

Emojis are added to documents by sandwiching their short names between colons. For example, :smile: resolves to :smile:. This syntax conflicts with the way you provide options to directives in Sphinx. And, since the extension ties into the source-read hook, those directives are yet to be resolved. As such, if an option shares the same name as an emoji short code, the option will be replaced by the emoji. Though I am unaware of any case where this happens, be aware that it is a possibility.

Development

The project is managed with poetry.

To contribute to emoji-shortname, first install poetry. Once installed, fetch the project dependencies with poetry install. From here, you can iterate on the code and run the unit tests with poetry run tox pyproject.toml

Usage

Simply install the package with your manager of choice (e.g. poetry, pip, etc) and then add the extension to your sphinx config.py.

extensions = ["emoji_shortname"]