{"id":7744,"library":"sphinxemoji","title":"Sphinx Emoji Codes","description":"Sphinx Emoji Codes (sphinxemoji) is a Sphinx extension that enables the use of emoji shortcodes (e.g., |:smile:|) directly within your Sphinx documentation. It is currently at version 0.3.2 and primarily releases updates to maintain compatibility with new Sphinx versions or to fix bugs.","status":"active","version":"0.3.2","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/emojicodes","tags":["sphinx","emoji","documentation","extension","reStructuredText"],"install":[{"cmd":"pip install sphinxemoji","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generator that sphinxemoji extends.","package":"Sphinx"},{"reason":"Requires Python 3.9 or higher for installation.","package":"Python","optional":true}],"imports":[{"note":"sphinxemoji is enabled as a string in Sphinx's conf.py configuration, not directly imported as a Python module in your project's code.","wrong":"import sphinxemoji # Not directly imported in Python code","symbol":"sphinxemoji","correct":"extensions = ['sphinxemoji.sphinxemoji'] # In conf.py"}],"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinxemoji.sphinxemoji',\n]\n\n# Your RST or MyST file (e.g., index.rst or index.md)\n# This text includes a smiley face |:smile:| and a snake too! |:snake:|\n# Don't you love it? |:heart_eyes:|\n\n# Optional: Set a consistent emoji style (e.g., Twemoji)\n# sphinxemoji_style = 'twemoji'","lang":"python","description":"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."},"warnings":[{"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`).","message":"sphinxemoji version 0.3.2 (and earlier) is incompatible with Sphinx v9 due to changes in `SphinxComponentRegistry.create_source_parser`.","severity":"breaking","affected_versions":"0.3.2 and older"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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')`).","message":"Users on Windows might encounter `encoding` errors when `sphinxemoji.py` attempts to load its `codes.json` file.","severity":"gotcha","affected_versions":"Potentially all versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Package inputenc Error: Unicode character 🚚 (U+1F69A) (inputenc) not set up for use with LaTeX."},{"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'`).","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.","error":"Sphinx build fails with an error related to `SphinxComponentRegistry.create_source_parser` or `Cannot import name 'create_source_parser' from 'sphinx.util.parsers'`."},{"fix":"Ensure that `extensions = ['sphinxemoji.sphinxemoji']` (or `extensions.append('sphinxemoji.sphinxemoji')`) is correctly formatted within your `conf.py` file, respecting Python list syntax.","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.","error":"SyntaxError: invalid syntax in conf.py or unexpected keyword 'sphinxemoji.sphinxemoji'"}]}