CINXE.COM

<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="./"> <head> <meta charset="utf-8" /> <meta name="readthedocs-addons-api-version" content="1"><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta property="og:title" content="Redirects" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://docs.readthedocs.io/en/stable/user-defined-redirects.html" /> <meta property="og:site_name" content="Read the Docs Documentation" /> <meta property="og:description" content="Over time, a documentation project may want to rename and move contents around. Redirects allow changes in a documentation project to happen without bad user experiences. If you do not manage URL structures, users will eventually encounter 404 File Not Found errors. While this may be acceptable i..." /> <meta property="og:image" content="https://docs.readthedocs.io/en/latest/_static/img/logo-opengraph.png" /> <meta property="og:image:alt" content="Read the Docs Documentation" /> <meta name="description" content="Over time, a documentation project may want to rename and move contents around. Redirects allow changes in a documentation project to happen without bad user experiences. If you do not manage URL structures, users will eventually encounter 404 File Not Found errors. While this may be acceptable i..." /> <meta name="twitter:card" content="summary_large_image" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Redirects — Read the Docs user documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" /> <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" /> <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" /> <link rel="stylesheet" type="text/css" href="_static/css/custom.css?v=da32ccdd" /> <link rel="stylesheet" type="text/css" href="_static/css/sphinx_prompt_css.css?v=351d85e3" /> <link rel="canonical" href="https://docs.readthedocs.io/en/stable/user-defined-redirects.html" /> <script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/documentation_options.js?v=604cd17f"></script> <script src="_static/doctools.js?v=9bcbadda"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/clipboard.min.js?v=a7894cd8"></script> <script src="_static/copybutton.js?v=f281be69"></script> <script src="_static/design-tabs.js?v=f930bc37"></script> <script src="_static/js/expand_tabs.js?v=1e151f68"></script> <script src="_static/js/theme.js"></script> <script src="_static/js/versions.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Traffic analytics" href="traffic-analytics.html" /> <link rel="prev" title="Flyout menu" href="flyout-menu.html" /> <script defer data-domain="docs.readthedocs.io" src="https://plausible.io/js/script.js"></script> <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="docs" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/user-defined-redirects.html" /><meta name="readthedocs-http-status" content="200" /></head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html"> <img src="_static/logo.svg" class="logo" alt="Logo"/> </a> <div class="switch-menus"> <div class="version-switch"></div> <div class="language-switch"></div> </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <p class="caption" role="heading"><span class="caption-text">Getting started</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Read the Docs tutorial</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/doctools.html">Supported tools</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/mkdocs.html">Material for MkDocs</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/sphinx.html">Sphinx</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/markdoc.html">Markdoc</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/add-project.html">Adding a documentation project</a></li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Example projects</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Project setup and configuration</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="config-file/index.html">Configuration file overview</a></li> <li class="toctree-l1"><a class="reference internal" href="config-file/v2.html">Configuration file reference</a></li> <li class="toctree-l1"><a class="reference internal" href="addons.html">Read the Docs Addons</a></li> <li class="toctree-l1"><a class="reference internal" href="automation-rules.html">Automation rules</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/reproducible-builds.html">How to create reproducible builds</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Build process</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="builds.html">Build process overview</a></li> <li class="toctree-l1"><a class="reference internal" href="build-customization.html">Build process customization</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/git-integration.html">Git integration (GitHub, GitLab, Bitbucket)</a></li> <li class="toctree-l1"><a class="reference internal" href="pull-requests.html">Pull request previews</a></li> <li class="toctree-l1"><a class="reference internal" href="build-notifications.html">Build failure notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="environment-variables.html">Environment variable overview</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/environment-variables.html">Environment variable reference</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Hosting documentation</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="versions.html">Versions</a></li> <li class="toctree-l1"><a class="reference internal" href="subprojects.html">Subprojects</a></li> <li class="toctree-l1"><a class="reference internal" href="localization.html">Localization and Internationalization</a></li> <li class="toctree-l1"><a class="reference internal" href="versioning-schemes.html">URL versioning schemes</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-domains.html">Custom domains</a></li> <li class="toctree-l1"><a class="reference internal" href="doc-notifications.html">Documentation notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="canonical-urls.html">Canonical URLs</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/cdn.html">Content Delivery Network (CDN) and caching</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/sitemaps.html">Sitemap support</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/404-not-found.html"><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> pages</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/robots.html"><code class="docutils literal notranslate"><span class="pre">robots.txt</span></code> support</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reading documentation</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="downloadable-documentation.html">Offline formats (PDF, ePub, HTML)</a></li> <li class="toctree-l1"><a class="reference internal" href="doc-diff.html">DocDiff</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/embedding-content.html">How to embed content from your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="server-side-search/index.html">Server side search</a></li> <li class="toctree-l1"><a class="reference internal" href="server-side-search/syntax.html">Search query syntax</a></li> <li class="toctree-l1"><a class="reference internal" href="flyout-menu.html">Flyout menu</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Maintaining projects</span></p> <ul class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="#">Redirects</a><ul> <li class="toctree-l2"><a class="reference internal" href="#built-in-redirects">Built-in redirects</a><ul> <li class="toctree-l3"><a class="reference internal" href="#page-redirects-at-page">Page redirects at <code class="docutils literal notranslate"><span class="pre">/page/</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="#root-url-redirect-at">Root URL redirect at <code class="docutils literal notranslate"><span class="pre">/</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="#root-language-redirect-at-lang">Root language redirect at <code class="docutils literal notranslate"><span class="pre">/<lang>/</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="#shortlink-with-https-slug-rtfd-io">Shortlink with <code class="docutils literal notranslate"><span class="pre">https://<slug>.rtfd.io</span></code></a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#user-defined-redirects">User-defined redirects</a><ul> <li class="toctree-l3"><a class="reference internal" href="#id2">Page redirects</a></li> <li class="toctree-l3"><a class="reference internal" href="#exact-redirects">Exact redirects</a></li> <li class="toctree-l3"><a class="reference internal" href="#clean-html-urls-redirects">Clean/HTML URLs redirects</a></li> <li class="toctree-l3"><a class="reference internal" href="#limitations-and-observations">Limitations and observations</a></li> <li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a><ul> <li class="toctree-l4"><a class="reference internal" href="#redirecting-a-page">Redirecting a page</a></li> <li class="toctree-l4"><a class="reference internal" href="#redirecting-a-directory">Redirecting a directory</a></li> <li class="toctree-l4"><a class="reference internal" href="#redirecting-a-directory-to-a-single-page">Redirecting a directory to a single page</a></li> <li class="toctree-l4"><a class="reference internal" href="#redirecting-a-page-to-the-latest-version">Redirecting a page to the latest version</a></li> <li class="toctree-l4"><a class="reference internal" href="#redirecting-an-old-version-to-a-new-one">Redirecting an old version to a new one</a></li> <li class="toctree-l4"><a class="reference internal" href="#creating-a-shortlink">Creating a shortlink</a></li> <li class="toctree-l4"><a class="reference internal" href="#migrating-your-docs-to-read-the-docs">Migrating your docs to Read the Docs</a></li> <li class="toctree-l4"><a class="reference internal" href="#migrating-your-documentation-to-another-domain">Migrating your documentation to another domain</a></li> <li class="toctree-l4"><a class="reference internal" href="#changing-your-sphinx-builder-from-html-to-dirhtml">Changing your Sphinx builder from <code class="docutils literal notranslate"><span class="pre">html</span></code> to <code class="docutils literal notranslate"><span class="pre">dirhtml</span></code></a></li> </ul> </li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="traffic-analytics.html">Traffic analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="search-analytics.html">Search analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="security-log.html">Security logs</a></li> <li class="toctree-l1"><a class="reference internal" href="badges.html">Status badges</a></li> <li class="toctree-l1"><a class="reference internal" href="explanation/documentation-structure.html">How to structure your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/best-practice/links.html">Best practices for linking to your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="security-implications.html">Security considerations for documentation pages</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Business features</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="commercial/index.html">Business hosting</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/organizations.html">Organizations</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/single-sign-on.html">Single Sign-On (SSO)</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/sharing.html">Sharing private documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/subscriptions.html">How to manage your subscription</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/privacy-level.html">Privacy Levels</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">How-to guides</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="guides/setup/index.html">Project setup and configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/build/index.html">Build process</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/maintenance/index.html">Upgrading and maintaining projects</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/content/index.html">Content, themes and SEO</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/access/index.html">Security and access</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/management/index.html">Account management</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/best-practice/index.html">Best practice</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/troubleshooting/index.html">Troubleshooting problems</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reference</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="api/index.html">Public REST API</a></li> <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently asked questions</a></li> <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li> <li class="toctree-l1"><a class="reference internal" href="about/index.html">About Read the Docs</a></li> <li class="toctree-l1"><a class="reference external" href="https://dev.readthedocs.io">Developer Documentation</a></li> <li class="toctree-l1"><a class="reference external" href="https://about.readthedocs.com">Read the Docs website</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Read the Docs user documentation</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">Redirects</li> <li class="wy-breadcrumbs-aside"> <a href="https://github.com/readthedocs/readthedocs.org/blob/main/docs/user/user-defined-redirects.rst" class="fa fa-github"> Edit on GitHub</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="redirects"> <h1>Redirects<a class="headerlink" href="#redirects" title="Link to this heading"></a></h1> <p>Over time, a documentation project may want to rename and move contents around. Redirects allow changes in a documentation project to happen without bad user experiences.</p> <p>If you do not manage URL structures, users will eventually encounter 404 File Not Found errors. While this may be acceptable in some cases, the bad user experience of a 404 page is usually best to avoid.</p> <dl class="simple"> <dt><a class="reference internal" href="#built-in-redirects">Built-in redirects</a> ⬇️</dt><dd><p>Allows for simple and long-term sharing of external references to your documentation.</p> </dd> <dt><a class="reference internal" href="#user-defined-redirects">User-defined redirects</a> ⬇️</dt><dd><p>Makes it easier to move contents around</p> </dd> </dl> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt><a class="reference internal" href="guides/redirects.html"><span class="doc">How to use custom URL redirects in documentation projects</span></a></dt><dd><p>This guide shows you how to add redirects with practical examples.</p> </dd> <dt><a class="reference internal" href="guides/best-practice/links.html"><span class="doc">Best practices for linking to your documentation</span></a></dt><dd><p>Information and tips about creating and handling external references.</p> </dd> <dt><a class="reference internal" href="guides/deprecating-content.html"><span class="doc">How to deprecate content</span></a></dt><dd><p>A guide to deprecating features and other topics in a documentation.</p> </dd> </dl> </div> <section id="built-in-redirects"> <h2>Built-in redirects<a class="headerlink" href="#built-in-redirects" title="Link to this heading"></a></h2> <p>This section explains the redirects that are automatically active for all projects and how they are useful. Built-in redirects are especially useful for creating and sharing incoming links, which is discussed in depth in <a class="reference internal" href="guides/best-practice/links.html"><span class="doc">Best practices for linking to your documentation</span></a>.</p> <section id="page-redirects-at-page"> <span id="page-redirects"></span><h3>Page redirects at <code class="docutils literal notranslate"><span class="pre">/page/</span></code><a class="headerlink" href="#page-redirects-at-page" title="Link to this heading"></a></h3> <p>You can link to a specific page and have it redirect to your default version, allowing you to create links on external sources that are always up to date. This is done with the <code class="docutils literal notranslate"><span class="pre">/page/</span></code> URL prefix.</p> <p>For instance, you can reach the page you are reading now by going to <a class="reference external" href="https://docs.readthedocs.io/page/guides/best-practice/links.html">https://docs.readthedocs.io/page/guides/best-practice/links.html</a>.</p> <p>Another way to handle this is the <code class="docutils literal notranslate"><span class="pre">latest</span></code> version. You can set your <code class="docutils literal notranslate"><span class="pre">latest</span></code> version to a specific version and just always link to <code class="docutils literal notranslate"><span class="pre">latest</span></code>. You can reach this page by going to <a class="reference external" href="https://docs.readthedocs.io/en/latest/guides/best-practice/links.html">https://docs.readthedocs.io/en/latest/guides/best-practice/links.html</a>.</p> </section> <section id="root-url-redirect-at"> <span id="root-url-redirect"></span><h3>Root URL redirect at <code class="docutils literal notranslate"><span class="pre">/</span></code><a class="headerlink" href="#root-url-redirect-at" title="Link to this heading"></a></h3> <p>A link to the root of your documentation (<code class="xref py py-obj docutils literal notranslate"><span class="pre"><slug>.readthedocs.io/</span></code>) will redirect to the <a class="reference internal" href="glossary.html#term-default-version"><span class="xref std std-term">default version</span></a>, as set in your project settings.</p> <p>This works for both readthedocs.io (Read the Docs Community), readthedocs-hosted.com (Read the Docs for Business), and <a class="reference internal" href="custom-domains.html"><span class="doc">custom domains</span></a>.</p> <p>For example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">docs</span><span class="o">.</span><span class="n">readthedocs</span><span class="o">.</span><span class="n">io</span> <span class="o">-></span> <span class="n">docs</span><span class="o">.</span><span class="n">readthedocs</span><span class="o">.</span><span class="n">io</span><span class="o">/</span><span class="n">en</span><span class="o">/</span><span class="n">stable</span><span class="o">/</span> </pre></div> </div> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>You cannot use the root redirect to reference specific pages. <code class="docutils literal notranslate"><span class="pre">/</span></code> <em>only</em> redirects to the default version, whereas <code class="docutils literal notranslate"><span class="pre">/some/page.html</span></code> will <em>not</em> redirect to <code class="docutils literal notranslate"><span class="pre">/en/latest/some/page.html</span></code>. Instead, use <a class="reference internal" href="#page-redirects"><span class="std std-ref">Page redirects at /page/</span></a>.</p> </div> <p>You can choose which is the <a class="reference internal" href="glossary.html#term-default-version"><span class="xref std std-term">default version</span></a> for Read the Docs to display. This usually corresponds to the most recent official release from your project.</p> </section> <section id="root-language-redirect-at-lang"> <h3>Root language redirect at <code class="docutils literal notranslate"><span class="pre">/<lang>/</span></code><a class="headerlink" href="#root-language-redirect-at-lang" title="Link to this heading"></a></h3> <p>A link to the root language of your documentation (<code class="docutils literal notranslate"><span class="pre"><slug>.readthedocs.io/en/</span></code>) will redirect to the <a class="reference internal" href="glossary.html#term-default-version"><span class="xref std std-term">default version</span></a> of that language.</p> <p>For example, accessing the English language of the project will redirect you to the its default version (<code class="docutils literal notranslate"><span class="pre">stable</span></code>):</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">docs</span><span class="o">.</span><span class="n">readthedocs</span><span class="o">.</span><span class="n">io</span><span class="o">/</span><span class="n">en</span><span class="o">/</span> <span class="o">-></span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">docs</span><span class="o">.</span><span class="n">readthedocs</span><span class="o">.</span><span class="n">io</span><span class="o">/</span><span class="n">en</span><span class="o">/</span><span class="n">stable</span><span class="o">/</span> </pre></div> </div> </section> <section id="shortlink-with-https-slug-rtfd-io"> <h3>Shortlink with <code class="docutils literal notranslate"><span class="pre">https://<slug>.rtfd.io</span></code><a class="headerlink" href="#shortlink-with-https-slug-rtfd-io" title="Link to this heading"></a></h3> <p>Links to <code class="docutils literal notranslate"><span class="pre">rtfd.io</span></code> are treated the same way as <code class="docutils literal notranslate"><span class="pre">readthedocs.io</span></code>. They are intended to be easy and short for people to type.</p> <p>You can reach these docs at <a class="reference external" href="https://docs.rtfd.io">https://docs.rtfd.io</a>.</p> </section> </section> <section id="user-defined-redirects"> <span id="id1"></span><h2>User-defined redirects<a class="headerlink" href="#user-defined-redirects" title="Link to this heading"></a></h2> <section id="id2"> <h3>Page redirects<a class="headerlink" href="#id2" title="Link to this heading"></a></h3> <p><em>Page Redirects</em> let you redirect a page across all versions of your documentation.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Since pages redirects apply to all versions, <code class="docutils literal notranslate"><span class="pre">From</span> <span class="pre">URL</span></code> doesn’t need to include the <code class="docutils literal notranslate"><span class="pre">/<language>/<version></span></code> prefix (e.g. <code class="docutils literal notranslate"><span class="pre">/en/latest</span></code>), but just the version-specific part of the URL. If you want to set redirects only for some languages or some versions, you should use <a class="reference internal" href="#exact-redirects"><span class="std std-ref">Exact redirects</span></a> with the fully-specified path.</p> </div> </section> <section id="exact-redirects"> <h3>Exact redirects<a class="headerlink" href="#exact-redirects" title="Link to this heading"></a></h3> <p><em>Exact Redirects</em> take into account the full URL (including language and version), allowing you to create a redirect for a specific version or language of your documentation.</p> </section> <section id="clean-html-urls-redirects"> <h3>Clean/HTML URLs redirects<a class="headerlink" href="#clean-html-urls-redirects" title="Link to this heading"></a></h3> <p>If you decide to change the style of the URLs of your documentation, you can use <em>Clean URL to HTML</em> or <em>HTML to clean URL</em> redirects to redirect users to the new URL style.</p> <p>For example, if a previous page was at <code class="docutils literal notranslate"><span class="pre">/en/latest/install.html</span></code>, and now is served at <code class="docutils literal notranslate"><span class="pre">/en/latest/install/</span></code>, or vice versa, users will be redirected to the new URL.</p> </section> <section id="limitations-and-observations"> <h3>Limitations and observations<a class="headerlink" href="#limitations-and-observations" title="Link to this heading"></a></h3> <ul class="simple"> <li><p>Read the Docs Community users are limited to 100 redirects per project, and Read the Docs for Business users have a number of redirects limited by their plan.</p></li> <li><p>By default, redirects only apply on pages that don’t exist. <strong>Forced redirects</strong> allow you to apply redirects on existing pages.</p></li> <li><p>Redirects aren’t applied on <a class="reference internal" href="pull-requests.html"><span class="doc">previews of pull requests</span></a>. You should treat these domains as ephemeral and not rely on them for user-facing content.</p></li> <li><p>You can redirect to URLs outside Read the Docs, just include the protocol in <code class="docutils literal notranslate"><span class="pre">To</span> <span class="pre">URL</span></code>, e.g <code class="docutils literal notranslate"><span class="pre">https://example.com</span></code>.</p></li> <li><p>A wildcard can be used at the end of <code class="docutils literal notranslate"><span class="pre">From</span> <span class="pre">URL</span></code> (suffix wildcard) to redirect all pages matching a prefix. Prefix and infix wildcards are not supported.</p></li> <li><p>If a wildcard is used in <code class="docutils literal notranslate"><span class="pre">From</span> <span class="pre">URL</span></code>, the part of the URL that matches the wildcard can be used in <code class="docutils literal notranslate"><span class="pre">To</span> <span class="pre">URL</span></code> with the <code class="docutils literal notranslate"><span class="pre">:splat</span></code> placeholder.</p></li> <li><p>Redirects without a wildcard match paths with or without a trailing slash, e.g. <code class="docutils literal notranslate"><span class="pre">/install</span></code> matches <code class="docutils literal notranslate"><span class="pre">/install</span></code> and <code class="docutils literal notranslate"><span class="pre">/install/</span></code>.</p></li> <li><p>The order of redirects matters. If multiple redirects match the same URL, the first one will be applied. The order of redirects <a class="reference internal" href="guides/redirects.html#changing-the-order-of-redirects"><span class="std std-ref">can be changed from your project’s dashboard</span></a>.</p></li> <li><p>If an infinite redirect is detected, a 404 error will be returned, and no other redirects will be applied.</p></li> </ul> </section> <section id="examples"> <h3>Examples<a class="headerlink" href="#examples" title="Link to this heading"></a></h3> <section id="redirecting-a-page"> <h4>Redirecting a page<a class="headerlink" href="#redirecting-a-page" title="Link to this heading"></a></h4> <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 can create a redirect with 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="o">/</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="o">/</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> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/example.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/examples/intro.html</span></code>.</p></li> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/stable/example.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/stable/examples/intro.html</span></code>.</p></li> </ul> <p>If you want this redirect to apply to a specific version of your documentation, you can create a redirect with 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">Exact</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">en</span><span class="o">/</span><span class="n">latest</span><span class="o">/</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="o">/</span><span class="n">en</span><span class="o">/</span><span class="n">latest</span><span class="o">/</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> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Use the desired version and language instead of <code class="docutils literal notranslate"><span class="pre">latest</span></code> and <code class="docutils literal notranslate"><span class="pre">en</span></code>.</p> </div> </section> <section id="redirecting-a-directory"> <h4>Redirecting a directory<a class="headerlink" href="#redirecting-a-directory" title="Link to this heading"></a></h4> <p>Say you rename the <code class="docutils literal notranslate"><span class="pre">/api/</span></code> directory to <code class="docutils literal notranslate"><span class="pre">/api/v1/</span></code>. Instead of creating a redirect for each page in the directory, you can use a wildcard to redirect all pages in that directory:</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="o">/</span><span class="n">api</span><span class="o">/*</span> <span class="n">To</span> <span class="n">URL</span><span class="p">:</span> <span class="o">/</span><span class="n">api</span><span class="o">/</span><span class="n">v1</span><span class="o">/</span><span class="p">:</span><span class="n">splat</span> </pre></div> </div> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/api/</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/api/v1/</span></code>.</p></li> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/api/projects.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/api/v1/projects.html</span></code>.</p></li> </ul> <p>If you want this redirect to apply to a specific version of your documentation, you can create a redirect with 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">Exact</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">en</span><span class="o">/</span><span class="n">latest</span><span class="o">/</span><span class="n">api</span><span class="o">/*</span> <span class="n">To</span> <span class="n">URL</span><span class="p">:</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">api</span><span class="o">/</span><span class="n">v1</span><span class="o">/</span><span class="p">:</span><span class="n">splat</span> </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Use the desired version and language instead of <code class="docutils literal notranslate"><span class="pre">latest</span></code> and <code class="docutils literal notranslate"><span class="pre">en</span></code>.</p> </div> </section> <section id="redirecting-a-directory-to-a-single-page"> <h4>Redirecting a directory to a single page<a class="headerlink" href="#redirecting-a-directory-to-a-single-page" title="Link to this heading"></a></h4> <p>Say you put the contents of the <code class="docutils literal notranslate"><span class="pre">/examples/</span></code> directory into a single page at <code class="docutils literal notranslate"><span class="pre">/examples.html</span></code>. You can use a wildcard to redirect all pages in that directory to the new page:</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="o">/</span><span class="n">examples</span><span class="o">/*</span> <span class="n">To</span> <span class="n">URL</span><span class="p">:</span> <span class="o">/</span><span class="n">examples</span><span class="o">.</span><span class="n">html</span> </pre></div> </div> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/examples/</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/examples.html</span></code>.</p></li> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/examples/intro.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/examples.html</span></code>.</p></li> </ul> <p>If you want this redirect to apply to a specific version of your documentation, you can create a redirect with 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">Exact</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">en</span><span class="o">/</span><span class="n">latest</span><span class="o">/</span><span class="n">examples</span><span class="o">/*</span> <span class="n">To</span> <span class="n">URL</span><span class="p">:</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">examples</span><span class="o">.</span><span class="n">html</span> </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Use the desired version and language instead of <code class="docutils literal notranslate"><span class="pre">latest</span></code> and <code class="docutils literal notranslate"><span class="pre">en</span></code>.</p> </div> </section> <section id="redirecting-a-page-to-the-latest-version"> <h4>Redirecting a page to the latest version<a class="headerlink" href="#redirecting-a-page-to-the-latest-version" title="Link to this heading"></a></h4> <p>Say you want your users to always be redirected to the latest version of a page, your security policy (<code class="docutils literal notranslate"><span class="pre">/security.html</span></code>) for example. You can use a wildcard with a forced redirect to redirect all versions of that page to the latest version:</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="o">/</span><span class="n">security</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">https</span><span class="p">:</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">security</span><span class="o">.</span><span class="n">html</span> <span class="n">Force</span> <span class="n">Redirect</span><span class="p">:</span> <span class="kc">True</span> </pre></div> </div> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/v1.0/security.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/security.html</span></code>.</p></li> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/v2.5/security.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/security.html</span></code>.</p></li> </ul> <div class="admonition note"> <p class="admonition-title">Note</p> <p><code class="docutils literal notranslate"><span class="pre">To</span> <span class="pre">URL</span></code> includes the domain, this is required, otherwise the redirect will be relative to the current version, resulting in a redirect to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/v1.0/en/latest/security.html</span></code>.</p> </div> </section> <section id="redirecting-an-old-version-to-a-new-one"> <h4>Redirecting an old version to a new one<a class="headerlink" href="#redirecting-an-old-version-to-a-new-one" title="Link to this heading"></a></h4> <p>Let’s say that you want to redirect your readers of your version <code class="docutils literal notranslate"><span class="pre">2.0</span></code> of your documentation under <code class="docutils literal notranslate"><span class="pre">/en/2.0/</span></code> because it’s deprecated, to the newest <code class="docutils literal notranslate"><span class="pre">3.0</span></code> version of it at <code class="docutils literal notranslate"><span class="pre">/en/3.0/</span></code>. You can use an exact redirect to do so:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Type</span><span class="p">:</span> <span class="n">Exact</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">en</span><span class="o">/</span><span class="mf">2.0</span><span class="o">/*</span> <span class="n">To</span> <span class="n">URL</span><span class="p">:</span> <span class="o">/</span><span class="n">en</span><span class="o">/</span><span class="mf">3.0</span><span class="o">/</span><span class="p">:</span><span class="n">splat</span> </pre></div> </div> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/2.0/dev/install.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/3.0/dev/install.html</span></code>.</p></li> </ul> <div class="admonition note"> <p class="admonition-title">Note</p> <p>For this redirect to work, your old version must be disabled, if the version is still active, you can use the <code class="docutils literal notranslate"><span class="pre">Force</span> <span class="pre">Redirect</span></code> option.</p> </div> </section> <section id="creating-a-shortlink"> <h4>Creating a shortlink<a class="headerlink" href="#creating-a-shortlink" title="Link to this heading"></a></h4> <p>Say you want to redirect <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/security</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/security.html</span></code>, so it’s easier to share the link to the page. You can create a redirect with 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">Exact</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">security</span> <span class="n">To</span> <span class="n">URL</span><span class="p">:</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">security</span><span class="o">.</span><span class="n">html</span> </pre></div> </div> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/security</span></code> (no trailing slash) to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/security.html</span></code>.</p></li> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/security/</span></code> (trailing slash) to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/security.html</span></code>.</p></li> </ul> </section> <section id="migrating-your-docs-to-read-the-docs"> <h4>Migrating your docs to Read the Docs<a class="headerlink" href="#migrating-your-docs-to-read-the-docs" title="Link to this heading"></a></h4> <p>Say that you previously had your docs hosted at <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/dev/</span></code>, and choose to migrate to Read the Docs with support for multiple versions and translations. Your documentation will now be served at <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/</span></code>, but your users may have bookmarks saved with the old URL structure, for example <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/dev/install.html</span></code>.</p> <p>You can use an exact redirect with a wildcard to redirect all pages from the old URL structure to the new one:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Type</span><span class="p">:</span> <span class="n">Exact</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> <span class="n">To</span> <span class="n">URL</span><span class="p">:</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="p">:</span><span class="n">splat</span> </pre></div> </div> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/dev/install.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/install.html</span></code>.</p></li> </ul> </section> <section id="migrating-your-documentation-to-another-domain"> <h4>Migrating your documentation to another domain<a class="headerlink" href="#migrating-your-documentation-to-another-domain" title="Link to this heading"></a></h4> <p>You can use an exact redirect with the force option to migrate your documentation to another domain, for example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Type</span><span class="p">:</span> <span class="n">Exact</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">To</span> <span class="n">URL</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">newdocs</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="p">:</span><span class="n">splat</span> <span class="n">Force</span> <span class="n">Redirect</span><span class="p">:</span> <span class="kc">True</span> </pre></div> </div> <p>Users will now be redirected:</p> <ul class="simple"> <li><p>From <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/install.html</span></code> to <code class="docutils literal notranslate"><span class="pre">https://newdocs.example.com/en/latest/install.html</span></code>.</p></li> </ul> </section> <section id="changing-your-sphinx-builder-from-html-to-dirhtml"> <h4>Changing your Sphinx builder from <code class="docutils literal notranslate"><span class="pre">html</span></code> to <code class="docutils literal notranslate"><span class="pre">dirhtml</span></code><a class="headerlink" href="#changing-your-sphinx-builder-from-html-to-dirhtml" title="Link to this heading"></a></h4> <p>When you change your Sphinx builder from <code class="docutils literal notranslate"><span class="pre">html</span></code> to <code class="docutils literal notranslate"><span class="pre">dirhtml</span></code>, all your URLs will change from <code class="docutils literal notranslate"><span class="pre">/page.html</span></code> to <code class="docutils literal notranslate"><span class="pre">/page/</span></code>. You can create a redirect of type <code class="docutils literal notranslate"><span class="pre">HTML</span> <span class="pre">to</span> <span class="pre">clean</span> <span class="pre">URL</span></code> to redirect all your old URLs to the new style.</p> </section> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="flyout-menu.html" class="btn btn-neutral float-left" title="Flyout menu" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="traffic-analytics.html" class="btn btn-neutral float-right" title="Traffic analytics" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>© Copyright Read the Docs, Inc & contributors.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>