Redirecting pages when reorganizing content¶
As a documentation site grows, its natural for content to need to move.
If pages are moved or renamed, you should create a redirect from the old page path to the new one so that users won’t be orphaned by out-of-date links and bookmarks.
Documenteer supports this with the [sphinx.redirects] table in the documenteer.toml configuration file.
Adding a page redirect in documenteer.toml¶
As an example, consider the page at old-page.rst has moved to some-dir/new-page.rst.
To create a redirect from the old page to the new one, add the following to the documenteer.toml file:
[sphinx.redirects]
"old-page.rst" = "some-dir/new-page.rst"
These paths are relative to the documentation project’s root directory (where conf.py and documenteer.toml are located) and include the file extension (e.g., .rst or .md).
The table accepts an arbitrary number of redirects:
[sphinx.redirects]
"old-page.rst" = "some-dir/new-page.rst"
"foo.rst" = "bar.rst"
Redirects for deleted pages¶
Besides pages that have been moved, you can use this feature for pages that have been deleted. Choose an existing path that is most relevant to the deleted page and redirect it to the new location.
[sphinx.redirects]
"deleted-page.rst" = "index.rst"