sphinx-reredirects Usage

Usage#

This document explains how to use the sphinx-reredirects extension to manage redirects in your Sphinx documentation. The extension provides flexible options for defining redirects, including support for wildcards and placeholders.

Introduction#

The extension relies on the redirects configuration option in conf.py. redirects option maps a source to a target.

redirects = {
     "<source>": "<target>"
}

By default, redirects is empty (i.e. generates no redirect files).

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

A source may be a non-existent document or existing document. If a source does not exist, sphinx-reredirects creates a new redirect .html file. For an existing document, the document’s .html file will be overwritten with the redirect file. To select multiple existing documents, a source wildcard can be used.

Target (the value in the redirects map) is a URL that will be used in the HTML redirecting file. It may be specified using the placeholder to reuse the source docname (see Target placeholders).

Target must correspond to the output file naming of the chosen Sphinx builder. For example, the html builder creates docname.html, while dirhtml creates docname/index.html.

Important

The extension works only for HTML-based builders like html and dirhtml. When building to other outputs (linkcheck, latex), it does nothing.

The target may be relative to the current page, or it may be absolute, in which case it takes the project root as the root of the path. For example, if you want to redirect guides/index.html to index.html, you can use both options shown below:

redirects = {
     "guides/index": "../index.html"  # relative
     "guides/index": "/index.html"    # absolute
}

Redirect old documents#

The basic usage is to redirect a document you delete or rename to a new file within the same project. For example, if you rename setup.rst to install.rst:

redirects = {
    "setup": "install.html",
}

Newly created setup.html will contain <meta http-equiv="refresh" content="0; url=install.html">.

Or, if you output to dirhtml, target must be a folder:

redirects = {
    "setup": "install/",
}

Absolute URLs

The target may also be an external URL. For example, if a particular page is now on a different website:

redirects = {
    "install/requirements": "https://anotherwebsite.com/docs/requirements.html",
}

It will create an install folder (if it does not exist) and requirements.html containing <meta http-equiv="refresh" content="0; url=https://anotherwebsite.com/docs/requirements.html">.

Redirect existing documents#

Source (the key in the redirects option) may be specified with wildcards. If wildcard is used, it means that you want to expand it against existing documents. sphinx-reredirects creates redirect .html file that will overwrite original document’s html file.

For example, if all FAQ documents in faq/ folder should be redirected to dedicated forum website, but you don’t want to delete them in your documentation:

redirects = {
    "faq/*": "https://website.com/forum/faq",
}

Now, html files originally produced by documents in faq/ like supported-os.html, licencing.html, etc., are all replaced with body <meta http-equiv="refresh" content="0; url=https://website.com/forum/faq">

Wildcard syntax#

Wildcards for selecting existing source documents 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.

(If you are curious, matching is using Python3 fnmatch().)

Important

In other words, for example ** used as “recursive” has no meaning here.

Target placeholders#

Matched document in the source, is available in the target as $source or ${source} placeholder. Because source notation (a docname) is without suffix, you may need to append .html or / suffix after the placeholder.

For example, if all FAQ documents in faq/ folder should be redirected to dedicated forum website with the identical filenames in URL, but you don’t want to delete them in your documentation:

redirects = {
    "faq/*": "https://website.com/forum/faq/$source",
}

Now, html files originally produced by documents in faq/ like supported-os.html, licencing.html, etc., have replaced bodies like <meta http-equiv="refresh" content="0; url=https://website.com/forum/faq/supported-os">, etc.

Redirect everything#

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

redirects = {
    "*": "https://anotherwebsite.com/docs/$source.html"
}

Tip

To help search engines to understand the transfer, update (or set) html_baseurl option to the new website, too.

Checking your redirects#

Sphinx has a linkcheck builder for finding broken links in your documentation. This extension cooperates with it so that redirects to external websites will be checked too.

Note

Checking redirects to another page in the same documentation is not supported yet.

Invoke link checker as usual:

sphinx-build -M linkcheck source build

The output will contains checked links that appear in the documents itself, but also redirects to external URLs (those with line -1):

(         install: line   -1) ok        https://documatt.com
(         faq/two: line   -1) broken    https://documatt.com/faq/two - 404 Client Error: Not Found for url: https://documatt.com/faq/two
(         faq/one: line   -1) broken    https://documatt.com/faq/one - 404 Client Error: Not Found for url: https://documatt.com/faq/one
(           index: line    6) ok        https://documatt.com/sphinx-reredirects
(           index: line    7) ok        https://github.com/documatt/sphinx-reredirects