Configuration
=============

The default settings generate the most commonly-used URL pattern on `Read the Docs <https://readthedocs.org>`_:
if you have a resource at ``_static/js/logic.js`` and you generate a 404 page with the default settings,
the URL for that resource will be ``/en/latest/_static/js/logic.js``.

For other use cases, you can customize these configuration options in your ``conf.py`` file:

.. confval:: notfound_template

   Template used to render the ``404.html`` generated by this extension.

   Default: ``'page.html'``

   Type: string

.. confval:: notfound_context

   Context passed to the template defined by ``notfound_template``.

   Default:

   .. code-block:: python

      {
          'title': 'Page not found',
          'body': "<h1>Page not found</h1>\n\nUnfortunately we couldn't find the content you were looking for.",
      }

   Type: dict

   .. note::

      If you prefer, you can create a file called ``404.rst`` and use reStructuredText to create the context of your ``404.html`` page.
      Add the ``:orphan:`` `metadata <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#metadata>`__ to the top of ``404.rst``,
      to silence the spurious ``document isn't included in any toctree`` warning.

.. confval:: notfound_pagename

   Page name generated by the extension.

   Default: ``'404'``

   Type: string

.. confval:: notfound_urls_prefix

   Prefix added to all the URLs generated in the 404 page.

   Default: The path from the `READTHEDOCS_CANONICAL_URL <https://docs.readthedocs.com/platform/stable/reference/environment-variables.html#envvar-READTHEDOCS_CANONICAL_URL>`__ environment variable.
   In case that variables is not defined, it defaults to ``/en/latest/``.

   Type: string

   .. warning::

      Make sure this config starts and ends with a ``/``.
      Otherwise, you may have unexpected behaviours.

   .. tip::

      The prefix can be completely removed by setting it to ``None``.
