Sphinx Redirect Extension

0.3.0 · active · verified Fri Apr 17

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.

Common errors

```
[WARNING] sphinxext.rediraffe: No redirects configured. Skipping redirection generation.
```
cause The `rediraffe_redirects` setting is not defined in `conf.py` or is empty.

fix Set `rediraffe_redirects` to a path to a redirects file (e.g., `'redirects.txt'`) or a dictionary of redirects in your `conf.py`.
```
Sphinx error: unknown extension 'sphinxext.rediraffe'
```
cause The extension name `'sphinxext.rediraffe'` was not added to the `extensions` list in your `conf.py` file.

fix Add `'sphinxext.rediraffe'` to your `extensions` list in `conf.py`.
```
[WARNING] sphinxext.rediraffe: Redirect file 'path/to/nonexistent_redirects.txt' not found.
```
cause The path specified in `rediraffe_redirects` in `conf.py` does not point to an existing file.

fix Correct the path in `rediraffe_redirects` or ensure the specified file exists at that location.
```
[WARNING] sphinxext.rediraffe: Invalid redirect entry: 'old_page -> new_page'
```
cause A line in your `redirects.txt` file does not follow the required `old_path new_path` (space-separated) format.

fix Ensure each line in your `redirects.txt` file has exactly two space-separated paths. Comments should start with a `#`.

Warnings

gotcha 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.
Fix: Ensure `extensions = ['sphinxext.rediraffe', ...]` is present in your `conf.py`.
gotcha 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.
Fix: Set `rediraffe_redirects` in `conf.py` to a string (path to file) or a dictionary mapping old to new paths.
gotcha 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.
Fix: Review your `redirects.txt` file or `rediraffe_redirects` dictionary to ensure paths are relative, use forward slashes, and correctly target HTML output files.
gotcha 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.
Fix: Verify the path provided in `rediraffe_redirects` in `conf.py` and confirm the file is present at that location.

Install

pip install sphinxext-rediraffe Install latest version

Imports

sphinxext.rediraffe
```
extensions = ['sphinxext.rediraffe']
```
Add this string to the 'extensions' list in your conf.py file.

Quickstart

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`.

# conf.py
extensions = [
    'sphinxext.rediraffe',
]

# Option 1: Path to a text file with redirects (preferred for many redirects)
rediraffe_redirects = "redirects.txt"

# Option 2: A dictionary mapping old paths to new paths (for fewer redirects)
# rediraffe_redirects = {
#     "old/page": "new/page.html",
#     "legacy_docs/index": "current_docs/welcome.html",
# }

# --- redirects.txt (example content, place in your source directory) ---
# old/path/to/file new/path/to/target.html
# old_directory/some_page new_directory/another_page.html
# old/index new/home.html
# A comment line starts with a hash

view raw JSON →