diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst
index 6bc15349d..e7851b5e9 100644
--- a/docs/html/cli/pip_install.rst
+++ b/docs/html/cli/pip_install.rst
@@ -66,7 +66,7 @@ for the name and project version (this is in theory slightly less reliable
than using the ``egg_info`` command, but avoids downloading and processing
unnecessary numbers of files).
-Any URL may use the ``#egg=name`` syntax (see :ref:`VCS Support`) to
+Any URL may use the ``#egg=name`` syntax (see :doc:`../topics/vcs-support`) to
explicitly state the project name.
Satisfying Requirements
@@ -372,168 +372,7 @@ that enables installation of pre-releases and development releases.
VCS Support
-----------
-pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects
-the type of VCS using URL prefixes: ``git+``, ``hg+``, ``svn+``, and ``bzr+``.
-
-pip requires a working VCS command on your path: ``git``, ``hg``, ``svn``, or
-``bzr``.
-
-VCS projects can be installed in :ref:`editable mode ` (using
-the :ref:`--editable ` option) or not.
-
-* For editable installs, the clone location by default is ``/src/SomeProject`` in virtual environments, and
- ``/src/SomeProject``
- for global installs. The :ref:`--src ` option can be used to
- modify this location.
-* For non-editable installs, the project is built locally in a temp dir and then
- installed normally. Note that if a satisfactory version of the package is
- already installed, the VCS source will not overwrite it without an
- ``--upgrade`` flag. VCS requirements pin the package version (specified
- in the ``setup.py`` file) of the target commit, not necessarily the commit
- itself.
-* The :ref:`pip freeze` subcommand will record the VCS requirement specifier
- (referencing a specific commit) if and only if the install is done using the
- editable option.
-
-The "project name" component of the URL suffix ``egg=``
-is used by pip in its dependency logic to identify the project prior
-to pip downloading and analyzing the metadata. For projects
-where ``setup.py`` is not in the root of project, the "subdirectory" component
-is used. The value of the "subdirectory" component should be a path starting
-from the root of the project to where ``setup.py`` is located.
-
-If your repository layout is::
-
- pkg_dir
- ├── setup.py # setup.py for package "pkg"
- └── some_module.py
- other_dir
- └── some_file
- some_other_file
-
-Then, to install from this repository, the syntax would be:
-
-.. tab:: Unix/macOS
-
- .. code-block:: shell
-
- python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
-
-.. tab:: Windows
-
- .. code-block:: shell
-
- py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
-
-
-Git
-^^^
-
-pip currently supports cloning over ``git``, ``git+http``, ``git+https``,
-``git+ssh``, ``git+git`` and ``git+file``.
-
-.. warning::
-
- Note that the use of ``git``, ``git+git``, and ``git+http`` is discouraged.
- The former two use `the Git Protocol`_, which lacks authentication, and HTTP is
- insecure due to lack of TLS based encryption.
-
-Here are the supported forms::
-
- [-e] git+http://git.example.com/MyProject#egg=MyProject
- [-e] git+https://git.example.com/MyProject#egg=MyProject
- [-e] git+ssh://git.example.com/MyProject#egg=MyProject
- [-e] git+file:///home/user/projects/MyProject#egg=MyProject
-
-Passing a branch name, a commit hash, a tag name or a git ref is possible like so::
-
- [-e] git+https://git.example.com/MyProject.git@main#egg=MyProject
- [-e] git+https://git.example.com/MyProject.git@v1.0#egg=MyProject
- [-e] git+https://git.example.com/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
- [-e] git+https://git.example.com/MyProject.git@refs/pull/123/head#egg=MyProject
-
-When passing a commit hash, specifying a full hash is preferable to a partial
-hash because a full hash allows pip to operate more efficiently (e.g. by
-making fewer network calls).
-
-.. _`the Git Protocol`: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols
-
-Mercurial
-^^^^^^^^^
-
-The supported schemes are: ``hg+file``, ``hg+http``, ``hg+https``,
-``hg+static-http``, and ``hg+ssh``.
-
-Here are the supported forms::
-
- [-e] hg+http://hg.myproject.org/MyProject#egg=MyProject
- [-e] hg+https://hg.myproject.org/MyProject#egg=MyProject
- [-e] hg+ssh://hg.myproject.org/MyProject#egg=MyProject
- [-e] hg+file:///home/user/projects/MyProject#egg=MyProject
-
-You can also specify a revision number, a revision hash, a tag name or a local
-branch name like so::
-
- [-e] hg+http://hg.example.com/MyProject@da39a3ee5e6b#egg=MyProject
- [-e] hg+http://hg.example.com/MyProject@2019#egg=MyProject
- [-e] hg+http://hg.example.com/MyProject@v1.0#egg=MyProject
- [-e] hg+http://hg.example.com/MyProject@special_feature#egg=MyProject
-
-Subversion
-^^^^^^^^^^
-
-pip supports the URL schemes ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``, ``svn+ssh``.
-
-Here are some of the supported forms::
-
- [-e] svn+https://svn.example.com/MyProject#egg=MyProject
- [-e] svn+ssh://svn.example.com/MyProject#egg=MyProject
- [-e] svn+ssh://user@svn.example.com/MyProject#egg=MyProject
-
-You can also give specific revisions to an SVN URL, like so::
-
- [-e] svn+svn://svn.example.com/svn/MyProject#egg=MyProject
- [-e] svn+http://svn.example.com/svn/MyProject/trunk@2019#egg=MyProject
-
-which will check out revision 2019. ``@{20080101}`` would also check
-out the revision from 2008-01-01. You can only check out specific
-revisions using ``-e svn+...``.
-
-Bazaar
-^^^^^^
-
-pip supports Bazaar using the ``bzr+http``, ``bzr+https``, ``bzr+ssh``,
-``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` schemes.
-
-Here are the supported forms::
-
- [-e] bzr+http://bzr.example.com/MyProject/trunk#egg=MyProject
- [-e] bzr+sftp://user@example.com/MyProject/trunk#egg=MyProject
- [-e] bzr+ssh://user@example.com/MyProject/trunk#egg=MyProject
- [-e] bzr+ftp://user@example.com/MyProject/trunk#egg=MyProject
- [-e] bzr+lp:MyProject#egg=MyProject
-
-Tags or revisions can be installed like so::
-
- [-e] bzr+https://bzr.example.com/MyProject/trunk@2019#egg=MyProject
- [-e] bzr+http://bzr.example.com/MyProject/trunk@v1.0#egg=MyProject
-
-Using Environment Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Since version 10, pip also makes it possible to use environment variables which
-makes it possible to reference private repositories without having to store
-access tokens in the requirements file. For example, a private git repository
-allowing Basic Auth for authentication can be refenced like this::
-
- [-e] git+http://${AUTH_USER}:${AUTH_PASSWORD}@git.example.com/MyProject#egg=MyProject
- [-e] git+https://${AUTH_USER}:${AUTH_PASSWORD}@git.example.com/MyProject#egg=MyProject
-
-.. note::
-
- Only ``${VARIABLE}`` is supported, other formats like ``$VARIABLE`` or
- ``%VARIABLE%`` won't work.
+This is now covered in :doc:`../topics/vcs-support`.
Finding Packages
----------------
@@ -801,7 +640,7 @@ You can install local projects or VCS projects in "editable" mode:
py -m pip install -e git+http://repo/my_project.git#egg=SomeProject
-(See the :ref:`VCS Support` section above for more information on VCS-related syntax.)
+(See the :doc:`../topics/vcs-support` section above for more information on VCS-related syntax.)
For local projects, the "SomeProject.egg-info" directory is created relative to
the project path. This is one advantage over just using ``setup.py develop``,
@@ -992,7 +831,7 @@ Examples
py -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1
-#. Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support ` and :ref:`Editable Installs `.
+#. Install a project from VCS in "editable" mode. See the sections on :doc:`../topics/vcs-support` and :ref:`Editable Installs `.
.. tab:: Unix/macOS
diff --git a/docs/html/getting-started.md b/docs/html/getting-started.md
index 42ac2c934..5c22d1abe 100644
--- a/docs/html/getting-started.md
+++ b/docs/html/getting-started.md
@@ -47,7 +47,7 @@ $ pip install git+https://github.com/pypa/sampleproject.git@main
Successfully installed sampleproject
```
-See {ref}`VCS Support` for more information about this syntax.
+See {doc}`topics/vcs-support` for more information about this syntax.
### Install a package from a distribution file
diff --git a/docs/html/installation.md b/docs/html/installation.md
index e389a8fa4..ecb71a4aa 100644
--- a/docs/html/installation.md
+++ b/docs/html/installation.md
@@ -13,8 +13,8 @@ Usually, pip is automatically installed if you are:
If your Python environment does not have pip installed, there are 2 mechanisms
to install pip supported directly by pip's maintainers:
-- [`ensurepip`](#using-ensurepip)
-- [`get-pip.py`](#using-get-pip-py)
+- [`ensurepip`](#ensurepip)
+- [`get-pip.py`](#get-pip-py)
### `ensurepip`
diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst
index e86fdb48c..78f5f0730 100644
--- a/docs/html/user_guide.rst
+++ b/docs/html/user_guide.rst
@@ -1528,7 +1528,7 @@ Setups to test with special attention
* Continuous integration/continuous deployment setups
-* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :ref:`VCS Support`
+* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :doc:`topics/vcs-support`
* Installing from source code held in local directories