https://blog.readthedocs.comRead the Docs Blog - Posts in Changelog2024-01-10T23:05:10.593243+00:00ABloghttps://blog.readthedocs.com/new-improvements-to-redirects/New improvements to redirects2024-01-03T00:00:00+00:00Santos Gallegos<section id="new-improvements-to-redirects">
<p>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.</p>
<p>We are excited to announce significant improvements to our redirects feature to make them more flexible and powerful.</p>
<section id="key-improvements">
<h2>Key improvements</h2>
<dl class="simple">
<dt>HTTP status code</dt><dd><p>You can now choose the <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections">HTTP status code</a> for your redirects,
selecting between 301 (permanent redirect) and 302 (temporary redirect).
Previously, all redirects had the status code 302.</p>
</dd>
</dl>
<dl class="simple">
<dt>Explicit ordering</dt><dd><p>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.</p>
</dd>
<dt>Disable redirects without deletion</dt><dd><p>You can now disable redirects without deleting them.
This is useful when debugging or when you want to temporarily disable a redirect.</p>
</dd>
<dt>Trailing slash</dt><dd><p>Redirects now apply to URLs with and without a trailing slash.
Previously, you had to create two redirects to handle both cases.</p>
</dd>
<dt>Suffix wildcards</dt><dd><p>While we already supported suffix wildcard redirects, their functionality was limited.
Now wildcard redirects use a more familiar syntax, <code class="docutils literal notranslate"><span class="pre">*</span></code> instead of <code class="docutils literal notranslate"><span class="pre">$rest</span></code>,
and the <code class="docutils literal notranslate"><span class="pre">:splat</span></code> placeholder is available in the target URL.
Wildcards can be used with <em>Exact</em> and <em>Page</em> redirects.</p>
</dd>
</dl>
</section>
<section id="other-changes">
<h2>Other changes</h2>
<ul class="simple">
<li><p>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.</p></li>
<li><p>Redirects now have a description field, allowing you to provide additional information about the redirect.</p></li>
<li><p><em>Sphinx HTMLDir -> HTML</em> and <em>Sphinx HTML -> HTMLDir*</em> redirects where renamed to <em>Clean URL to HTML</em> and <em>HTML to Clean URL</em> redirects.
These types of redirects are valid for all documentation tools, not just Sphinx.</p></li>
<li><p>Prefix redirects were removed.
The same functionality can be achieved with an <em>Exact</em> redirect using a wildcard.</p></li>
</ul>
<p>For more details and examples, refer to <a class="reference external" href="https://docs.readthedocs.io/en/stable/user-defined-redirects.html#user-defined-redirects">our documentation</a>.</p>
</section>
<section id="breaking-changes">
<h2>Breaking changes</h2>
<p>In order to support these new improvements, we have made some breaking changes:</p>
<ul class="simple">
<li><p>The old <code class="docutils literal notranslate"><span class="pre">$rest</span></code> syntax for wildcard redirects is no longer supported.
Use <code class="docutils literal notranslate"><span class="pre">*</span></code> instead.</p></li>
<li><p>When using a wildcard, the matched suffix is no longer added to the target URL automatically.
Use the <code class="docutils literal notranslate"><span class="pre">:splat</span></code> placeholder in the target URL to add the matched suffix.</p></li>
<li><p>The redirect type <code class="docutils literal notranslate"><span class="pre">sphinx_html</span></code> used in the API was renamed to <code class="docutils literal notranslate"><span class="pre">clean_url_to_html</span></code>.</p></li>
<li><p>The redirect type <code class="docutils literal notranslate"><span class="pre">sphinx_htmldir</span></code> used in the API was renamed to <code class="docutils literal notranslate"><span class="pre">html_to_clean_url</span></code>.</p></li>
<li><p>The prefix redirect type was removed.
Use an <em>Exact</em> redirect with a wildcard instead.</p></li>
</ul>
<p>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.</p>
</section>
</section>
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.2024-01-03T00:00:00+00:00