Sphinx Emoji Codes

Common errors

• Package inputenc Error: Unicode character 🚚 (U+1F69A) (inputenc) not set up for use with LaTeX.

  cause The default LaTeX engine (pdfLaTeX) often struggles with direct Unicode emoji characters, especially when not explicitly configured with appropriate packages or a Unicode-friendly engine.
  fix In `conf.py`, set `latex_engine = 'xelatex'` or `latex_engine = 'lualatex'`. Ensure these engines are installed and available in your LaTeX distribution. Alternatively, use `sphinxemoji_style = 'twemoji'` to render emojis as images.

• Sphinx build fails with an error related to `SphinxComponentRegistry.create_source_parser` or `Cannot import name 'create_source_parser' from 'sphinx.util.parsers'`.

  cause You are likely using Sphinx v9, which introduced breaking changes to its internal API, specifically how source parsers are registered and created. `sphinxemoji` versions prior to a compatible update do not support this new API.
  fix Upgrade `sphinxemoji` to its latest version (if a v9-compatible release exists). If not, temporarily downgrade your Sphinx installation to a version below 9.x (e.g., `pip install 'Sphinx<9'`).

• SyntaxError: invalid syntax in conf.py or unexpected keyword 'sphinxemoji.sphinxemoji'

  cause The `extensions` list in `conf.py` is Python code, and improper formatting (e.g., missing commas, incorrect quotes, or direct `import` statements) will cause a `SyntaxError` during the Sphinx build process.
  fix Ensure that `extensions = ['sphinxemoji.sphinxemoji']` (or `extensions.append('sphinxemoji.sphinxemoji')`) is correctly formatted within your `conf.py` file, respecting Python list syntax.

Warnings

• breaking sphinxemoji version 0.3.2 (and earlier) is incompatible with Sphinx v9 due to changes in `SphinxComponentRegistry.create_source_parser`.
  Fix: Check for an updated version of sphinxemoji that explicitly supports Sphinx v9. If unavailable, pin your Sphinx dependency to a version prior to 9.x (e.g., `pip install Sphinx<9`).
• gotcha Building documentation to PDF via LaTeX can result in `inputenc Error: Unicode character ... not set up for use with LaTeX` if your LaTeX distribution or configuration does not properly handle Unicode emojis.
  Fix: Configure Sphinx to use a Unicode-aware LaTeX engine (e.g., XeLaTeX or LuaLaTeX) by setting `latex_engine` in `conf.py`, or ensure your LaTeX preamble includes packages for Unicode support. Alternatively, consider setting `sphinxemoji_style = 'twemoji'` to render emojis as images, which are generally more compatible with LaTeX.
• gotcha Users on Windows might encounter `encoding` errors when `sphinxemoji.py` attempts to load its `codes.json` file.
  Fix: This issue might require a manual modification to the `sphinxemoji.py` file in your `site-packages` directory to specify UTF-8 encoding when opening the JSON file. (e.g., `open(..., encoding='utf-8')`).

Install

• pip install sphinxemoji Install latest version

Imports

• sphinxemoji
  wrong:

  import sphinxemoji # Not directly imported in Python code

  correct:

  extensions = ['sphinxemoji.sphinxemoji'] # In conf.py

  sphinxemoji is enabled as a string in Sphinx's conf.py configuration, not directly imported as a Python module in your project's code.

Quickstart

To quickly enable `sphinxemoji`, add `'sphinxemoji.sphinxemoji'` to your `extensions` list in `conf.py`. Then, you can use emoji shortcodes wrapped in bars (e.g., `|:smile:|`) directly in your reStructuredText or MyST files. An optional `sphinxemoji_style` configuration can be added to `conf.py` to use a consistent emoji set like Twemoji.

# conf.py
extensions = [
    'sphinxemoji.sphinxemoji',
]

# Your RST or MyST file (e.g., index.rst or index.md)
# This text includes a smiley face |:smile:| and a snake too! |:snake:|
# Don't you love it? |:heart_eyes:|

# Optional: Set a consistent emoji style (e.g., Twemoji)
# sphinxemoji_style = 'twemoji'