diff --git a/docs/html/topics/configuration.md b/docs/html/topics/configuration.md
new file mode 100644
index 000000000..90799d574
--- /dev/null
+++ b/docs/html/topics/configuration.md
@@ -0,0 +1,226 @@
+# Configuration
+
+pip allows a user to change its behaviour via 3 mechanisms:
+
+- command line options
+- environment variables
+- configuration files
+
+This page explains how the configuration files and environment variables work,
+and how they are related to pip's various command line options.
+
+## Configuration Files
+
+Configuration files can change the default values for command line option.
+They are written using a standard INI style configuration files.
+
+pip has 3 "levels" of configuration files:
+
+- `global`: system-wide configuration file, shared across users.
+- `user`: per-user configuration file.
+- `site`: per-environment configuration file; i.e. per-virtualenv.
+
+### Location
+
+pip's configuration files are located in fairly standard locations. This
+location is different on different operating systems, and has some additional
+complexity for backwards compatibility reasons.
+
+```{tab} Unix
+
+Global
+: {file}`/etc/pip.conf`
+
+ Alternatively, it may be in a "pip" subdirectory of any of the paths set
+ in the environment variable `XDG_CONFIG_DIRS` (if it exists), for
+ example {file}`/etc/xdg/pip/pip.conf`.
+
+User
+: {file}`$HOME/.config/pip/pip.conf`, which respects the `XDG_CONFIG_HOME` environment variable.
+
+ The legacy "per-user" configuration file is also loaded, if it exists: {file}`$HOME/.pip/pip.conf`.
+
+Site
+: {file}`$VIRTUAL_ENV/pip.conf`
+```
+
+```{tab} MacOS
+
+Global
+: {file}`/Library/Application Support/pip/pip.conf`
+
+User
+: {file}`$HOME/Library/Application Support/pip/pip.conf`
+ if directory `$HOME/Library/Application Support/pip` exists
+ else {file}`$HOME/.config/pip/pip.conf`
+
+ The legacy "per-user" configuration file is also loaded, if it exists: {file}`$HOME/.pip/pip.conf`.
+
+Site
+: {file}`$VIRTUAL_ENV/pip.conf`
+```
+
+```{tab} Windows
+
+Global
+: * On Windows 7 and later: {file}`C:\\ProgramData\\pip\\pip.ini`
+ (hidden but writeable)
+ * On Windows Vista: Global configuration is not supported.
+ * On Windows XP:
+ {file}`C:\\Documents and Settings\\All Users\\Application Data\\pip\\pip.ini`
+
+User
+: {file}`%APPDATA%\\pip\\pip.ini`
+
+ The legacy "per-user" configuration file is also loaded, if it exists: {file}`%HOME%\\pip\\pip.ini`
+
+Site
+: {file}`%VIRTUAL_ENV%\\pip.ini`
+```
+
+### `PIP_CONFIG_FILE`
+
+Additionally, the environment variable `PIP_CONFIG_FILE` can be used to specify
+a configuration file that's loaded first, and whose values are overridden by
+the values set in the aforementioned files. Setting this to {ref}`os.devnull`
+disables the loading of _all_ configuration files.
+
+### Loading order
+
+When multiple configuration files are found, pip combines them in the following
+order:
+
+- `PIP_CONFIG_FILE`, if given.
+- Global
+- User
+- Site
+
+Each file read overrides any values read from previous files, so if the
+global timeout is specified in both the global file and the per-user file
+then the latter value will be used.
+
+### Naming
+
+The names of the settings are derived from the long command line option.
+
+As an example, if you want to use a different package index (`--index-url`) and
+set the HTTP timeout (`--default-timeout`) to 60 seconds, your config file would
+look like this:
+
+```ini
+[global]
+timeout = 60
+index-url = https://download.zope.org/ppix
+```
+
+### Per-command section
+
+Each subcommand can be configured optionally in its own section. This overrides
+the global setting with the same name.
+
+As an example, if you want to decrease the `timeout` to `10` seconds when
+running the {ref}`pip freeze`, and use `60` seconds for all other commands:
+
+```ini
+[global]
+timeout = 60
+
+[freeze]
+timeout = 10
+```
+
+### Boolean options
+
+Boolean options like `--ignore-installed` or `--no-dependencies` can be set
+like this:
+
+```ini
+[install]
+ignore-installed = true
+no-dependencies = yes
+```
+
+To enable the boolean options `--no-compile`, `--no-warn-script-location` and
+`--no-cache-dir`, falsy values have to be used:
+
+```ini
+[global]
+no-cache-dir = false
+
+[install]
+no-compile = no
+no-warn-script-location = false
+```
+
+### Repeatable options
+
+For options which can be repeated like `--verbose` and `--quiet`, a
+non-negative integer can be used to represent the level to be specified:
+
+```ini
+[global]
+quiet = 0
+verbose = 2
+```
+
+It is possible to append values to a section within a configuration file. This
+is applicable to appending options like `--find-links` or `--trusted-host`,
+which can be written on multiple lines:
+
+```ini
+[global]
+find-links =
+ http://download.example.com
+
+[install]
+find-links =
+ http://mirror1.example.com
+ http://mirror2.example.com
+
+trusted-host =
+ mirror1.example.com
+ mirror2.example.com
+```
+
+This enables users to add additional values in the order of entry for such
+command line arguments.
+
+## Environment Variables
+
+pip's command line options can be set with environment variables using the
+format `PIP_` . Dashes (`-`) have to be replaced with
+underscores (`_`).
+
+- `PIP_DEFAULT_TIMEOUT=60` is the same as `--default-timeout=60`
+- ```
+ PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
+ ```
+
+ is the same as
+
+ ```
+ --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
+ ```
+
+Repeatable options that do not take a value (such as `--verbose`) can be
+specified using the number of repetitions:
+
+- `PIP_VERBOSE=3` is the same as `pip install -vvv`
+
+```{note}
+Environment variables set to an empty string (like with `export X=` on Unix) will **not** be treated as false.
+Use `no`, `false` or `0` instead.
+```
+
+## Precedence / Override order
+
+Command line options have override environment variables, which override the
+values in a configuration file. Within the configuration file, values in
+command-specific sections over values in the global section.
+
+Examples:
+
+- `--host=foo` overrides `PIP_HOST=foo`
+- `PIP_HOST=foo` overrides a config file with `[global] host = foo`
+- A command specific section in the config file `[] host = bar`
+ overrides the option with same name in the `[global]` config file section.
diff --git a/docs/html/topics/index.md b/docs/html/topics/index.md
index d82e7afdb..478aacf2a 100644
--- a/docs/html/topics/index.md
+++ b/docs/html/topics/index.md
@@ -12,4 +12,5 @@ This section of the documentation is currently being fleshed out. See
authentication
caching
+configuration
```
diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst
index 967d78aef..e86fdb48c 100644
--- a/docs/html/user_guide.rst
+++ b/docs/html/user_guide.rst
@@ -437,242 +437,26 @@ For more information and examples, see the :ref:`pip search` reference.
Configuration
=============
+This is now covered in :doc:`topics/configuration`.
+
.. _config-file:
Config file
-----------
-pip allows you to set all command line option defaults in a standard ini
-style config file.
-
-The names and locations of the configuration files vary slightly across
-platforms. You may have per-user, per-virtualenv or global (shared amongst
-all users) configuration:
-
-**Per-user**:
-
-* On Unix the default configuration file is: :file:`$HOME/.config/pip/pip.conf`
- which respects the ``XDG_CONFIG_HOME`` environment variable.
-* On macOS the configuration file is
- :file:`$HOME/Library/Application Support/pip/pip.conf`
- if directory ``$HOME/Library/Application Support/pip`` exists
- else :file:`$HOME/.config/pip/pip.conf`.
-* On Windows the configuration file is :file:`%APPDATA%\\pip\\pip.ini`.
-
-There is also a legacy per-user configuration file which is also respected.
-To find its location:
-
-* On Unix and macOS the configuration file is: :file:`$HOME/.pip/pip.conf`
-* On Windows the configuration file is: :file:`%HOME%\\pip\\pip.ini`
-
-You can set a custom path location for this config file using the environment
-variable ``PIP_CONFIG_FILE``.
-
-**Inside a virtualenv**:
-
-* On Unix and macOS the file is :file:`$VIRTUAL_ENV/pip.conf`
-* On Windows the file is: :file:`%VIRTUAL_ENV%\\pip.ini`
-
-**Global**:
-
-* On Unix the file may be located in :file:`/etc/pip.conf`. Alternatively
- it may be in a "pip" subdirectory of any of the paths set in the
- environment variable ``XDG_CONFIG_DIRS`` (if it exists), for example
- :file:`/etc/xdg/pip/pip.conf`.
-* On macOS the file is: :file:`/Library/Application Support/pip/pip.conf`
-* On Windows XP the file is:
- :file:`C:\\Documents and Settings\\All Users\\Application Data\\pip\\pip.ini`
-* On Windows 7 and later the file is hidden, but writeable at
- :file:`C:\\ProgramData\\pip\\pip.ini`
-* Global configuration is not supported on Windows Vista.
-
-The global configuration file is shared by all Python installations.
-
-If multiple configuration files are found by pip then they are combined in
-the following order:
-
-1. The global file is read
-2. The per-user file is read
-3. The virtualenv-specific file is read
-
-Each file read overrides any values read from previous files, so if the
-global timeout is specified in both the global file and the per-user file
-then the latter value will be used.
-
-The names of the settings are derived from the long command line option, e.g.
-if you want to use a different package index (``--index-url``) and set the
-HTTP timeout (``--default-timeout``) to 60 seconds your config file would
-look like this:
-
-.. code-block:: ini
-
- [global]
- timeout = 60
- index-url = https://download.zope.org/ppix
-
-Each subcommand can be configured optionally in its own section so that every
-global setting with the same name will be overridden; e.g. decreasing the
-``timeout`` to ``10`` seconds when running the ``freeze``
-(:ref:`pip freeze`) command and using
-``60`` seconds for all other commands is possible with:
-
-.. code-block:: ini
-
- [global]
- timeout = 60
-
- [freeze]
- timeout = 10
-
-
-Boolean options like ``--ignore-installed`` or ``--no-dependencies`` can be
-set like this:
-
-.. code-block:: ini
-
- [install]
- ignore-installed = true
- no-dependencies = yes
-
-To enable the boolean options ``--no-compile``, ``--no-warn-script-location``
-and ``--no-cache-dir``, falsy values have to be used:
-
-.. code-block:: ini
-
- [global]
- no-cache-dir = false
-
- [install]
- no-compile = no
- no-warn-script-location = false
-
-For options which can be repeated like ``--verbose`` and ``--quiet``,
-a non-negative integer can be used to represent the level to be specified:
-
-.. code-block:: ini
-
- [global]
- quiet = 0
- verbose = 2
-
-It is possible to append values to a section within a configuration file such as the pip.ini file.
-This is applicable to appending options like ``--find-links`` or ``--trusted-host``,
-which can be written on multiple lines:
-
-.. code-block:: ini
-
- [global]
- find-links =
- http://download.example.com
-
- [install]
- find-links =
- http://mirror1.example.com
- http://mirror2.example.com
-
- trusted-host =
- mirror1.example.com
- mirror2.example.com
-
-This enables users to add additional values in the order of entry for such command line arguments.
-
+This is now covered in :doc:`topics/configuration`.
Environment Variables
---------------------
-pip's command line options can be set with environment variables using the
-format ``PIP_`` . Dashes (``-``) have to be replaced with
-underscores (``_``).
-
-For example, to set the default timeout:
-
-.. tab:: Unix/macOS
-
- .. code-block:: shell
-
- export PIP_DEFAULT_TIMEOUT=60
-
-.. tab:: Windows
-
- .. code-block:: shell
-
- set PIP_DEFAULT_TIMEOUT=60
-
-This is the same as passing the option to pip directly:
-
-.. tab:: Unix/macOS
-
- .. code-block:: shell
-
- python -m pip --default-timeout=60 [...]
-
-.. tab:: Windows
-
- .. code-block:: shell
-
- py -m pip --default-timeout=60 [...]
-
-For command line options which can be repeated, use a space to separate
-multiple values. For example:
-
-.. tab:: Unix/macOS
-
- .. code-block:: shell
-
- export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
-
-.. tab:: Windows
-
- .. code-block:: shell
-
- set PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
-
-is the same as calling:
-
-.. tab:: Unix/macOS
-
- .. code-block:: shell
-
- python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
-
-.. tab:: Windows
-
- .. code-block:: shell
-
- py -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
-
-Options that do not take a value, but can be repeated (such as ``--verbose``)
-can be specified using the number of repetitions, so::
-
- export PIP_VERBOSE=3
-
-is the same as calling::
-
- pip install -vvv
-
-.. note::
-
- Environment variables set to be empty string will not be treated as false.
- Please use ``no``, ``false`` or ``0`` instead.
-
+This is now covered in :doc:`topics/configuration`.
.. _config-precedence:
Config Precedence
-----------------
-Command line options have precedence over environment variables, which have
-precedence over the config file.
-
-Within the config file, command specific sections have precedence over the
-global section.
-
-Examples:
-
-- ``--host=foo`` overrides ``PIP_HOST=foo``
-- ``PIP_HOST=foo`` overrides a config file with ``[global] host = foo``
-- A command specific section in the config file ``[] host = bar``
- overrides the option with same name in the ``[global]`` config file section
+This is now covered in :doc:`topics/configuration`.
Command Completion