{"id":2774,"library":"sphinx-jinja","title":"Sphinx Jinja","description":"Sphinx Jinja is a Python library that enables the embedding of Jinja2 templates directly within Sphinx documentation. It allows dynamic content generation, variable injection, and custom logic using Jinja2 syntax in reStructuredText or MyST files. The current version is 2.0.2, and releases are generally made as needed, with significant changes between major versions.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/tardyp/sphinx-jinja","tags":["sphinx","jinja","documentation","extension","templating"],"install":[{"cmd":"pip install sphinx-jinja","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for Sphinx documentation projects.","package":"Sphinx","optional":false},{"reason":"The templating engine used by the extension.","package":"Jinja2","optional":false}],"imports":[{"note":"sphinx-jinja is typically integrated by adding 'sphinx_jinja' to the 'extensions' list in conf.py, not through direct Python imports of its internal components. Configuration is done via global variables in conf.py.","wrong":"from sphinx_jinja import SomeClass","symbol":"Extension Configuration","correct":"extensions = ['sphinx_jinja']\njinja_contexts = {...}"}],"quickstart":{"code":"# conf.py\nproject = 'My Jinja Project'\ncopyright = '2024, Your Name'\nhtml_theme = 'alabaster'\nextensions = [\n    'sphinx_jinja'\n]\n\njinja_contexts = {\n    'global_vars': {\n        'product_name': 'Awesome App',\n        'version': '1.0.0'\n    }\n}\n\njinja_filters = {\n    'upper': lambda s: s.upper()\n}\n\njinja_env_kwargs = {\n    'trim_blocks': True,\n    'lstrip_blocks': True\n}\n\n# docs/index.rst\n# .. jinja:: global_vars\n#\n#    Welcome to {{ product_name }} ({{ version }}).\n#    This text will be uppercased: {{ \"hello world\" | upper }}\n","lang":"python","description":"To get started, add 'sphinx_jinja' to your `extensions` list in `conf.py`. Then, configure Jinja contexts, filters, globals, and environment options using `jinja_contexts`, `jinja_filters`, `jinja_globals`, `jinja_tests`, and `jinja_env_kwargs` variables. Finally, use the `.. jinja::` directive in your reStructuredText or MyST files to render templates. The provided example shows a `conf.py` setup and a conceptual `.rst` usage."},"warnings":[{"fix":"Migrate your `conf.py` configuration from `jinja_contexts`, `jinja_env`, `jinja_filters`, `jinja_globals`, `jinja_tests` (pre-2.0.0) to the new style using `jinja_contexts`, `jinja_filters`, `jinja_globals`, `jinja_tests`, and `jinja_env_kwargs` (2.0.0+). Consult the official documentation for detailed migration guides.","message":"The configuration parameters in `conf.py` for setting up Jinja2 environments, contexts, filters, globals, and tests have changed significantly in version 2.0.0.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"Ensure your project is running on Python 3.7 or a later version before upgrading to sphinx-jinja 2.x.","message":"Version 2.0.0 dropped support for Python 3.6. It now requires Python 3.7 or newer.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"Upgrade your Sphinx installation to version 4.0.0 or higher: `pip install 'sphinx>=4.0.0'`.","message":"Version 2.0.0 tightened its dependency on Sphinx, requiring Sphinx 4.0.0 or newer.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"Upgrade your Jinja2 installation to version 3.0.0 or higher: `pip install 'Jinja2>=3.0.0'`.","message":"Version 2.0.0 updated its dependency on Jinja2, requiring Jinja2 3.0.0 or newer.","severity":"breaking","affected_versions":"2.0.0 and later"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}