Skip to main content

Handles redirects for moved pages in Sphinx documentation projects

Project description

sphinx-reredirects is the extension for Sphinx documentation projects that handles redirects for moved pages. Based on the its configuration, the extension generates HTML pages with meta refresh redirects to the new page location to prevent 404 errors if you rename or move your documents.

Good URLs are never changing URLs. But if you must, sphinx-reredirects helps you manage redirects with ease and from the single place in project’s For example, if you rename document start to intro, you configure this redirect, the extension generate HTML page start.html with <meta http-equiv="refresh" content="0; url=intro.html">. sphinx-reredirects supports wildcards and moving to different domain too.


pip3 install sphinx-reredirects


Add to your into extensions list extension name sphinx_reredirects:

extensions = [


The extension relies on the redirects configuration option in By default is empty (generates no redirect files). redirects option is mapping of docnames to new targets.

Source (the key in redirects map) is docname, i.e. document path without an suffix (an extension). Most Sphinx projects use .rst as extensions. For example, docname for file index.rst is index, for agents/intro.rst is agents/intro, etc.

While, target URI is free text that will be be used in HTML redirect file as-is. Only placeholder (see bellow) is applied on it. It means its value usually is path with file suffix.

Relative URIs

Basic usage is to redirect document to another document within the same project:

redirects = {
    "agents/intro": "agents/getting-started.html",

Or, if you output to dirhtml:

redirects = {
    "agents/*": "agents/getting-started/",

Absolute URIs

However, target URI maybe any value. For example, if particular page is now on the different website:

redirects = {
    "agents/intro": "",


Source URI (the key in the redirects option) may be specified with wildcards.

Wildcards know only *, ?, [seq] and [!seq] patterns. * matches everything, while ? any single character. [seq] matches any character in the seq, [!seq] any character not in seq.


Matched part in the source URI, is available in the target URI as $source or ${source}. Because source notation is without suffix, you may need to append .html or / suffix after the placeholder.

For example, if you move all documents inside agents/ folder to operators/:

redirects = {
    "agents/*": "operators/$source.html",

Or, if you output to dirhtml:

redirects = {
    "agents/*": "operators/$source/",

Occasionally, you have to move complete documentation to the new home. It’s easy with wildcard and placeholder:

redirects = {
    "*": ""$source.html"

Caveats and limitations

The sphinx-reredirects extension runs after the Sphinx build has finished. It works by creating files in build output directory (usually build/html, _build/html, etc.). If you instruct sphinx-reredirects to create redirect file at the path of existing HTML file produced by Sphinx, it will be overwritten without warning.


Isn’t 301 redirects better?

sphinx-reredirects extension was created for tech writers who can’t manage redirects with server-side 301 redirects. Generally, SEO consultants recommend server-side redirects created with .htaccess and similar files. However, many documentation is hosted as static website on services like S3, GitLab Pages which doesn’t support server-side redirects.

However, client-side redirects with meta refresh are okay for search engines, even the most ancient browsers, and users too. Also, it is easier if you can manage redirects in documentation, instead of delegate every page URL change to the administrators.

I know better how to write HTML redirect file

By default, created HTML redirect files contains <html><head><meta http-equiv="refresh" content="0; url=${to_uri}"></head></html>.

If you want JavaScript redirection instead, wait longer, or whatever, set redirect_html_template option. This option should points to file inside source dir (directory containing For example:

redirect_html_template = "redirect.html.template"

Actual target URI requested in configuration is available under ${to_uri} placeholder.

Why name “reredirects”?

Because the name “redirects” is already taken by another extension. Unfortunately, it seems to be a bit old, unmaintained, and doesn’t support wildcards. These were reasons why we decided to craft new extension.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_reredirects-0.0.0.tar.gz (4.9 kB view hashes)

Uploaded Source

Built Distribution

sphinx_reredirects-0.0.0-py3-none-any.whl (5.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page