CINXE.COM
404 Not Found pages — Read the Docs user documentation
<!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="404 Not Found pages" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://docs.readthedocs.com/platform/stable/reference/404-not-found.html" /> <meta property="og:site_name" content="Read the Docs Documentation" /> <meta property="og:description" content="If you want your project to use a custom or branded 404 Not Found page, you can put a 404.html or 404/index.html at the top level of your project’s HTML output. How it works: When our servers return a 404 Not Found error, we check if there is a 404.html or 404/index.html in the root of your proje..." /> <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="If you want your project to use a custom or branded 404 Not Found page, you can put a 404.html or 404/index.html at the top level of your project’s HTML output. How it works: When our servers return a 404 Not Found error, we check if there is a 404.html or 404/index.html in the root of your proje..." /> <meta name="twitter:card" content="summary_large_image" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>404 Not Found pages — Read the Docs user documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" /> <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/tabs.css?v=a5c4661c" /> <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.com/platform/stable/reference/404-not-found.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=4b22ba74"></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/tabs.js?v=3030b3cb"></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="robots.txt support" href="robots.html" /> <link rel="prev" title="Sitemap support" href="sitemaps.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="/reference/404-not-found.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">Tutorial</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="../intro/doctools.html">Popular documentation tools</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="../intro/accounts.html">Account authentication methods</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="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="environment-variables.html">Environment variable reference</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Hosting documentation</span></p> <ul class="current"> <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="cdn.html">Content Delivery Network (CDN) and caching</a></li> <li class="toctree-l1"><a class="reference internal" href="sitemaps.html">Sitemap support</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> pages</a><ul> <li class="toctree-l2"><a class="reference internal" href="#how-it-works">How it works</a></li> <li class="toctree-l2"><a class="reference internal" href="#tool-integration">Tool integration</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="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="../visual-diff.html">Visual diff</a></li> <li class="toctree-l1"><a class="reference internal" href="../link-previews.html">Link previews</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> <li class="toctree-l1"><a class="reference internal" href="../user-defined-redirects.html">Redirects</a></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"><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> pages</li> <li class="wy-breadcrumbs-aside"> <a href="https://github.com/readthedocs/readthedocs.org/blob/main/docs/user/reference/404-not-found.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="not-found-pages"> <h1><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> pages<a class="headerlink" href="#not-found-pages" title="Link to this heading"></a></h1> <p>If you want your project to use a custom or branded <code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> page, you can put a <code class="docutils literal notranslate"><span class="pre">404.html</span></code> or <code class="docutils literal notranslate"><span class="pre">404/index.html</span></code> at the top level of your project’s HTML output.</p> <section id="how-it-works"> <h2>How it works<a class="headerlink" href="#how-it-works" title="Link to this heading"></a></h2> <p>When our servers return a <code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> error, we check if there is a <code class="docutils literal notranslate"><span class="pre">404.html</span></code> or <code class="docutils literal notranslate"><span class="pre">404/index.html</span></code> in the root of your project’s output.</p> <p>The following locations are checked, in order:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">/404.html</span></code> or <code class="docutils literal notranslate"><span class="pre">404/index.html</span></code> in the <em>current</em> documentation version.</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">/404.html</span></code> or <code class="docutils literal notranslate"><span class="pre">404/index.html</span></code> in the <em>default</em> documentation version.</p></li> </ul> </section> <section id="tool-integration"> <h2>Tool integration<a class="headerlink" href="#tool-integration" title="Link to this heading"></a></h2> <p>Documentation tools will have different ways of generating a <code class="docutils literal notranslate"><span class="pre">404.html</span></code> or <code class="docutils literal notranslate"><span class="pre">404/index.html</span></code> file. We have examples for some of the most popular tools below.</p> <div class="sphinx-tabs docutils container"> <div aria-label="Tabbed content" class="closeable" role="tablist"><button aria-controls="panel-0-0-0" aria-selected="true" class="sphinx-tabs-tab" id="tab-0-0-0" name="0-0" role="tab" tabindex="0">Sphinx</button><button aria-controls="panel-0-0-1" aria-selected="false" class="sphinx-tabs-tab" id="tab-0-0-1" name="0-1" role="tab" tabindex="-1">MkDocs</button></div><div aria-labelledby="tab-0-0-0" class="sphinx-tabs-panel" id="panel-0-0-0" name="0-0" role="tabpanel" tabindex="0"><p>We recommend the <a class="reference external" href="https://pypi.org/project/sphinx-notfound-page">sphinx-notfound-page</a> extension, which Read the Docs maintains. It automatically creates a <code class="docutils literal notranslate"><span class="pre">404.html</span></code> page for your documentation, matching the theme of your project. See its <a class="reference external" href="https://sphinx-notfound-page.readthedocs.io/">documentation</a> for how to install and customize it.</p> <p>If you want to create a custom <code class="docutils literal notranslate"><span class="pre">404.html</span></code>, Sphinx uses the <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path">html_extra_path</a> option to add static files to the output. You need to create a <code class="docutils literal notranslate"><span class="pre">404.html</span></code> file and put it under the path defined in <code class="docutils literal notranslate"><span class="pre">html_extra_path</span></code>.</p> <p>If you are using the <code class="docutils literal notranslate"><span class="pre">DirHTML</span></code> builder, no further steps are required. Sphinx will automatically apply the <code class="docutils literal notranslate"><span class="pre"><page-name>/index.html</span></code> folder structure to your 404 page: <code class="docutils literal notranslate"><span class="pre">404/index.html</span></code>. Read the Docs also detects 404 pages named this way.</p> </div><div aria-labelledby="tab-0-0-1" class="sphinx-tabs-panel" hidden="true" id="panel-0-0-1" name="0-1" role="tabpanel" tabindex="0"><p>MkDocs automatically generates a <code class="docutils literal notranslate"><span class="pre">404.html</span></code> which Read the Docs will use. However, assets will not be loaded correctly unless you define the <a class="reference external" href="https://www.mkdocs.org/user-guide/configuration/#site_url">site_url</a> configuration value as your site’s <a class="reference internal" href="../canonical-urls.html"><span class="doc">canonical base URL</span></a>.</p> </div></div> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="sitemaps.html" class="btn btn-neutral float-left" title="Sitemap support" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="robots.html" class="btn btn-neutral float-right" title="robots.txt support" 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>