sphinx-substitution-extensions

What it is and what it does

This package extends Sphinx with directives that perform variable substitution in documentation content. It works by registering new options (`:substitutions:`, `:content-substitutions:`, `:path-substitutions:`) on Sphinx's built-in directives like `code-block`, `literalinclude`, `include`, and `image`, plus adds new directives like `:substitution-code:` and `:substitution-download:`. Substitutions are defined in `conf.py` via `rst_prolog` for reStructuredText or `myst_substitutions` for MyST Markdown.

The package supports both reStructuredText and MyST Markdown syntax. Variables can be scoped globally (in `rst_prolog` or `myst_substitutions`) or per-document (in frontmatter for Markdown). By default, substitution flags must be added explicitly to each directive; a `substitutions_default_enabled` setting applies them automatically across all compatible directives. It depends on sphinx, docutils, myst-parser, and beartype, and requires Python 3.11 or later.

Use it for:

• Document version numbers and release dates that appear in code examples and download links without manual updates
• Replace author names, product names, or environment-specific values across code blocks and file paths in multi-author or multi-environment docs
• Generate dynamic file paths in `literalinclude` and `include` directives based on substitution variables
• Maintain consistent branding or configuration values in inline code snippets and hyperlink targets

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Adds substitution support to Sphinx directives, allowing variable replacement within code blocks, file paths, and other content during documentation builds.

Yes. Active maintenance, low install friction, no known vulnerabilities, and permissive MIT license. Install if you maintain Sphinx documentation with repeated variable values in code examples or file paths. Skip if your documentation is static and does not benefit from templating.

Install

sphinx-substitution-extensions on PyPI

pip install sphinx-substitution-extensions

uv add sphinx-substitution-extensions

poetry add sphinx-substitution-extensions

Installing sphinx-substitution-extensions

Before you install

Low friction install with a wheel distribution. Active maintenance as of 2026-08-14 with recent release. Depends on sphinx, docutils, myst-parser, and beartype—all standard documentation tooling.

License in practice

MIT license permits use in open-source and commercial projects with minimal restrictions; attribution required.

Quickstart

pip install sphinx-substitution-extensions

# In conf.py:
extensions = ["sphinx_substitution_extensions"]
rst_prolog = """
.. |version| replace:: 1.0
.. |author| replace:: Jane
"""

# In your .rst file:
.. code-block:: shell
   :substitutions:

   echo "|author| released |version|"

Requires Python 3.11 or later and Sphinx 8.2.0 or later.

Verify before relying

• Whether substitution syntax conflicts with existing Sphinx extensions in real projects
• Performance impact when substitutions_default_enabled is true on large documentation sets
• Exact scope of MyST Markdown support beyond the documented examples

Package facts

Evidence: sphinx_substitution_extensions-2026.8.13.1-py3-none-any.whl

Keywords: documentation, rst, sphinx

Tags

More Sphinx packages