https://blog.readthedocs.comRead the Docs Blog - Posts tagged migrating2024-01-10T23:05:11.044453+00:00ABloghttps://blog.readthedocs.com/user-defined-redirects/User-defined Redirects2014-08-22T00:00:00+00:00Eric Holscher<section id="user-defined-redirects">
<p>Today we are announcing User-defined Redirects for Read the Docs.
This has been a long requested feature that should cut down on 404’s when migrating your documentation.</p>
<p>Read the Docs has long had <a class="reference external" href="http://docs.readthedocs.org/en/latest/redirects.html">Redirects</a>,
but they are managed automatically for only certain use cases.
This change allows users to control a specific set of common redirects.</p>
<section id="prefix-redirects">
<h2>Prefix Redirects</h2>
<p>The most useful and requested application of redirects was to migrate to Read the Docs from an old host.
You would have your docs served at a previous URL,
but that URL would break once you moved them.
Read the Docs includes a language and version slug in your documentation,
but not all documentation is hosted this way.</p>
<p>Say that you previously had your docs hosted at <code class="docutils literal notranslate"><span class="pre">http://docs.example.com/dev/</span></code>,
and you move <code class="docutils literal notranslate"><span class="pre">docs.example.com</span></code> to point at Read the Docs.
Users will have a bookmark saved to a page at <code class="docutils literal notranslate"><span class="pre">http://docs.example.com/dev/install.html</span></code>,
a URL that no longer exists.</p>
<p>You can now set a <em>Prefix Redirect</em> that will redirect all 404’s with a prefix to a new place.
The example configuration would be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Type</span><span class="p">:</span> <span class="n">Prefix</span> <span class="n">Redirect</span>
<span class="n">From</span> <span class="n">URL</span><span class="p">:</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span>
</pre></div>
</div>
<p>Your user’s query would now redirect in the following manner:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">docs</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">install</span><span class="o">.</span><span class="n">html</span> <span class="o">-></span>
<span class="n">docs</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">en</span><span class="o">/</span><span class="n">latest</span><span class="o">/</span><span class="n">install</span><span class="o">.</span><span class="n">html</span>
</pre></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre">en</span></code> and <code class="docutils literal notranslate"><span class="pre">latest</span></code> are the default language and version values for your project.</p>
</section>
<section id="page-redirects">
<h2>Page Redirects</h2>
<p>A more specific case is when you move a page around in your docs.
The old page will start 404’ing,
and your users will be confused.
<em>Page Redirects</em> let you redirect a specific page.</p>
<p>Say you move the <code class="docutils literal notranslate"><span class="pre">example.html</span></code> page into a subdirectory of examples: <code class="docutils literal notranslate"><span class="pre">examples/intro.html</span></code>.
You would set the following configuration:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Type</span><span class="p">:</span> <span class="n">Page</span> <span class="n">Redirect</span>
<span class="n">From</span> <span class="n">URL</span><span class="p">:</span> <span class="n">example</span><span class="o">.</span><span class="n">html</span>
<span class="n">To</span> <span class="n">URL</span><span class="p">:</span> <span class="n">examples</span><span class="o">/</span><span class="n">intro</span><span class="o">.</span><span class="n">html</span>
</pre></div>
</div>
</section>
<section id="sphinx-redirects">
<h2>Sphinx Redirects</h2>
<p>We also support redirects for changing the type of documentation Sphinx is building.
If you switch between <em>HTMLDir</em> and <em>HTML</em>, your URL’s will change.
A page at <code class="docutils literal notranslate"><span class="pre">/en/latest/install.html</span></code> will be served at <code class="docutils literal notranslate"><span class="pre">/en/latest/install/</span></code>,
or vice versa.
The built in redirects for this will handle redirecting users appropriately.</p>
</section>
<section id="implementation">
<h2>Implementation</h2>
<p>Since we serve documentation in a highly available way,
we do not run any logic when we’re serving documentation.
This means that redirects will only happen in the case of a <em>404 File Not Found</em>.</p>
<p>In the future we might implement redirect logic in Javascript,
but this first version is only implemented in the 404 handlers.</p>
</section>
<section id="feature-requests">
<h2>Feature Requests</h2>
<p>This is an initial attempt at redirects.
We have some plans to improve this,
but get in touch with us if you have ideas for improving the feature.</p>
<p>Feel free to <a class="reference external" href="http://github.com/rtfd/readthedocs.org/issues">file an issue</a>,
or you can always reach us at <a class="reference external" href="mailto:readthedocs%40gmail.com">readthedocs<span>@</span>gmail<span>.</span>com</a>.</p>
</section>
</section>
Today we are announcing User-defined Redirects for Read the Docs.
This has been a long requested feature that should cut down on 404’s when migrating your documentation.Read the Docs has long had Redirects,
but they are managed automatically for only certain use cases.
This change allows users to control a specific set of common redirects.2014-08-22T00:00:00+00:00