scientific-python · henryiii · Jun 15, 2026 · Jun 15, 2026 · Jun 15, 2026
diff --git a/docs/_partials/pyproject.md b/docs/_partials/pyproject.md
@@ -1,4 +1,6 @@
-# pyproject.toml: project table
+<!-- rumdl-disable MD041 -->
+
+## pyproject.toml: project table
 
 <!-- [[[cog
 from cog_helpers import code_fence, render_cookie, TOMLMatcher
@@ -64,7 +66,7 @@ special, and replaces the old url setting.
 If you use the above configuration, you need `README.md` and `LICENSE` files,
 since they are explicitly specified.
 
-## License
+### License
 
 The license can be done one of two ways.
 
@@ -91,7 +93,7 @@ classifiers = [
 You should not include the `License ::` classifiers if you use the `license`
 field {rr}`PP007`.
 
-### Extras
+#### Extras
 
 Sometimes you want to ship a package with optional dependencies. For example,
 you might have extra requirements that are only needed for running a CLI, or for
@@ -113,7 +115,7 @@ mpl = [
 Self dependencies can be used by using the name of the package, such as
 `all = ["package[cli,mpl]"]`, (requires Pip 21.2+).
 
-### Command line
+#### Command line
 
 If you want to ship an "app" that a user can run from the command line, you need
 to add a `script` entry point. The form is:
@@ -128,7 +130,7 @@ function, followed by a colon, then the function to call. If you use
 `__main__.py` as the file, then `python -m` followed by the module will also
 work to call the app (`__name__` will be `"__main__"` in that case).
 
-### Development dependencies
+#### Development dependencies
 
 The proper way to specify dependencies exclusively used for development tasks
 (such as `pytest`, `ruff`, packages for generating documentation, etc.) is to

diff --git a/docs/pages/guides/coverage.md b/docs/pages/guides/coverage.md
@@ -1,8 +1,4 @@
----
-title: "Code coverage"
----
-
-## Code Coverage
+# Code Coverage
 
 The "Code coverage" value of a codebase indicates how much of the
 production/development code is covered by the running unit tests. Maintainers
@@ -32,7 +28,7 @@ adding weak tests just for coverage's sake is not a good idea. The tests
 should test your codebase thoroughly and should not be unreliable.
 :::
 
-### Running your tests with coverage
+## Running your tests with coverage
 
 There are two common ways to calculate coverage: using `coverage` or using
 `pytest-cov`. While `pytest-cov` is simpler on the command line, and it promises
@@ -92,7 +88,7 @@ shown below.
 :::
 ::::
 
-#### Configuring coverage
+### Configuring coverage
 
 There is a configuration section in `pyproject.toml` for coverage. Here are some
 common options
@@ -126,7 +122,7 @@ There are also useful reporting options. `report.exclude_lines = [...]` allows
 you to exclude lines from coverage. `report.fail_under` can trigger a failure if
 coverage is below a percent (like 100).
 
-#### Calculating code coverage in your workflows
+### Calculating code coverage in your workflows
 
 Your workflows should produce a `.coverage` file as outlined above. This file
 can be uploaded to `Codecov` using the [codecov/codecov-action][] action.
@@ -135,7 +131,7 @@ If you would rather do it yourself, you should collect coverage files from all
 your jobs and combine them into one `.coverage` file before running
 `coverage report`, so that you get a combined score.
 
-##### Manually combining coverage
+#### Manually combining coverage
 
 If you are running in parallel, such as with `pytest-xdist`, you can set
 `run.parallel` to `true`, which will add a unique suffix to the coverage file(s)
@@ -199,7 +195,7 @@ def tests(session: nox.Session) -> None:
 :::
 ::::
 
-##### Merging and reporting
+#### Merging and reporting
 
 If you are running in multiple jobs, you should use upload/download artifacts so
 they are all available in a single combine job at the end. Each one should have
@@ -219,7 +215,7 @@ def coverage(session: nox.Session) -> None:
     session.run("coverage", "erase")
 ```
 
-##### Configuring Codecov and uploading coverage reports
+#### Configuring Codecov and uploading coverage reports
 
 Interestingly, `Codecov` does not require any initial configurations for your
 project, given that you have already signed up for the same using your GitHub
@@ -243,7 +239,7 @@ The lines above should be added after the step that runs your tests with the
 for all the optional options. You'll need to specify a `CODECOV_TOKEN` secret,
 as well.
 
-##### Using codecov.yml
+#### Using codecov.yml
 
 One can also configure `Codecov` and coverage reports passed to `Codecov` using
 `codecov.yml`. `codecov.yml` should be placed inside the `.github` folder, along

diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md
@@ -1,8 +1,4 @@
----
-title: Writing documentation
----
-
-## Writing documentation
+# Writing documentation
 
 Documentation used to require learning reStructuredText (sometimes referred to
 as reST / rST), but today we have great choices for documentation in markdown,
@@ -45,7 +41,7 @@ is uncertain, and mkdocs-material will be minimally maintained until
 late 2026.
 :::
 
-### What to include
+## What to include
 
 Ideally, software documentation should include:
 
@@ -76,7 +72,7 @@ with render_cookie(backend="hatch", docs="mkdocs") as package:
 ]]] -->
 <!-- [[[end]]] -->
 
-### Hand-written docs
+## Hand-written docs
 
 Create `docs/` directory within your project (next to `src/`). From here, Sphinx
 and MkDocs diverge.
@@ -85,7 +81,7 @@ and MkDocs diverge.
 :::{tab-item} Sphinx
 :sync: sphinx
 
-#### pyproject.toml additions
+### pyproject.toml additions
 
 Setting a `docs` dependency group looks like this:
 
@@ -107,7 +103,7 @@ There is a sphinx-quickstart tool, but it creates unnecessary files (make/bat,
 we recommend a cross-platform noxfile instead), and uses rST instead of
 Markdown. Instead, this is our recommended starting point for `conf.py`:
 
-#### conf.py
+### conf.py
 
 <!-- [[[cog
 with code_fence("python"):
@@ -227,7 +223,7 @@ docstrings, even if the parameter isn't documented yet. Feel free to check
 [sphinx-autodoc-typehints](https://github.com/tox-dev/sphinx-autodoc-typehints)
 for more options.
 
-#### index.md
+### index.md
 
 Your `index.md` file can start out like this:
 
@@ -471,7 +467,7 @@ nav:
 :::
 ::::
 
-#### .readthedocs.yaml
+### .readthedocs.yaml
 
 In order to use <https://readthedocs.org> to build, host, and preview your
 documentation, you must have a `.readthedocs.yaml` file {rr}`RTD100` like
@@ -548,7 +544,7 @@ Python {rr}`RTD103`, several languages are supported here).
 Finally, we have a `commands` table which describes how to install our
 dependencies and build the documentation into the ReadTheDocs output directory.
 
-#### noxfile.py additions
+### noxfile.py additions
 
 Add a session to your `noxfile.py` to generate docs:
 
@@ -642,7 +638,7 @@ documentation on how to configure what directories are watched for changes,
 :::
 ::::
 
-### API docs
+## API docs
 
 ::::{tab-set}
 :::{tab-item} Sphinx
@@ -651,7 +647,7 @@ To build API docs, you need to add the following Nox job. It will rerun
 `sphinx-apidoc` to generate the sphinx autodoc pages for each of your public
 modules.
 
-#### noxfile.py additions
+### noxfile.py additions
 
 <!-- [[[cog
 with code_fence("python"):
@@ -721,7 +717,7 @@ module by being more specific, like `::: my_package.my_module.MyClass`.
 :::
 ::::
 
-### Notebooks in docs
+## Notebooks in docs
 
 ::::{tab-set}
 :::{tab-item} Sphinx

diff --git a/docs/pages/guides/gha_basic.md b/docs/pages/guides/gha_basic.md
@@ -1,9 +1,8 @@
 ---
-title: "GHA: GitHub Actions intro"
 short_title: GitHub Actions introduction
 ---
 
-## GitHub Actions: Intro
+# GitHub Actions: Intro
 
 {rr}`GH100` The recommended CI for scientific Python projects is GitHub
 Actions (GHA), although its predecessor Azure is also in heavy usage, and other
@@ -25,7 +24,7 @@ with render_cookie() as package:
 ]]] -->
 <!-- [[[end]]] -->
 
-### Header
+## Header
 
 Your main CI workflow file should begin something like this:
 
@@ -47,7 +46,7 @@ you use a develop branch, you probably will want to include that. You can also
 specify specific branches for pull requests instead of running on all PRs (will
 run on PRs targeting those branches only).
 
-### Prek / Pre-commit
+## Prek / Pre-commit
 
 If you use [prek][] or [pre-commit][] in CI, you can run it directly in GitHub
 Actions. Prek is a faster Rust rewrite of pre-commit that supports most real
@@ -91,7 +90,7 @@ run a manual check, like check-manifest, then you can keep it but just use
 this one check. You can also use `needs: lint` in your other jobs to keep them
 from running if the lint check does not pass.
 
-### Unit tests
+## Unit tests
 
 Implementing unit tests is also easy. Since you should be following best
 practices listed in the previous sections, this becomes an almost directly
@@ -158,7 +157,7 @@ Note that while versioned images are available, like `ubuntu-24.04`, these are
 all rolling images; selecting a specific image will not make your CI completely
 static. And old versioned images are decommissioned.
 
-### Updating
+## Updating
 
 {rr}`GH200` {rr}`GH210` If you use non-default actions in your repository
 (you will see some in the following pages), then it's a good idea to keep them
@@ -190,9 +189,9 @@ which is both cleaner and sometimes required for dependent actions, like
 
 You can use this for other ecosystems too, including Python.
 
-### Common needs
+## Common needs
 
-#### Single OS steps
+### Single OS steps
 
 If you need to have a step run only on a specific OS, use an if on that step
 with `runner.os`:
@@ -204,7 +203,7 @@ if: runner.os != 'Windows' # also 'macOS' and 'Linux'
 Using `runner.os` is better than `matrix.<something>`. You also have an
 environment variable `$RUNNER_OS` as well. Single quotes are required here.
 
-#### Changing the environment in a step
+### Changing the environment in a step
 
 If you need to change environment variables for later steps, such combining with
 an if condition for only for one OS, then you add it to a special file:
@@ -215,7 +214,7 @@ an if condition for only for one OS, then you add it to a special file:
 
 Later steps will see this environment variable.
 
-#### Communicating between steps
+### Communicating between steps
 
 You can also directly communicate between steps, by setting `id:`'s. Some
 actions have outputs, and bash actions can manually write to output:
@@ -230,7 +229,7 @@ You can now refer to this step in a later step with
 using `${{ needs.<jobname>.outputs.something }}`. The `toJson()` function is
 useful for inputting JSON - you can even generate matrices dynamically this way!
 
-#### Pretty output
+### Pretty output
 
 You can write GitHub flavored markdown to `$GITHUB_STEP_SUMMARY`, and it will be
 shown on the summary page.
@@ -247,7 +246,7 @@ You can also do this
 which tell GitHub to look for certain patterns. Do keep in mind you can only see
 up to 10 matches per type per step, and a total of 50 matchers.
 
-#### Common useful actions
+### Common useful actions
 
 There are a variety of useful actions. There are GitHub supplied ones:
 
@@ -325,11 +324,11 @@ You can also run GitHub Actions locally:
 - [act](https://github.com/nektos/act): Run GitHub Actions in a docker image
   locally.
 
-### Advanced usage
+## Advanced usage
 
 These are some things you might need.
 
-#### Cancel existing runs
+### Cancel existing runs
 
 {rr}`GH102` If you add the following, you can ensure only one run per
 PR/branch happens at a time, cancelling the old run when a new one starts:
@@ -345,7 +344,7 @@ the "from" name for the PR. If you want, you can replace `github.ref` with
 `github.event.pull_request.number || github.sha`; this will still cancel on PR
 pushes but will build each commit on `main`.
 
-#### Pass job
+### Pass job
 
 If you want support GitHub's "merge when pass" feature, you should set up a pass
 job instead of listing every job you wand to require. Besides making it much
@@ -382,7 +381,7 @@ allowed to be skipped (`allowed-skips:`) too.
 Just set this `pass` job in your required checks for your main branch. Then
 you'll be able to use GitHub's auto merge functionality.
 
-#### Custom actions
+### Custom actions
 
 You can
 [write your own actions](https://docs.github.com/en/actions/creating-actions)
@@ -453,7 +452,7 @@ Examples of custom composite actions include:
   (This repo)
 :::
 
-#### Reusable workflows
+### Reusable workflows
 
 You can also make reusable workflows. One reason to do this is it allows you to
 use `needs` or communicate values between workflows. It's an easy way to make
@@ -470,7 +469,7 @@ If you add a `outputs:` table to the workflow call table, you can specify
 outputs for other workflows to read. See other options
 [in the docs](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
 
-#### Conditional workflows
+### Conditional workflows
 
 Sometimes you have jobs that depend on certain files in our repository. Maybe
 you only want to run tests if code or tests files are changed, docs if
@@ -620,7 +619,7 @@ Some examples of repos using this method are:
   (this repo)
 :::
 
-#### GitHub pages
+### GitHub pages
 
 GitHub has finished moving their pages build infrastructure to Actions, and they
 [now provide](https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/)
@@ -702,7 +701,7 @@ for examples. Some other examples include:
 - [iris-hep.org](https://github.com/iris-hep/iris-hep.github.io/blob/master/.github/workflows/deploy.yml)
 :::
 
-#### Changelog generation
+### Changelog generation
 
 Not directly part of Actions, but also in `.github` is `.github/release.yml`,
 which lets you [configure the changelog generation][gh-changelog] button when