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 conf.py. 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.
Install
pip3 install sphinx-reredirects
Setup
Add to your conf.py into extensions list extension name sphinx_reredirects:
extensions = [ ... 'sphinx_reredirects' ]
Usage
The extension relies on the redirects configuration option in conf.py. 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": "https://anotherwebsite.com/docs/agents/intro.html", }
Wildcards
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.
Placeholders
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 = { "*": ""https://anotherwebsite.com/docs/$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.
FAQ
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 conf.py). 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.
About and legal
sphinx-reredirects started from the urge to manage redirects for all documents during moving our Techwriter at work blog to the new domain https://techwriter.documatt.com.
Feel free to raise issue with support question, found bug, or enhancement.
Legal
Forward Arrow icon by Icons8.
sphinx-reredirects is licenced under BSD3.
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
Built Distribution
Hashes for sphinx_reredirects-0.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 681149d869f782779662dd646b23ca13d3dfe3e98548ad516273052ab2598b7f |
|
MD5 | 89370087298ae87cdba5a6b783ef69fa |
|
BLAKE2b-256 | 237782b7f1993f2d2e8e1a6c9b33244b2929ff508e6b0c76977ef65cbaea8100 |