.. post:: January 3, 2024 :tags: redirects, docs :category: Changelog :author: Santos :location: CUE
As your documentation evolves, content is moved, and pages are renamed, leading to broken links for your users. Redirects allow you to point users to the new location of a page.
We are excited to announce significant improvements to our redirects feature to make them more flexible and powerful.
- HTTP status code
- You can now choose the HTTP status code for your redirects, selecting between 301 (permanent redirect) and 302 (temporary redirect). Previously, all redirects had the status code 302.
- Explicit ordering
- Redirects now have an explicit order, allowing you to control the order in which they are processed. Previously, redirects were ordered based on their last modification date.
- Disable redirects without deletion
- You can now disable redirects without deleting them. This is useful when debugging or when you want to temporarily disable a redirect.
- Trailing slash
- Redirects now apply to URLs with and without a trailing slash. Previously, you had to create two redirects to handle both cases.
- Suffix wildcards
- While we already supported suffix wildcard redirects, their functionality was limited.
Now wildcard redirects use a more familiar syntax,
*
instead of$rest
, and the:splat
placeholder is available in the target URL. Wildcards can be used with Exact and Page redirects.
- Redirects aren't processed in domains from pull requests previews. You should treat these domains as ephemeral and not rely on them for user-facing content.
- Redirects now have a description field, allowing you to provide additional information about the redirect.
- Sphinx HTMLDir -> HTML and Sphinx HTML -> HTMLDir* redirects where renamed to Clean URL to HTML and HTML to Clean URL redirects. These types of redirects are valid for all documentation tools, not just Sphinx.
- Prefix redirects were removed. The same functionality can be achieved with an Exact redirect using a wildcard.
For more details and examples, refer to our documentation.
In order to support these new improvements, we have made some breaking changes:
- The old
$rest
syntax for wildcard redirects is no longer supported. Use*
instead. - When using a wildcard, the matched suffix is no longer added to the target URL automatically.
Use the
:splat
placeholder in the target URL to add the matched suffix. - The redirect type
sphinx_html
used in the API was renamed toclean_url_to_html
. - The redirect type
sphinx_htmldir
used in the API was renamed tohtml_to_clean_url
. - The prefix redirect type was removed. Use an Exact redirect with a wildcard instead.
If you had redirects using the old syntax, you don't need to do anything. We have automatically migrated them to use the new syntax.