Registry / sphinx-substitution-extensions
Install & Compatibility
Where this runs
tested against v2026.1.12 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 105.6MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 6.1s · import 0.000s · 107MB
106MB installed
● package 106MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx_substitution_extensions
✓ extensions = [
# other extensions...
'sphinx_substitution_extensions',
]
Add to the `extensions` list in `conf.py` to enable the extension.
To quickly integrate `sphinx-substitution-extensions`, add it to your `extensions` list in `conf.py`. Define your substitutions using `rst_prolog` for reStructuredText files or `myst_substitutions` for MyST Markdown. Then, use the `|KEY|` syntax in reST or `{{KEY}}` in MyST within directives that support substitutions (like `code-block` with the `:substitutions:` flag) or with the inline `:substitution-code:` role. Setting `substitutions_default_enabled = True` in `conf.py` applies substitutions to code blocks and literal includes without explicit flags.
# conf.py
extensions = [
'sphinx.ext.autodoc',
'sphinx_substitution_extensions',
]
# Define substitutions for reStructuredText
rst_prolog = '''
.. |project_name| replace:: My Awesome Project
.. |version| replace:: 1.0.0
'''
# Optional: Enable substitutions by default for applicable directives
substitutions_default_enabled = True
# .rst file (e.g., index.rst)
# .. code-block:: python
# print("Welcome to |project_name| version |version|!")
# .rst file (e.g., index.rst) - manual substitution flag
# .. code-block:: bash
# :substitutions:
#
# echo "Hello from |project_name|"
# .rst file (e.g., index.rst) - inline substitution
# :substitution-code:`echo "Installed version: |version|"`
# For MyST Markdown (if myst-parser is installed)
# myst_enable_extensions = ["substitution"]
# myst_substitutions = {
# "project_name": "My Awesome Project",
# "version": "1.0.0",
# }
#
# In a .md file:
# ```{code-block} bash
# :substitutions:
# echo "Hello from {{project_name}}"
# ```
#
# In a .md file - inline substitution:
# {substitution-code}`echo "Installed version: {{version}}"`
Debug
Known issues
gotchaWhen integrating with `sphinx-prompt`, ensure `sphinx-prompt` is listed *before* `sphinx_substitution_extensions` in your `conf.py` extensions list to prevent conflicts or incorrect behavior.fixIn `conf.py`, set `extensions = ['sphinx-prompt', 'sphinx_substitution_extensions', ...]`.
affects: All versions
gotchaSubstitutions are not applied by default to Sphinx's built-in `code-block` or `literalinclude` directives. You must explicitly add the `:substitutions:`, `:content-substitutions:`, or `:path-substitutions:` flags, or enable substitutions globally.fixAdd `:substitutions:` (or `content-/path-substitutions`) to the directive, or set `substitutions_default_enabled = True` in your `conf.py` to apply them automatically to all relevant directives.
affects: All versions
breakingThis library explicitly states compatibility with Sphinx versions 8.2.0+ and Python 3.11+ in its latest GitHub README and PyPI classifiers, despite PyPI metadata stating `requires_python: >=3.10`. Using older Sphinx versions or Python 3.10 might lead to unexpected issues or errors.fixUpgrade Sphinx to 8.2.0 or newer and ensure your Python environment is 3.11+.
affects: <2026.1.12 (for Sphinx versions), all versions (for Python 3.10)
Upgrade
Version history
2026.1.12latest on PyPI · released Jan 12, 2026
Audit
Dependencies
SphinxrequiredCore documentation generator
docutilsrequiredUnderlying text processing system for reStructuredText, a core Sphinx dependency
beartyperequiredRuntime type checking dependency
myst-parseroptionalRequired for MyST Markdown support
sphinx-promptoptionalRequired for the `prompt` directive with substitutions