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: ``'/<language>/<version>/'`` where ``<language>`` is ``READTHEDOCS_LANGUAGE`` environment variable
   and ``<version>`` is ``READTHEDOCS_VERSION`` environment variable.
   In case these variables are 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``.
