{"id":7742,"library":"sphinx-substitution-extensions","title":"Sphinx Substitution Extensions","description":"Sphinx Substitution Extensions enhances Sphinx documentation by enabling variable substitutions within standard directives like `code-block`, `literalinclude`, and `image`, and introduces an inline `substitution-code` role. It supports both reStructuredText (reST) and MyST Markdown syntax for defining and using substitutions. The project maintains a frequent release cadence, often with multiple updates per month, ensuring continuous improvements and compatibility.","status":"active","version":"2026.1.12","language":"en","source_language":"en","source_url":"https://github.com/adamtheturtle/sphinx-substitution-extensions","tags":["Sphinx","documentation","reStructuredText","Markdown","substitutions","extensions","code-blocks"],"install":[{"cmd":"pip install sphinx-substitution-extensions","lang":"bash","label":"Basic Installation"},{"cmd":"pip install sphinx-substitution-extensions[prompt]","lang":"bash","label":"With sphinx-prompt integration"}],"dependencies":[{"reason":"Core documentation generator","package":"Sphinx","optional":false},{"reason":"Underlying text processing system for reStructuredText, a core Sphinx dependency","package":"docutils","optional":false},{"reason":"Runtime type checking dependency","package":"beartype","optional":false},{"reason":"Required for MyST Markdown support","package":"myst-parser","optional":true},{"reason":"Required for the `prompt` directive with substitutions","package":"sphinx-prompt","optional":true}],"imports":[{"note":"Add to the `extensions` list in `conf.py` to enable the extension.","symbol":"sphinx_substitution_extensions","correct":"extensions = [\n    # other extensions...\n    'sphinx_substitution_extensions',\n]"}],"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_substitution_extensions',\n]\n\n# Define substitutions for reStructuredText\nrst_prolog = '''\n.. |project_name| replace:: My Awesome Project\n.. |version| replace:: 1.0.0\n'''\n\n# Optional: Enable substitutions by default for applicable directives\nsubstitutions_default_enabled = True\n\n# .rst file (e.g., index.rst)\n# .. code-block:: python\n#    print(\"Welcome to |project_name| version |version|!\")\n\n# .rst file (e.g., index.rst) - manual substitution flag\n# .. code-block:: bash\n#    :substitutions:\n#\n#    echo \"Hello from |project_name|\"\n\n# .rst file (e.g., index.rst) - inline substitution\n# :substitution-code:`echo \"Installed version: |version|\"`\n\n# For MyST Markdown (if myst-parser is installed)\n# myst_enable_extensions = [\"substitution\"]\n# myst_substitutions = {\n#     \"project_name\": \"My Awesome Project\",\n#     \"version\": \"1.0.0\",\n# }\n#\n# In a .md file:\n# ```{code-block} bash\n# :substitutions:\n# echo \"Hello from {{project_name}}\"\n# ```\n#\n# In a .md file - inline substitution:\n# {substitution-code}`echo \"Installed version: {{version}}\"`\n","lang":"python","description":"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."},"warnings":[{"fix":"In `conf.py`, set `extensions = ['sphinx-prompt', 'sphinx_substitution_extensions', ...]`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `: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.","message":"Substitutions 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade Sphinx to 8.2.0 or newer and ensure your Python environment is 3.11+.","message":"This 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.","severity":"breaking","affected_versions":"<2026.1.12 (for Sphinx versions), all versions (for Python 3.10)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `sphinx_substitution_extensions` is enabled in `conf.py`. For reStructuredText, either add the `:substitutions:` option to the `code-block` directive (e.g., `.. code-block:: python :substitutions:`) or set `substitutions_default_enabled = True` in `conf.py`. For MyST Markdown, use the `{{VAR}}` syntax and ensure `:substitutions:` is present.","cause":"Sphinx's native `code-block` directive does not process reStructuredText substitutions by default, leading to placeholders like `|VAR|` or `{{VAR}}` appearing literally.","error":"Substitutions inside Sphinx code blocks aren't replaced / Variable substitution not working properly in Sphinx"},{"fix":"Run `pip install sphinx-substitution-extensions` to ensure the package is installed. Then, verify that `sphinx_substitution_extensions` is correctly listed as a string in the `extensions` list within your `conf.py` file.","cause":"The extension module `sphinx_substitution_extensions` could not be found or loaded by Sphinx. This typically means it was not installed or incorrectly added to the `extensions` list.","error":"Sphinx error: 'sphinx_substitution_extensions' is not a Sphinx extension"},{"fix":"Modify your `conf.py` to ensure `sphinx-prompt` appears before `sphinx_substitution_extensions` in the `extensions` list. Example: `extensions = ['sphinx-prompt', 'sphinx_substitution_extensions', ...]`","cause":"The `sphinx_substitution_extensions` library requires `sphinx-prompt` to be loaded first if both are used, due to how they interact or extend Sphinx's parsing. The order in the `extensions` list in `conf.py` is incorrect.","error":"Configuration error: 'sphinx-prompt' must be loaded before 'sphinx_substitution_extensions'"}]}