{"id":10250,"library":"sphinxext-rediraffe","title":"Sphinx Redirect Extension","description":"sphinxext-rediraffe is a Sphinx extension that generates HTTP redirects (via HTML meta refresh tags) for non-existent pages, pointing them to specified working pages. This is useful for maintaining SEO and user experience when restructuring documentation. It is currently at version 0.3.0 and typically releases updates as needed for bug fixes, compatibility with new Sphinx versions, or minor features.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinxext-rediraffe/","tags":["sphinx","documentation","redirects","meta-refresh","extension"],"install":[{"cmd":"pip install sphinxext-rediraffe","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to function.","package":"Sphinx"}],"imports":[{"note":"Add this string to the 'extensions' list in your conf.py file.","symbol":"sphinxext.rediraffe","correct":"extensions = ['sphinxext.rediraffe']"}],"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinxext.rediraffe',\n]\n\n# Option 1: Path to a text file with redirects (preferred for many redirects)\nrediraffe_redirects = \"redirects.txt\"\n\n# Option 2: A dictionary mapping old paths to new paths (for fewer redirects)\n# rediraffe_redirects = {\n#     \"old/page\": \"new/page.html\",\n#     \"legacy_docs/index\": \"current_docs/welcome.html\",\n# }\n\n# --- redirects.txt (example content, place in your source directory) ---\n# old/path/to/file new/path/to/target.html\n# old_directory/some_page new_directory/another_page.html\n# old/index new/home.html\n# A comment line starts with a hash\n","lang":"python","description":"To quickly set up `sphinxext-rediraffe`, first add it to your `extensions` list in `conf.py`. Then, configure the `rediraffe_redirects` setting, either by pointing it to a text file (e.g., `redirects.txt`) where each line specifies an old path followed by a new path, or by providing a dictionary directly in `conf.py`."},"warnings":[{"fix":"Ensure `extensions = ['sphinxext.rediraffe', ...]` is present in your `conf.py`.","message":"The most common issue is forgetting to add 'sphinxext.rediraffe' to the `extensions` list in your `conf.py` file. Without this, Sphinx will not load the extension.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `rediraffe_redirects` in `conf.py` to a string (path to file) or a dictionary mapping old to new paths.","message":"Since version 0.2.0, the `rediraffe_redirects` setting defaults to `None`. You must explicitly configure this setting with either a path to a redirects file or a dictionary; otherwise, no redirects will be generated.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Review your `redirects.txt` file or `rediraffe_redirects` dictionary to ensure paths are relative, use forward slashes, and correctly target HTML output files.","message":"Paths specified in `rediraffe_redirects` (both file and dictionary methods) should be relative to your Sphinx source directory and use forward slashes (`/`), even on Windows. Do not include `.rst` or other source file extensions for the 'old' paths; specify the target HTML file (e.g., `new_page.html`) for the 'new' paths.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the path provided in `rediraffe_redirects` in `conf.py` and confirm the file is present at that location.","message":"If you point `rediraffe_redirects` to a file, ensure that the file exists and is accessible. If the file is not found, `sphinxext-rediraffe` will log a warning and skip redirect generation for that configuration.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Set `rediraffe_redirects` to a path to a redirects file (e.g., `'redirects.txt'`) or a dictionary of redirects in your `conf.py`.","cause":"The `rediraffe_redirects` setting is not defined in `conf.py` or is empty.","error":"[WARNING] sphinxext.rediraffe: No redirects configured. Skipping redirection generation."},{"fix":"Add `'sphinxext.rediraffe'` to your `extensions` list in `conf.py`.","cause":"The extension name `'sphinxext.rediraffe'` was not added to the `extensions` list in your `conf.py` file.","error":"Sphinx error: unknown extension 'sphinxext.rediraffe'"},{"fix":"Correct the path in `rediraffe_redirects` or ensure the specified file exists at that location.","cause":"The path specified in `rediraffe_redirects` in `conf.py` does not point to an existing file.","error":"[WARNING] sphinxext.rediraffe: Redirect file 'path/to/nonexistent_redirects.txt' not found."},{"fix":"Ensure each line in your `redirects.txt` file has exactly two space-separated paths. Comments should start with a `#`.","cause":"A line in your `redirects.txt` file does not follow the required `old_path new_path` (space-separated) format.","error":"[WARNING] sphinxext.rediraffe: Invalid redirect entry: 'old_page -> new_page'"}]}