{"id":4771,"library":"sphinx-reredirects","title":"Sphinx Reredirects","description":"Sphinx Reredirects is a Sphinx extension that generates HTML pages with meta refresh redirects for moved or renamed documentation pages, preventing 404 errors. It is currently at version 1.1.0 and is actively maintained with irregular but frequent releases.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/documatt/sphinx-reredirects","tags":["Sphinx","documentation","redirects","HTML","tooling"],"install":[{"cmd":"pip install sphinx-reredirects","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for any Sphinx extension. Requires >=7.4 for v1.0.0+ and supports 9.0+ for v1.1.0.","package":"Sphinx","optional":false}],"imports":[{"note":"The extension is enabled by adding its string name to the 'extensions' list in conf.py, not as a direct Python import.","symbol":"'sphinx_reredirects'","correct":"extensions = ['sphinx_reredirects', ...]"}],"quickstart":{"code":"# In your project's conf.py file:\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx_reredirects'\n]\n\n# Define your redirects. Keys are old docnames, values are new URLs.\n# Docnames are paths without file extensions (e.g., 'old_chapter/intro' for 'old_chapter/intro.rst').\n# Targets can be relative to the project root or absolute URLs.\nredirects = {\n    \"old-page\": \"new-page.html\",\n    \"removed-feature\": \"https://external.com/docs/new-home\",\n    \"legacy/*\": \"current_docs/$source.html\" # Wildcard example\n}\n\n# To build the documentation and apply redirects:\n# sphinx-build -M html source build","lang":"python","description":"To use sphinx-reredirects, first ensure it's added to your `extensions` list in `conf.py`. Then, define the `redirects` dictionary in the same file, mapping old Sphinx document names (without extensions) to their new relative or absolute URL targets. Wildcards and placeholders are supported."},"warnings":[{"fix":"Ensure your environment meets Python >= 3.11 and Sphinx >= 7.4. Upgrade Sphinx using `pip install -U sphinx` if necessary.","message":"Version 1.0.0 introduced stricter Python and Sphinx version requirements. It now requires Python >= 3.11 and Sphinx >= 7.4.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Be aware that redirects are only generated for HTML output. This is by design, as meta refresh redirects are an HTML-specific mechanism.","message":"The extension only supports HTML-based builders (like `html` and `dirhtml`). It performs no action when building to other outputs (e.g., `linkcheck`, `latex`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Plan your redirects carefully. If you intend to redirect an *existing* document, understand that its original content will no longer be accessible at that path in the built output.","message":"If a source document specified in the `redirects` configuration exists, its generated HTML file will be *overwritten* by the redirect HTML. This is intentional to ensure the redirect takes precedence.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manually verify internal redirects or use other tools. The extension cooperates with `linkcheck` for external redirects.","message":"The Sphinx `linkcheck` builder does not currently support checking redirects to other pages *within the same documentation project* when using `sphinx-reredirects`. It only checks redirects to external URLs.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `sphinx-reredirects` version 0.1.6 or newer, as this feature was added and is now the default behavior. For older versions, a custom HTML template was required.","message":"In versions prior to 0.1.6, URL fragments (e.g., `#section`) were not preserved during redirects, leading to loss of specific link targets.","severity":"deprecated","affected_versions":"<0.1.6"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}