diff --git a/docs/html/development/issue-triage.md b/docs/html/development/issue-triage.md
new file mode 100644
index 00000000000..6861df7d8ae
--- /dev/null
+++ b/docs/html/development/issue-triage.md
@@ -0,0 +1,346 @@
+```{note}
+This section of the documentation is currently being written. pip
+developers welcome your help to complete this documentation. If
+you're interested in helping out, please let us know in the
+[tracking issue](https://github.com/pypa/pip/issues/6583), or
+just submit a pull request and mention it in that tracking issue.
+```
+
+# Issue Triage
+
+This serves as an introduction to issue tracking in pip as well as
+how to help triage reported issues.
+
+## Issue Tracker
+
+The [pip issue tracker](https://github.com/pypa/pip/issues) is hosted on
+GitHub alongside the project.
+
+Currently, the issue tracker is used for bugs, feature requests, and general
+user support.
+
+In the pip issue tracker, we make use of labels and milestones to organize and
+track work.
+
+### Labels
+
+Issue labels are used to:
+
+1. Categorize issues
+2. Provide status information for contributors and reporters
+3. Help contributors find tasks to work on
+
+The current set of labels are divided into several categories identified by
+prefix:
+
+**C - Category**
+: which area of `pip` functionality a feature request or issue is related to
+
+**K - Kind**
+**O - Operating System**
+: for issues that are OS-specific
+
+**P - Project/Platform**
+: related to something external to `pip`
+
+**R - Resolution**
+: no more discussion is really needed, an action has been identified and the
+issue is waiting or closed
+
+**S - State**
+: for some automatic labels and other indicators that work is needed
+
+**type**
+: the role or flavor of an issue
+
+The specific labels falling into each category have a description that can be
+seen on the [Labels](https://github.com/pypa/pip/labels) page.
+
+In addition, there are several standalone labels:
+
+**good first issue**
+: this label marks an issue as beginner-friendly and shows up in banners that
+GitHub displays for first-time visitors to the repository
+
+**triage**
+: default label given to issues when they are created
+
+**trivial**
+: special label for pull requests that removes the
+{ref}`news file requirement `
+
+**needs rebase or merge**
+
+: this is a special label used by BrownTruck to mark PRs that have merge
+conflicts
+
+### Automation
+
+There are several helpers to manage issues and pull requests.
+
+Issues created on the issue tracker are automatically given the
+`triage` label by the
+[triage-new-issues](https://github.com/apps/triage-new-issues)
+bot. The label is automatically removed when another label is added.
+
+When an issue needs feedback from the author we can label it with
+`S: awaiting response`. When the author responds, the
+[no-response](https://github.com/apps/no-response) bot removes the label.
+
+After an issue has been closed for 30 days, the
+[lock](https://github.com/apps/lock) bot locks the issue and adds the
+`S: auto-locked` label. This allows us to avoid monitoring existing closed
+issues, but unfortunately prevents and references to issues from showing up as
+links on the closed issue.
+
+## Triage Issues
+
+Users can make issues for a number of reasons:
+
+1. Suggestions about pip features that could be added or improved
+2. Problems using pip
+3. Concerns about pip usability
+4. General packaging problems to be solved with pip
+5. Problems installing or using Python packages
+6. Problems managing virtual environments
+7. Problems managing Python installations
+
+To triage issues means to identify what kind of issue is happening and
+
+- confirm bugs
+- provide support
+- discuss and design around the uses of the tool
+
+Specifically, to address an issue:
+
+1. Read issue title
+2. Scan issue description
+3. Ask questions
+4. If time is available, try to reproduce
+5. Search for or remember related issues and link to them
+6. Identify an appropriate area of concern (if applicable)
+
+Keep in mind that all communication is happening with other people and
+should be done with respect per the
+[Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/).
+
+The lifecycle of an issue (bug or support) generally looks like:
+
+1. waiting for triage (marked with label `triage`)
+
+2. confirming issue - some discussion with the user, gathering
+ details, trying to reproduce the issue (may be marked with a specific
+ category, `S: awaiting-response`, `S: discussion-needed`, or
+ `S: need-repro`)
+
+3. confirmed - the issue is pretty consistently reproducible in a
+ straightforward way, or a mechanism that could be causing the issue has been
+ identified
+
+4. awaiting fix - the fix is identified and no real discussion on the issue
+ is needed, should be marked `R: awaiting PR`
+
+5. closed - can be for several reasons
+
+ - fixed
+ - could not be reproduced, no more details could be obtained, and no
+ progress can be made
+ - actual issue was with another project or related to system
+ configuration and pip cannot (or will not) be adapted for it
+
+### Requesting information
+
+Requesting more information to better understand the context and environment
+that led to the issue. Examples of specific information that may be useful
+depending on the situation:
+
+- pip debug: `pip debug`
+- pip version: `pip -V`
+- Python version: `python -VV`
+- Python path: `python -c 'import sys; print(sys.executable)'`
+- `python` on `PATH`: Unix: `which python`; Windows: `where python`
+- Python as resolved by the shell: `type python`
+- Origin of pip (get-pip.py, OS-level package manager, ensurepip, manual
+ installation)
+- Using a virtual environment (with `--system-site-packages`?)
+- Using a conda environment
+- `PATH` environment variable
+- Network situation (e.g. airgapped environment, firewalls)
+- `--verbose` output of a failing command
+- (Unix) `strace` output from a failing command (be careful not to output
+ into the same directory as a package that's being installed, otherwise pip
+ will loop forever copying the log file...)
+- (Windows)
+ [procmon](https://docs.microsoft.com/en-us/sysinternals/downloads/procmon)
+ output during a failing command
+ ([example request](https://github.com/pypa/pip/issues/6814#issuecomment-516611389))
+- Listing of files relevant to the issue (e.g. `ls -l venv/lib/pythonX.Y/problem-package.dist-info/`)
+- whether the unexpected behavior ever worked as expected - if so then what
+ were the details of the setup (same information as above)
+
+Generally, information is good to request if it can help confirm or rule out
+possible sources of error. We shouldn't request information that does not
+improve our understanding of the situation.
+
+### Reproducing issues
+
+Whenever an issue happens and the cause isn't obvious, it is important
+that we be able to reproduce it independently. This serves several purposes:
+
+1. If it is a pip bug, then any fix will need tests - a good reproducer
+ is most of the way towards that.
+2. If it is not reproducible using the provided instructions, that helps
+ rule out a lot of possible causes.
+3. A clear set of instructions is an easy way to get on the same page as
+ someone reporting an issue.
+
+The best way to reproduce an issue is with a script.
+
+A script can be copied into a file and executed, whereas shell output
+has to be manually copied a line at a time.
+
+Scripts to reproduce issues should be:
+
+- portable (few/no assumptions about the system, other that it being Unix or Windows as applicable)
+- non-destructive
+- convenient
+- require little/no setup on the part of the runner
+
+Examples:
+
+- creating and installing multiple wheels with different versions
+ ([link](https://github.com/pypa/pip/issues/4331#issuecomment-520156471))
+- using a small web server for authentication errors
+ ([link](https://github.com/pypa/pip/issues/2920#issuecomment-508953118))
+- using docker to test system or global configuration-related issues
+ ([link](https://github.com/pypa/pip/issues/5533#issuecomment-520159896))
+- using docker to test special filesystem permission/configurations
+ ([link](https://github.com/pypa/pip/issues/6364#issuecomment-507074729))
+- using docker for global installation with get-pip
+ ([link](https://github.com/pypa/pip/issues/6498#issuecomment-513501112))
+- get-pip on system with no `/usr/lib64`
+ ([link](https://github.com/pypa/pip/issues/5379#issuecomment-515270576))
+- reproducing with `pip` from current development branch
+ ([link](https://github.com/pypa/pip/issues/6707#issue-467770959))
+
+### Reaching resolution
+
+Some user support questions are more related to system configuration than pip.
+It's important to treat these issues with the same care and attention as
+others, specifically:
+
+1. Unless the issue is very old and the user doesn't seem active, wait for
+ confirmation before closing the issue
+
+2. Direct the user to the most appropriate forum for their questions:
+
+ - For Ubuntu, [askubuntu](https://askubuntu.com/)
+ - For Other linuxes/unixes, [serverfault](https://serverfault.com/)
+ - For network connectivity issues,
+ [serverfault](https://serverfault.com/)
+
+3. Just because a user support question is best solved using some other forum
+ doesn't mean that we can't make things easier. Try to extract and
+ understand from the user query how things could have been made easier for
+ them or you, for example with better warning or error messages. If an issue
+ does not exist covering that case then create one. If an issue does exist then
+ make sure to reference that issue before closing this one.
+
+4. A user may be having trouble installing a package, where the package
+ `setup.py` or build-backend configuration is non-trivial. In these cases we
+ can help to troubleshoot but the best advice is going to be to direct them
+ to the support channels for the related projects.
+
+5. Do not be hasty to assume it is one cause or another. What looks like
+ someone else's problem may still be an issue in pip or at least something
+ that could be improved.
+
+6. For general discussion on Python packaging:
+
+ - [pypa/packaging](https://github.com/pypa/packaging-problems)
+ - [discuss.python.org/packaging](https://discuss.python.org/c/packaging)
+
+### Closing issues
+
+An issue may be considered resolved and closed when:
+
+- for each possible improvement or problem represented in the issue
+ discussion:
+
+ - Consensus has been reached on a specific action and the actions
+ appear to be external to the project, with no follow up needed
+ in the project afterwards.
+
+ - PEP updates (with a corresponding issue in
+ [python/peps](https://github.com/python/peps))
+ - already tracked by another issue
+
+ - A project-specific issue has been identified and the issue no
+ longer occurs as of the latest commit on the main branch.
+
+- An enhancement or feature request no longer has a proponent and the maintainers
+ don't think it's worth keeping open.
+
+- An issue has been identified as a duplicate, and it is clearly a duplicate (i.e. the
+ original report was very good and points directly to the issue)
+
+- The issue has been fixed, and can be independently validated as no longer being an
+ issue. If this is with code then the specific change/PR that led to it should be
+ identified and posted for tracking.
+
+## Common issues
+
+1. network-related issues - any issue involving retries, address lookup, or
+ anything like that are typically network issues.
+
+2. issues related to having multiple Python versions, or an OS package
+ manager-managed pip/python installation (specifically with Debian/Ubuntu).
+ These typically present themselves as:
+
+ 1. Not being able to find installed packages
+ 2. basic libraries not able to be found, fundamental OS components missing
+ 3. In these situations you will want to make sure that we know how they got
+ their Python and pip. Knowing the relevant package manager commands can
+ help, e.g. `dpkg -S`.
+
+## For issues caused by changes by redistributors
+
+Certain issues are caused by patches that redistributors of Python/pip
+make to Python/pip.
+
+Certain redistributors have shared preferred wording to redirect users
+to their issue trackers.
+
+Fedora, RHEL, CentOS (and probably other derivatives – Rocky, Scientific, CloudLinux):
+
+```
+This issue looks like it's caused by changes that Fedora or Red Hat
+made in their pip packaging. Please file a Fedora bug at
+https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=python-pip
+
+cc @encukou @hroncok
+```
+
+Debian:
+
+```
+This issue looks like it's caused by changes that Debian made in
+their pip packaging. Please file a bug with Debian, with
+`reportbug python3-pip` [Docs](https://www.debian.org/Bugs/Reporting).
+You can link to this issue in your bug report.
+
+In the meantime, you may be able to work-around your issue by upgrading
+pip inside your virtualenv: `python -m pip install -U pip`
+```
+
+Ubuntu:
+
+```
+This issue looks like it's caused by changes that Ubuntu made in
+their pip packaging. Please file a bug with Ubuntu, with
+`ubuntu-bug python3-pip` [Docs](https://help.ubuntu.com/community/ReportingBugs).
+You can link to this issue in your bug report.
+
+In the meantime, you may be able to work-around your issue by upgrading
+pip inside your virtualenv: `python -m pip install -U pip`
+```
diff --git a/docs/html/development/issue-triage.rst b/docs/html/development/issue-triage.rst
deleted file mode 100644
index 7a67a0a89aa..00000000000
--- a/docs/html/development/issue-triage.rst
+++ /dev/null
@@ -1,312 +0,0 @@
-.. note::
-
- This section of the documentation is currently being written. pip
- developers welcome your help to complete this documentation. If
- you're interested in helping out, please let us know in the
- `tracking issue `__, or
- just submit a pull request and mention it in that tracking issue.
-
-============
-Issue Triage
-============
-
-This serves as an introduction to issue tracking in pip as well as
-how to help triage reported issues.
-
-
-Issue Tracker
-=============
-
-The `pip issue tracker `__ is hosted on
-GitHub alongside the project.
-
-Currently, the issue tracker is used for bugs, feature requests, and general
-user support.
-
-In the pip issue tracker, we make use of labels and milestones to organize and
-track work.
-
-Labels
-------
-
-Issue labels are used to:
-
-#. Categorize issues
-#. Provide status information for contributors and reporters
-#. Help contributors find tasks to work on
-
-The current set of labels are divided into several categories identified by
-prefix:
-
-**C - Category**
- which area of ``pip`` functionality a feature request or issue is related to
-
-**K - Kind**
-
-**O - Operating System**
- for issues that are OS-specific
-
-**P - Project/Platform**
- related to something external to ``pip``
-
-**R - Resolution**
- no more discussion is really needed, an action has been identified and the
- issue is waiting or closed
-
-**S - State**
- for some automatic labels and other indicators that work is needed
-
-**type**
- the role or flavor of an issue
-
-The specific labels falling into each category have a description that can be
-seen on the `Labels `__ page.
-
-In addition, there are several standalone labels:
-
-**good first issue**
- this label marks an issue as beginner-friendly and shows up in banners that
- GitHub displays for first-time visitors to the repository
-
-**triage**
- default label given to issues when they are created
-
-**trivial**
- special label for pull requests that removes the
- :ref:`news file requirement `
-
-**needs rebase or merge**
- this is a special label used by BrownTruck to mark PRs that have merge
- conflicts
-
-Automation
-----------
-
-There are several helpers to manage issues and pull requests.
-
-Issues created on the issue tracker are automatically given the
-``triage`` label by the
-`triage-new-issues `__
-bot. The label is automatically removed when another label is added.
-
-When an issue needs feedback from the author we can label it with
-``S: awaiting response``. When the author responds, the
-`no-response `__ bot removes the label.
-
-After an issue has been closed for 30 days, the
-`lock `__ bot locks the issue and adds the
-``S: auto-locked`` label. This allows us to avoid monitoring existing closed
-issues, but unfortunately prevents and references to issues from showing up as
-links on the closed issue.
-
-
-Triage Issues
-=============
-
-Users can make issues for a number of reasons:
-
-#. Suggestions about pip features that could be added or improved
-#. Problems using pip
-#. Concerns about pip usability
-#. General packaging problems to be solved with pip
-#. Problems installing or using Python packages
-#. Problems managing virtual environments
-#. Problems managing Python installations
-
-To triage issues means to identify what kind of issue is happening and
-
-* confirm bugs
-* provide support
-* discuss and design around the uses of the tool
-
-Specifically, to address an issue:
-
-#. Read issue title
-#. Scan issue description
-#. Ask questions
-#. If time is available, try to reproduce
-#. Search for or remember related issues and link to them
-#. Identify an appropriate area of concern (if applicable)
-
-Keep in mind that all communication is happening with other people and
-should be done with respect per the
-`Code of Conduct `__.
-
-The lifecycle of an issue (bug or support) generally looks like:
-
-#. waiting for triage (marked with label ``triage``)
-#. confirming issue - some discussion with the user, gathering
- details, trying to reproduce the issue (may be marked with a specific
- category, ``S: awaiting-response``, ``S: discussion-needed``, or
- ``S: need-repro``)
-#. confirmed - the issue is pretty consistently reproducible in a
- straightforward way, or a mechanism that could be causing the issue has been
- identified
-#. awaiting fix - the fix is identified and no real discussion on the issue
- is needed, should be marked ``R: awaiting PR``
-#. closed - can be for several reasons
-
- * fixed
- * could not be reproduced, no more details could be obtained, and no
- progress can be made
- * actual issue was with another project or related to system
- configuration and pip cannot (or will not) be adapted for it
-
-
-Requesting information
-----------------------
-
-Requesting more information to better understand the context and environment
-that led to the issue. Examples of specific information that may be useful
-depending on the situation:
-
-* pip debug: ``pip debug``
-* pip version: ``pip -V``
-* Python version: ``python -VV``
-* Python path: ``python -c 'import sys; print(sys.executable)'``
-* ``python`` on ``PATH``: Unix: ``which python``; Windows: ``where python``
-* Python as resolved by the shell: ``type python``
-* Origin of pip (get-pip.py, OS-level package manager, ensurepip, manual
- installation)
-* Using a virtual environment (with ``--system-site-packages``?)
-* Using a conda environment
-* ``PATH`` environment variable
-* Network situation (e.g. airgapped environment, firewalls)
-* ``--verbose`` output of a failing command
-* (Unix) ``strace`` output from a failing command (be careful not to output
- into the same directory as a package that's being installed, otherwise pip
- will loop forever copying the log file...)
-* (Windows)
- `procmon `__
- output during a failing command
- (`example request `__)
-* Listing of files relevant to the issue (e.g. ``ls -l venv/lib/pythonX.Y/problem-package.dist-info/``)
-* whether the unexpected behavior ever worked as expected - if so then what
- were the details of the setup (same information as above)
-
-
-Generally, information is good to request if it can help confirm or rule out
-possible sources of error. We shouldn't request information that does not
-improve our understanding of the situation.
-
-
-Reproducing issues
-------------------
-
-Whenever an issue happens and the cause isn't obvious, it is important
-that we be able to reproduce it independently. This serves several purposes:
-
-#. If it is a pip bug, then any fix will need tests - a good reproducer
- is most of the way towards that.
-#. If it is not reproducible using the provided instructions, that helps
- rule out a lot of possible causes.
-#. A clear set of instructions is an easy way to get on the same page as
- someone reporting an issue.
-
-The best way to reproduce an issue is with a script.
-
-A script can be copied into a file and executed, whereas shell output
-has to be manually copied a line at a time.
-
-Scripts to reproduce issues should be:
-
-- portable (few/no assumptions about the system, other that it being Unix or Windows as applicable)
-- non-destructive
-- convenient
-- require little/no setup on the part of the runner
-
-Examples:
-
-- creating and installing multiple wheels with different versions
- (`link `__)
-- using a small web server for authentication errors
- (`link `__)
-- using docker to test system or global configuration-related issues
- (`link `__)
-- using docker to test special filesystem permission/configurations
- (`link `__)
-- using docker for global installation with get-pip
- (`link `__)
-- get-pip on system with no ``/usr/lib64``
- (`link `__)
-- reproducing with ``pip`` from current development branch
- (`link `__)
-
-
-Reaching resolution
--------------------
-
-Some user support questions are more related to system configuration than pip.
-It's important to treat these issues with the same care and attention as
-others, specifically:
-
-#. Unless the issue is very old and the user doesn't seem active, wait for
- confirmation before closing the issue
-#. Direct the user to the most appropriate forum for their questions:
-
- * For Ubuntu, `askubuntu `__
- * For Other linuxes/unixes, `serverfault `__
- * For network connectivity issues,
- `serverfault `__
-
-#. Just because a user support question is best solved using some other forum
- doesn't mean that we can't make things easier. Try to extract and
- understand from the user query how things could have been made easier for
- them or you, for example with better warning or error messages. If an issue
- does not exist covering that case then create one. If an issue does exist then
- make sure to reference that issue before closing this one.
-#. A user may be having trouble installing a package, where the package
- ``setup.py`` or build-backend configuration is non-trivial. In these cases we
- can help to troubleshoot but the best advice is going to be to direct them
- to the support channels for the related projects.
-#. Do not be hasty to assume it is one cause or another. What looks like
- someone else's problem may still be an issue in pip or at least something
- that could be improved.
-#. For general discussion on Python packaging:
-
- * `pypa/packaging `__
- * `discuss.python.org/packaging `__
-
-
-Closing issues
---------------
-
-An issue may be considered resolved and closed when:
-
-- for each possible improvement or problem represented in the issue
- discussion:
-
- - Consensus has been reached on a specific action and the actions
- appear to be external to the project, with no follow up needed
- in the project afterwards.
-
- - PEP updates (with a corresponding issue in
- `python/peps `__)
- - already tracked by another issue
-
- - A project-specific issue has been identified and the issue no
- longer occurs as of the latest commit on the main branch.
-
-- An enhancement or feature request no longer has a proponent and the maintainers
- don't think it's worth keeping open.
-- An issue has been identified as a duplicate, and it is clearly a duplicate (i.e. the
- original report was very good and points directly to the issue)
-- The issue has been fixed, and can be independently validated as no longer being an
- issue. If this is with code then the specific change/PR that led to it should be
- identified and posted for tracking.
-
-
-Common issues
-=============
-
-#. network-related issues - any issue involving retries, address lookup, or
- anything like that are typically network issues.
-#. issues related to having multiple Python versions, or an OS package
- manager-managed pip/python installation (specifically with Debian/Ubuntu).
- These typically present themselves as:
-
- #. Not being able to find installed packages
- #. basic libraries not able to be found, fundamental OS components missing
- #. In these situations you will want to make sure that we know how they got
- their Python and pip. Knowing the relevant package manager commands can
- help, e.g. ``dpkg -S``.