From ac3055597d52e7b4bc9b7130c8992ed716088d1c Mon Sep 17 00:00:00 2001
From: julianz- <6255571+julianz-@users.noreply.github.com>
Date: Fri, 18 Sep 2026 19:33:32 -0700
Subject: [PATCH 1/6] Convert contributing docs to Markdown

Convert .github/CONTRIBUTING.md and docs/contributing/guidelines.md
from RST to Markdown, using MyST-parser (added in #835) to render them.

In addition, fix the "Also" section linking the rendered guidelines
page back to itself: exclude it from the include instead of just
rewording it, so it only shows up when reading CONTRIBUTING.md
directly on GitHub. And drop CONTRIBUTING.md's opening pointer to
the root README, which sends readers to a file with little relevant
additional information for contributors.

Also update one link in changelog-fragments.d/README.rst that broke
once that file got pulled into the new Markdown page.
---
 .github/{CONTRIBUTING.rst => CONTRIBUTING.md} |  32 ++--
 docs/changelog-fragments.d/842.doc.rst        |   5 +
 docs/changelog-fragments.d/README.rst         |   6 +-
 docs/contributing/guidelines.md               | 137 +++++++++++++++++
 docs/contributing/guidelines.rst              | 138 ------------------
 5 files changed, 157 insertions(+), 161 deletions(-)
 rename .github/{CONTRIBUTING.rst => CONTRIBUTING.md} (63%)
 create mode 100644 docs/changelog-fragments.d/842.doc.rst
 create mode 100644 docs/contributing/guidelines.md
 delete mode 100644 docs/contributing/guidelines.rst

diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.md
similarity index 63%
rename from .github/CONTRIBUTING.rst
rename to .github/CONTRIBUTING.md
index 504b5135f9..f749d4fe86 100644
--- a/.github/CONTRIBUTING.rst
+++ b/.github/CONTRIBUTING.md
@@ -1,14 +1,10 @@
-=========================
-Contributing to |project|
-=========================
+# Contributing to Cheroot
 
-Make sure you read the `README
-<https://github.com/cherrypy/cheroot/blob/main/README.rst>`_.
-Also **ensure you set up pre-commit utility correctly** and
-tests pass in GitHub Actions CI/CD workflows.
+**Ensure you set up pre-commit utility correctly** and tests pass in
+GitHub Actions CI/CD workflows.
+
+## Submitting Pull Requests
 
-Submitting Pull Requests
-^^^^^^^^^^^^^^^^^^^^^^^^
 If you're changing the structure of the repository please create an issue
 first. Don't forget to write appropriate test cases, add them into CI process
 if applicable and make the GitHub Actions CI/CD build pass.
@@ -19,27 +15,25 @@ us able to merge your PR seamlessly.
 Please fill out the pull request template that GitHub adds to your PR
 description automatically when you open one -- it covers what kind of
 change you're making, whether it affects user-facing behavior, and a
-checklist reviewers expect to be addressed (tests, a ``changelog``
-entry, etc.). PRs that skip it may be closed without review.
+checklist reviewers expect to be addressed (tests, a `changelog` entry,
+etc.). PRs that skip it may be closed without review.
 
 If you're submitting this PR through an automated or AI-assisted tool
 that posts directly via the GitHub API, the pull request template
 isn't shown to you automatically the way it would be through the
-GitHub web UI. Fetch ``.github/PULL_REQUEST_TEMPLATE.md`` directly
+GitHub web UI. Fetch `.github/PULL_REQUEST_TEMPLATE.md` directly
 and fill it in yourself.
 
-Submitting bug reports
-^^^^^^^^^^^^^^^^^^^^^^
+## Submitting bug reports
 
-Make sure you are on latest changes and that you re-ran this command ``tox``
+Make sure you are on latest changes and that you re-ran this command `tox`
 after updating your local repository. If you can, please provide more
 information about your environment such as browser, operating system,
 python version, and any other related software versions. It is also helpful to
 post a markdown snippet demonstrating minimum reproducible example of an issue.
 
-Also
-^^^^
-See the `contribution guidelines
-<https://cheroot.cherrypy.dev/en/latest/contributing/guidelines/>`_
+## Also
+
+See the fuller [contribution guidelines](https://cheroot.cherrypy.dev/en/latest/contributing/guidelines/)
 for more detail, including code style, testing, and the change log
 process.
diff --git a/docs/changelog-fragments.d/842.doc.rst b/docs/changelog-fragments.d/842.doc.rst
new file mode 100644
index 0000000000..729753fa03
--- /dev/null
+++ b/docs/changelog-fragments.d/842.doc.rst
@@ -0,0 +1,5 @@
+Converted the contributing documentation (``.github/CONTRIBUTING.rst`` and
+``docs/contributing/guidelines.rst``) to Markdown, fixed a self-referential
+link in the "Also" section that pointed the rendered guidelines page back to
+itself, and dropped an unhelpful pointer to the project's root README
+-- by :user:`julianz-`.
diff --git a/docs/changelog-fragments.d/README.rst b/docs/changelog-fragments.d/README.rst
index 8ad074d2b0..41d81fe8ed 100644
--- a/docs/changelog-fragments.d/README.rst
+++ b/docs/changelog-fragments.d/README.rst
@@ -6,7 +6,8 @@ Adding change notes with your PRs
 It is very important to maintain a log for news of how
 updating to the new version of the software will affect
 end-users. This is why we enforce collection of the change
-fragment files in pull requests as per `Towncrier philosophy`_.
+fragment files in pull requests as per `Towncrier philosophy
+<https://towncrier.readthedocs.io/en/stable/#philosophy>`_.
 
 The idea is that when somebody makes a change, they must record
 the bits that would affect end-users only including information
@@ -111,6 +112,3 @@ File :file:`docs/changelog-fragments.d/359.bugfix.rst`:
 
    See :file:`towncrier.toml` for all available categories
    (``tool.towncrier.type``).
-
-.. _Towncrier philosophy:
-   https://towncrier.readthedocs.io/en/stable/#philosophy
diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md
new file mode 100644
index 0000000000..781a679428
--- /dev/null
+++ b/docs/contributing/guidelines.md
@@ -0,0 +1,137 @@
+```{include} ../../.github/CONTRIBUTING.md
+:end-before: "## Also"
+```
+
+## First-time setup
+
+- You need to install [Python](https://www.python.org/) 3 which is required for building docs.
+  For example, Python 3.11.
+
+  Then, [create and activate a virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments).
+  And install [tox](https://tox.readthedocs.io/en/latest/).
+
+- [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+
+- [Configure git](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup):
+
+  1. Please, identify yourself:
+
+     ```console
+     $ git config --global user.name "firstname lastname"
+     $ git config --global user.email yourname@example.com
+     ```
+
+     Use the address bound to your GitHub account so that the commits would be linked to your profile.
+
+  2. Choose an editor for Git:
+
+     ```console
+     $ git config --global core.editor vim
+     ```
+
+- Create and log in to a [GitHub](http://github.com) account
+
+- [Fork](https://help.github.com/articles/fork-a-repo/) Cheroot to your GitHub account by clicking the Fork button
+
+- [Clone](https://help.github.com/articles/cloning-a-repository/) your fork locally:
+
+  ```console
+  $ git clone https://github.com/{username}/cheroot
+  $ cd cheroot
+  ```
+
+  Also, you can [clone](https://help.github.com/articles/cloning-a-repository/) fork using [ssh](https://help.github.com/articles/connecting-to-github-with-ssh/):
+
+  ```console
+  $ git clone git@github.com:{username}/cheroot.git
+  $ cd cheroot
+  ```
+
+- To create a new [branch](https://www.atlassian.com/git/tutorials/using-branches) and switch to it:
+
+  ```console
+  $ git checkout -b patch/some_fix
+  ```
+
+## Write your code
+
+- Please, use [PEP 8](https://pep8.org/)
+
+### Once you finished coding, you are recommended to do the following steps:
+
+- Run tests with [tox](https://tox.readthedocs.io/en/latest/)
+
+Run one test with Python3.11:
+
+```console
+$ tox -e py311 -- cheroot/test/test_name.py
+```
+
+**`tox`** — Run all tests using the Python version where `python` command
+currently points to which is specified in `tox` settings:
+
+```ini
+envlist = python
+minversion = 3.21.0
+```
+
+Run linters and all tests against several Python interpreters:
+
+```console
+$ tox -e pre-commit,py310,py37  # etc.
+```
+
+- Run the [pre-commit](https://github.com/pre-commit/pre-commit) linting suite:
+
+  ```console
+  $ tox -e pre-commit
+  ```
+
+- [git add](https://git-scm.com/docs/git-add) your files
+
+- [Write good](https://chris.beams.io/posts/git-commit/) [commit messages](https://git-scm.com/docs/git-commit) when checking in your changes to Git
+
+- [Push](https://git-scm.com/docs/git-push) and [create a pull request](https://help.github.com/articles/creating-a-pull-request/)
+
+## Building the docs
+
+To build the docs from a checked out source, run:
+
+```console
+$ tox -e build-docs
+```
+
+Open the documentation:
+
+`````{tabs}
+````{tab} GNU/Linux
+```console
+$ xdg-open build/html/index.html
+```
+````
+
+````{tab} macOS
+```console
+$ open build/html/index.html
+```
+````
+
+````{tab} Windows
+Please, open `build/html/index.html` in your browser.
+````
+`````
+
+Also, one can serve docs using a built-in static files server.
+This is preferable because of possible CSRF issues.
+
+```console
+$ python3 -m http.server --directory build/html/ 8000
+```
+
+After that, you can open [http://localhost:8000/](http://localhost:8000/) in your browser.
+
+Read more about [Sphinx](https://www.sphinx-doc.org).
+
+```{eval-rst}
+.. include:: ../changelog-fragments.d/README.rst
+```
diff --git a/docs/contributing/guidelines.rst b/docs/contributing/guidelines.rst
deleted file mode 100644
index 4a03e0837f..0000000000
--- a/docs/contributing/guidelines.rst
+++ /dev/null
@@ -1,138 +0,0 @@
-.. include:: ../../.github/CONTRIBUTING.rst
-
-
-First-time setup
-~~~~~~~~~~~~~~~~
-
-- You need to install `Python`_ 3 which is required for building docs.
-  For example, Python 3.11.
-
-  Then, `create and activate a virtual environment`_.
-  And install `tox`_.
-
-- `Install git`_
-
-- `Configure git`_:
-
-1. Please, identify yourself::
-
-    $ git config --global user.name "firstname lastname"
-    $ git config --global user.email yourname@example.com
-
-* Use the address bound to your GitHub account so that the commits would be linked to your profile.
-
-2. Choose an editor for Git::
-
-    $ git config --global core.editor vim
-
-- Create and log in to a `GitHub`_ account
-
-- `Fork`_ Cheroot to your GitHub account by clicking the Fork button
-
-- `Clone`_ your fork locally::
-
-    $ git clone https://github.com/{username}/cheroot
-    $ cd cheroot
-
-* Also, you can `clone`_ fork using `ssh`_::
-
-    $ git clone git@github.com:{username}/cheroot.git
-    $ cd cheroot
-
-- To create a new `branch`_ and switch to it::
-
-    $ git checkout -b patch/some_fix
-
-.. _create and activate a virtual environment: https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments
-.. _Python: https://www.python.org/
-.. _Install git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-.. _Configure git: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup
-.. _GitHub: http://github.com
-.. _Fork: https://help.github.com/articles/fork-a-repo/
-.. _Clone: https://help.github.com/articles/cloning-a-repository/
-.. _ssh: https://help.github.com/articles/connecting-to-github-with-ssh/
-.. _branch: https://www.atlassian.com/git/tutorials/using-branches
-
-Write your code
-~~~~~~~~~~~~~~~
-
-- Please, use `PEP 8`_
-
-.. _PEP 8: https://pep8.org/
-
-Once you finished coding, you are recommended to do the following steps:
-""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-- Run tests with `tox`_
-
-Run one test with Python3.11::
-
-    $ tox -e py311 -- cheroot/test/test_name.py
-
-**``tox``** — Run all tests using the Python version where `python` command
-currently points to which is specified in ``tox`` settings::
-
-    envlist = python
-    minversion = 3.21.0
-
-Run linters and all tests against several Python interpreters::
-
-    $ tox -e pre-commit,py310,py37  # etc.
-
-- Run the `pre-commit`_ linting suite::
-
-    $ tox -e pre-commit
-
-- `git add`_ your files
-
-- `Write good`_ `commit messages`_ when checking in your changes to Git
-
-- `Push`_ and `create a pull request`_
-
-.. _tox: https://tox.readthedocs.io/en/latest/
-.. _pre-commit: https://github.com/pre-commit/pre-commit
-.. _git add: https://git-scm.com/docs/git-add
-.. _Write good: https://chris.beams.io/posts/git-commit/
-.. _commit messages: https://git-scm.com/docs/git-commit
-.. _Push: https://git-scm.com/docs/git-push
-.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/
-
-Building the docs
-~~~~~~~~~~~~~~~~~
-
-To build the docs from a checked out source, run::
-
-    $ tox -e build-docs
-
-Open the documentation:
-
-.. tabs::
-
-   .. tab:: GNU/Linux
-
-      ::
-
-          $ xdg-open build/html/index.html
-
-   .. tab:: macOS
-
-      ::
-
-          $ open build/html/index.html
-
-   .. tab:: Windows
-
-      Please, open ``build/html/index.html`` in your browser.
-
-Also, one can serve docs using a built-in static files server.
-This is preferable because of possible CSRF issues.::
-
-    $ python3 -m http.server --directory build/html/ 8000
-
-After that, you can open `http://localhost:8000/ <http://localhost:8000/>`_ in your browser.
-
-Read more about `Sphinx`_.
-
-.. _Sphinx: https://www.sphinx-doc.org
-
-.. include:: ../changelog-fragments.d/README.rst

From 0b558c6427ac182e8c3fbcf50d316daffccc6f61 Mon Sep 17 00:00:00 2001
From: julianz- <6255571+julianz-@users.noreply.github.com>
Date: Thu, 24 Sep 2026 00:08:56 -0700
Subject: [PATCH 2/6] Convert changelog-fragments README to Markdown too

This removes the eval-rst workaround needed to embed it in
guidelines.md, which was also the source of the detached-reference
bug found in review. Also updates .gitignore, which only allowlisted
README.rst by name and would have silently excluded the new file
from tracking.
---
 docs/changelog-fragments.d/.gitignore         |  2 +-
 docs/changelog-fragments.d/842.doc.rst        | 10 ++-
 .../{README.rst => README.md}                 | 87 +++++++++----------
 docs/contributing/guidelines.md               |  3 +-
 4 files changed, 49 insertions(+), 53 deletions(-)
 rename docs/changelog-fragments.d/{README.rst => README.md} (53%)

diff --git a/docs/changelog-fragments.d/.gitignore b/docs/changelog-fragments.d/.gitignore
index 4db39ea08a..51c7e37535 100644
--- a/docs/changelog-fragments.d/.gitignore
+++ b/docs/changelog-fragments.d/.gitignore
@@ -1,7 +1,7 @@
 *
 !.gitignore
 !.towncrier-template.rst.j2
-!README.rst
+!README.md
 !*.bugfix
 !*.bugfix.rst
 !*.bugfix.*.rst
diff --git a/docs/changelog-fragments.d/842.doc.rst b/docs/changelog-fragments.d/842.doc.rst
index 729753fa03..113ab801cd 100644
--- a/docs/changelog-fragments.d/842.doc.rst
+++ b/docs/changelog-fragments.d/842.doc.rst
@@ -1,5 +1,7 @@
-Converted the contributing documentation (``.github/CONTRIBUTING.rst`` and
-``docs/contributing/guidelines.rst``) to Markdown, fixed a self-referential
-link in the "Also" section that pointed the rendered guidelines page back to
-itself, and dropped an unhelpful pointer to the project's root README
+Converted the contributing documentation (``.github/CONTRIBUTING.rst``,
+``docs/contributing/guidelines.rst`` and
+``docs/changelog-fragments.d/README.rst``) to Markdown, fixed a
+self-referential link in the "Also" section that pointed the rendered
+guidelines page back to itself, and dropped an unhelpful pointer to the
+project's root README
 -- by :user:`julianz-`.
diff --git a/docs/changelog-fragments.d/README.rst b/docs/changelog-fragments.d/README.md
similarity index 53%
rename from docs/changelog-fragments.d/README.rst
rename to docs/changelog-fragments.d/README.md
index 41d81fe8ed..b7b5089eca 100644
--- a/docs/changelog-fragments.d/README.rst
+++ b/docs/changelog-fragments.d/README.md
@@ -1,13 +1,11 @@
-.. _Adding change notes with your PRs:
+(adding change notes with your prs)=
 
-Adding change notes with your PRs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Adding change notes with your PRs
 
 It is very important to maintain a log for news of how
 updating to the new version of the software will affect
 end-users. This is why we enforce collection of the change
-fragment files in pull requests as per `Towncrier philosophy
-<https://towncrier.readthedocs.io/en/stable/#philosophy>`_.
+fragment files in pull requests as per [Towncrier philosophy](https://towncrier.readthedocs.io/en/stable/#philosophy).
 
 The idea is that when somebody makes a change, they must record
 the bits that would affect end-users only including information
@@ -19,13 +17,12 @@ related details generates noise that is not particularly useful
 to the end-users most of the time. And so such details should be
 recorded in the Git history rather than a change log.
 
-Alright! So how do I add a news fragment?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Alright! So how do I add a news fragment?
 
-*Cheroot* uses `towncrier <https://pypi.org/project/towncrier/>`_
+*Cheroot* uses [towncrier](https://pypi.org/project/towncrier/)
 for change log management.
 To submit a change note about your PR, add a text file into the
-``docs/changelog-fragments.d/`` folder. It should contain an
+`docs/changelog-fragments.d/` folder. It should contain an
 explanation of what applying this PR will change in the way
 end-users interact with the project. One sentence is usually
 enough but feel free to add as many details as you feel necessary
@@ -40,38 +37,37 @@ linking parts of the docs or external sites.
 However, you do not need to reference the issue or PR numbers here
 as *towncrier* will automatically add a reference to all of the
 affected issues when rendering the news file.
-If you wish to sign your change, feel free to add ``-- by
-:user:`github-username``` at the end (replace ``github-username``
+If you wish to sign your change, feel free to add `` -- by :user:`github-username` `` at the end (replace `github-username`
 with your own!).
 
 Finally, name your file following the convention that Towncrier
 understands: it should start with the number of an issue or a
-PR followed by a dot, then add a patch type, like ``feature``,
-``doc``, ``contrib`` etc., and add ``.rst`` as a suffix. If you
+PR followed by a dot, then add a patch type, like `feature`,
+`doc`, `contrib` etc., and add `.rst` as a suffix. If you
 need to add more than one fragment, you may add an optional
 sequence number (delimited with another period) between the type
 and the suffix.
 
-In general the name will follow ``<pr_number>.<category>.rst`` pattern,
+In general the name will follow `<pr_number>.<category>.rst` pattern,
 where the categories are:
 
-- ``bugfix``: A bug fix for something we deemed an improper undesired
+- `bugfix`: A bug fix for something we deemed an improper undesired
   behavior that got corrected in the release to match pre-agreed
   expectations.
-- ``feature``: A new behavior, public APIs. That sort of stuff.
-- ``deprecation``: A declaration of future API removals and breaking
+- `feature`: A new behavior, public APIs. That sort of stuff.
+- `deprecation`: A declaration of future API removals and breaking
   changes in behavior.
-- ``breaking``: When something public gets removed in a breaking way.
+- `breaking`: When something public gets removed in a breaking way.
   Could be deprecated in an earlier release.
-- ``doc``: Notable updates to the documentation structure or build
+- `doc`: Notable updates to the documentation structure or build
   process.
-- ``packaging``: Notes for downstreams about unobvious side effects
+- `packaging`: Notes for downstreams about unobvious side effects
   and tooling. Changes in the test invocation considerations and
   runtime assumptions.
-- ``contrib``: Stuff that affects the contributor experience. e.g.
+- `contrib`: Stuff that affects the contributor experience. e.g.
   Running tests, building the docs, setting up the development
   environment.
-- ``misc``: Changes that are hard to assign to any of the above
+- `misc`: Changes that are hard to assign to any of the above
   categories.
 
 A pull request may have more than one of these components, for example
@@ -80,35 +76,34 @@ feature, in which case two fragments should be added. It is not
 necessary to make a separate documentation fragment for documentation
 changes accompanying the relevant code changes.
 
-Examples for adding change log entries to your Pull Requests
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+## Examples for adding change log entries to your Pull Requests
 
-File :file:`docs/changelog-fragments.d/77.doc.rst`:
+File {file}`docs/changelog-fragments.d/77.doc.rst`:
 
-.. code-block:: rst
+```rst
+Fixed a WSGI documentation example to support Python 3
+-- by :user:`jaymcgrath`.
+```
 
-    Fixed a WSGI documentation example to support Python 3
-    -- by :user:`jaymcgrath`.
-
-File :file:`docs/changelog-fragments.d/384.feature.rst` (could be symlinked
-to :file:`docs/changelog-fragments.d/384.doc.rst` so it shows up in several
-change log sections, and to :file:`docs/changelog-fragments.d/385.feature.rst`
-and :file:`docs/changelog-fragments.d/406.feature.rst` referencing several
+File {file}`docs/changelog-fragments.d/384.feature.rst` (could be symlinked
+to {file}`docs/changelog-fragments.d/384.doc.rst` so it shows up in several
+change log sections, and to {file}`docs/changelog-fragments.d/385.feature.rst`
+and {file}`docs/changelog-fragments.d/406.feature.rst` referencing several
 pull requests at once):
 
-.. code-block:: rst
-
-    Exposed type stubs with annotations for public API -- by :user:`kasium`.
-
-File :file:`docs/changelog-fragments.d/359.bugfix.rst`:
-
-.. code-block:: rst
+```rst
+Exposed type stubs with annotations for public API -- by :user:`kasium`.
+```
 
-    Fixed a regression from :pr:`199` that made the worker threads exit on
-    invalid connection attempts and could make the whole server unresponsive
-    once there was no workers left -- by :user:`cameronbrunner`.
+File {file}`docs/changelog-fragments.d/359.bugfix.rst`:
 
-.. tip::
+```rst
+Fixed a regression from :pr:`199` that made the worker threads exit on
+invalid connection attempts and could make the whole server unresponsive
+once there was no workers left -- by :user:`cameronbrunner`.
+```
 
-   See :file:`towncrier.toml` for all available categories
-   (``tool.towncrier.type``).
+```{tip}
+See {file}`towncrier.toml` for all available categories
+(`tool.towncrier.type`).
+```
diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md
index 781a679428..48ed47058b 100644
--- a/docs/contributing/guidelines.md
+++ b/docs/contributing/guidelines.md
@@ -132,6 +132,5 @@ After that, you can open [http://localhost:8000/](http://localhost:8000/) in you
 
 Read more about [Sphinx](https://www.sphinx-doc.org).
 
-```{eval-rst}
-.. include:: ../changelog-fragments.d/README.rst
+```{include} ../changelog-fragments.d/README.md
 ```

From 8f8dc64c1bcf0cd6844da52d52543acf98633537 Mon Sep 17 00:00:00 2001
From: julianz- <6255571+julianz-@users.noreply.github.com>
Date: Thu, 24 Sep 2026 18:17:18 -0700
Subject: [PATCH 3/6] Fix GFM compatibility in the new changelog-fragments
 README

GitHub renders this file directly as the folder's own README, using
plain GFM, not Sphinx/MyST. Drop the MyST-only anchor, {file} role,
and {tip} directive that would have rendered as broken literal text
there: the anchor moves to guidelines.md, {file} becomes plain
backtick code, and {tip} becomes GitHub's native `> [!TIP]` syntax
(needs the new "alert" MyST extension to still render properly in
Sphinx). Also fixes the pre-commit hook that only allowlisted
README.rst and not README.md.
---
 .pre-commit-config.yaml              |  2 +-
 docs/changelog-fragments.d/README.md | 21 +++++++++------------
 docs/conf.py                         |  8 ++++++++
 docs/contributing/guidelines.md      |  2 ++
 4 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c95b28b108..6f6ba6441d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -36,7 +36,7 @@ repos:
             |contrib
             |misc
           )(\.\d+)?(\.rst)?
-          |README\.rst
+          |README\.md
           |\.towncrier-template\.rst\.j2
         )
       $
diff --git a/docs/changelog-fragments.d/README.md b/docs/changelog-fragments.d/README.md
index b7b5089eca..a24febbac3 100644
--- a/docs/changelog-fragments.d/README.md
+++ b/docs/changelog-fragments.d/README.md
@@ -1,5 +1,3 @@
-(adding change notes with your prs)=
-
 ## Adding change notes with your PRs
 
 It is very important to maintain a log for news of how
@@ -78,24 +76,24 @@ changes accompanying the relevant code changes.
 
 ## Examples for adding change log entries to your Pull Requests
 
-File {file}`docs/changelog-fragments.d/77.doc.rst`:
+File `docs/changelog-fragments.d/77.doc.rst`:
 
 ```rst
 Fixed a WSGI documentation example to support Python 3
 -- by :user:`jaymcgrath`.
 ```
 
-File {file}`docs/changelog-fragments.d/384.feature.rst` (could be symlinked
-to {file}`docs/changelog-fragments.d/384.doc.rst` so it shows up in several
-change log sections, and to {file}`docs/changelog-fragments.d/385.feature.rst`
-and {file}`docs/changelog-fragments.d/406.feature.rst` referencing several
+File `docs/changelog-fragments.d/384.feature.rst` (could be symlinked
+to `docs/changelog-fragments.d/384.doc.rst` so it shows up in several
+change log sections, and to `docs/changelog-fragments.d/385.feature.rst`
+and `docs/changelog-fragments.d/406.feature.rst` referencing several
 pull requests at once):
 
 ```rst
 Exposed type stubs with annotations for public API -- by :user:`kasium`.
 ```
 
-File {file}`docs/changelog-fragments.d/359.bugfix.rst`:
+File `docs/changelog-fragments.d/359.bugfix.rst`:
 
 ```rst
 Fixed a regression from :pr:`199` that made the worker threads exit on
@@ -103,7 +101,6 @@ invalid connection attempts and could make the whole server unresponsive
 once there was no workers left -- by :user:`cameronbrunner`.
 ```
 
-```{tip}
-See {file}`towncrier.toml` for all available categories
-(`tool.towncrier.type`).
-```
+> [!TIP]
+> See `towncrier.toml` for all available categories
+> (`tool.towncrier.type`).
diff --git a/docs/conf.py b/docs/conf.py
index 1d526cae44..586ca78684 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -44,6 +44,14 @@
     'spelling_stub_ext',  # auto-loads `sphinxcontrib.spelling` if installed
 ]
 
+myst_enable_extensions = [
+    # Enables GitHub's `> [!TIP]`-style alerts to render as Sphinx
+    # admonitions too. Needed for files like README.md and
+    # CONTRIBUTING.md, which GitHub also renders directly as plain
+    # GFM -- this way the same syntax works correctly in both places.
+    'alert',
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md
index 48ed47058b..0fac949c87 100644
--- a/docs/contributing/guidelines.md
+++ b/docs/contributing/guidelines.md
@@ -132,5 +132,7 @@ After that, you can open [http://localhost:8000/](http://localhost:8000/) in you
 
 Read more about [Sphinx](https://www.sphinx-doc.org).
 
+(adding change notes with your prs)=
+
 ```{include} ../changelog-fragments.d/README.md
 ```

From cbbf0c600e801011e1e18340f8bf0ad1810a3449 Mon Sep 17 00:00:00 2001
From: julianz- <6255571+julianz-@users.noreply.github.com>
Date: Fri, 25 Sep 2026 18:09:18 -0700
Subject: [PATCH 4/6] Require myst-parser>=5.1.0 for the docs build

myst-parser was unconstrained, so GitHub Actions and ReadTheDocs
each resolved "latest" independently and landed on different
versions -- GHA got 5.1.0, ReadTheDocs got 4.0.1, which predates
the "alert" extension the last commit started relying on and broke
ReadTheDocs's build as a result. The matching lockfile for this
environment doesn't list myst-parser at all, so it was never
constraining it either way; this one-line requirement is the
complete fix on its own.
---
 dependencies/tox-docs.in | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dependencies/tox-docs.in b/dependencies/tox-docs.in
index a05afe7ee3..4935993e79 100644
--- a/dependencies/tox-docs.in
+++ b/dependencies/tox-docs.in
@@ -6,7 +6,7 @@ jaraco.packaging >= 9  # first version to load meta through PEP 517 interface
 sphinx-tabs >= 1.1.0
 
 furo
-myst-parser[linkify]  # Markdown documents support w/ in-text link detector
+myst-parser[linkify]>=5.1.0  # Markdown documents support w/ in-text link detector; >=5.1.0 for the `alert` extension
 sphinx-issues  # Sphinx roles providing support for linking GitHub
 sphinxcontrib-apidoc >= 0.3.0
 sphinxcontrib-towncrier

From d77eb24d20963466f4b205f3d01db03ac740629b Mon Sep 17 00:00:00 2001
From: julianz- <6255571+julianz-@users.noreply.github.com>
Date: Sat, 26 Sep 2026 08:27:41 -0700
Subject: [PATCH 5/6] Bring back detached reference for Towncrier philosophy
 link

Per webknjaz's review suggestions: use a Markdown reference-style
link (detached, defined at the bottom of the file) instead of an
inline link, matching the project's preference for detached
references elsewhere. Verified the reference resolves correctly both
in the Sphinx/MyST build and in GitHub's own GFM rendering.
---
 docs/changelog-fragments.d/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/changelog-fragments.d/README.md b/docs/changelog-fragments.d/README.md
index a24febbac3..74defe212a 100644
--- a/docs/changelog-fragments.d/README.md
+++ b/docs/changelog-fragments.d/README.md
@@ -3,7 +3,7 @@
 It is very important to maintain a log for news of how
 updating to the new version of the software will affect
 end-users. This is why we enforce collection of the change
-fragment files in pull requests as per [Towncrier philosophy](https://towncrier.readthedocs.io/en/stable/#philosophy).
+fragment files in pull requests as per [Towncrier philosophy].
 
 The idea is that when somebody makes a change, they must record
 the bits that would affect end-users only including information
@@ -104,3 +104,5 @@ once there was no workers left -- by :user:`cameronbrunner`.
 > [!TIP]
 > See `towncrier.toml` for all available categories
 > (`tool.towncrier.type`).
+
+[Towncrier philosophy]: https://towncrier.rtfd.io/en/stable/#philosophy

From 5bbd0db966805d4788c730b05aab4e3086608981 Mon Sep 17 00:00:00 2001
From: julianz- <6255571+julianz-@users.noreply.github.com>
Date: Sat, 26 Sep 2026 08:34:34 -0700
Subject: [PATCH 6/6] Use spaced version specs for myst-parser in tox-docs.in

Per webknjaz's review suggestion: match the spacing convention used
by the other hand-crafted entries in this file (e.g. Sphinx >= 1.8.2,
jaraco.packaging >= 9) for readability.
---
 dependencies/tox-docs.in | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dependencies/tox-docs.in b/dependencies/tox-docs.in
index 4935993e79..e8c8f67261 100644
--- a/dependencies/tox-docs.in
+++ b/dependencies/tox-docs.in
@@ -6,7 +6,7 @@ jaraco.packaging >= 9  # first version to load meta through PEP 517 interface
 sphinx-tabs >= 1.1.0
 
 furo
-myst-parser[linkify]>=5.1.0  # Markdown documents support w/ in-text link detector; >=5.1.0 for the `alert` extension
+myst-parser [linkify] >= 5.1.0  # Markdown documents support w/ in-text link detector; >=5.1.0 for the `alert` extension
 sphinx-issues  # Sphinx roles providing support for linking GitHub
 sphinxcontrib-apidoc >= 0.3.0
 sphinxcontrib-towncrier