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\nThanks for trying.',
      }

   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: ``'/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``.

.. confval:: notfound_default_language

   Language used as default to generate all links to the resources.

   Default: :envvar:`READTHEDOCS_LANGUAGE` environment variable, if set, else ``'en'``

   Type: string

   .. note::

      All links generated will have this prefix (e.g. ``/en/``).
      This setting works with ``notfound_default_version`` to create a prefix for all URLs.

   .. deprecated:: 0.5

      ``notfound_default_language`` is deprecated.  Use :confval:`notfound_urls_prefix` instead

.. confval:: notfound_default_version

   Version used as default to generate all links to the resources.

   Default: :envvar:`READTHEDOCS_VERSION` environment variable, if set, else ``'latest'``

   Type: string

   .. note::

      All links generated will have this prefix (e.g. ``/latest/``).
      This setting works with ``notfound_default_language`` to create a prefix for all URLs.

   .. deprecated:: 0.5

      ``notfound_default_version`` is deprecated.  Use :confval:`notfound_urls_prefix` instead

.. confval:: notfound_no_urls_prefix

   URL prefixes skipped or included.

   Default: ``False``.

   Type: bool

   .. note::

      If this option is set to ``True``, the extension omits any prefix values from the URLs,
      including explicit values for ``notfound_default_language`` and ``notfound_default_version``.

   .. deprecated:: 0.5

      ``notfound_no_urls_prefix`` is deprecated.  Use :confval:`notfound_urls_prefix` instead
