diff --git a/.gitignore b/.gitignore
index c0c542e6..f3f339c4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -148,7 +148,6 @@ docs/assets/js/repo-review-app.min.js.map
 # NodeJS stuff, just in case (developer tooling)
 node_modules/
 package-lock.json
-package.json
 
 # readthedocs
 _readthedocs
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index caa7ca73..ea91221e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -32,7 +32,7 @@ repos:
     rev: "v0.15.14"
     hooks:
       - id: ruff-check
-        args: ["--fix", "--show-fixes"]
+        args: ["--fix"]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/pygrep-hooks
@@ -63,8 +63,13 @@ repos:
     rev: "v3.8.3"
     hooks:
       - id: prettier
-        types_or: [yaml, markdown, html, css, scss, javascript, json]
-        args: [--prose-wrap=always]
+        types_or: [yaml, html, css, scss, javascript, json]
+
+  - repo: https://github.com/rvben/rumdl-pre-commit
+    rev: v0.2.0
+    hooks:
+      - id: rumdl
+        args: [--no-exclude] # Disable all exclude patterns
 
   - repo: https://github.com/crate-ci/typos
     rev: "v1.46.3"
@@ -92,5 +97,5 @@ repos:
         name: Cog the pages
         language: python
         entry: cog -P -r -I ./helpers
-        files: "^docs/pages/guides/(packaging_compiled|docs|tasks|gha_basic).md|^copier.yml|^docs/_includes/pyproject.md"
+        files: "^docs/pages/guides/(packaging_compiled|docs|tasks|gha_basic).md|^copier.yml|^docs/_partials/pyproject.md"
         additional_dependencies: [cogapp, cookiecutter, tomlkit]
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index eb3d433f..d9961999 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,21 +1,20 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
+# Read the Docs configuration file for myst
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
   os: ubuntu-24.04
-
   tools:
-    ruby: "3.4"
-
+    nodejs: "24"
   commands:
-    - ./helpers/fetch_repo_review_app.sh
-    - bundle install
-    - >
-      JEKYLL_ENV=production bundle exec jekyll build --destination
-      _readthedocs/html --baseurl $(echo -n "$READTHEDOCS_CANONICAL_URL" | cut
-      -d '/' -f 4-)
+    # Install myst
+    - npm install -g mystmd
+    # Build the site
+    - cd docs && myst build --html
+    # Copy the output to Read the Docs expected location
+    - mkdir -p $READTHEDOCS_OUTPUT/html/
+    - cp -r docs/_build/html/. "$READTHEDOCS_OUTPUT/html"
+    # Clean up build artifacts
+    - rm -rf docs/_build
diff --git a/.ruby-version b/.ruby-version
deleted file mode 100644
index 47b322c9..00000000
--- a/.ruby-version
+++ /dev/null
@@ -1 +0,0 @@
-3.4.1
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..1633652d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,88 @@
+# Agent Guide for scientific-python/cookie
+
+This repo has three distinct concerns: a **cookiecutter/copier template** for
+new Python projects (`{{cookiecutter.project_name}}/`), a **repo-review plugin**
+(`src/sp_repo_review/`), and a **Jekyll-based developer guide** (`docs/`).
+
+## Key commands
+
+### sp-repo-review (the package)
+
+- Run tests: `uv run pytest` (or `uvx nox -s rr_tests`)
+- Run linting (pre-commit via prek): `uvx nox -s rr_lint`
+- Run pylint: `uvx nox -s rr_pylint`
+- Run the CLI: `uvx nox -s rr_run -- <path>`
+- Regenerate README check list via cog: `uvx nox -s readme`
+- Build wheel/sdist: `uvx nox -s rr_build`
+
+Important: tests run with `PYTHONWARNDEFAULTENCODING=1`.
+
+### Cookie template validation
+
+The noxfile generates temporary projects for **all 9 backends** × **vcs on/off**
+× **3 docs engines** (sphinx/mkdocs/zensical). These are slow.
+
+- `nox -s "tests(hatch)"` — run generated project tests for a single backend
+- `nox -s "lint(hatch)"` — run pre-commit (`prek`) on generated project
+- `nox -s "dist(hatch)"` — verify build output includes LICENSE
+- `nox -s "native(hatch)"` — test hatch/pdm/poetry native test runners
+- `nox -s compare_copier` — verify cookiecutter and copier produce identical
+  files
+- `nox -s compare_cruft` — verify cookiecutter and cruft produce identical files
+- `nox -s gha_bump` — bump GitHub Actions versions across docs and templates
+- `nox -s pc_bump` — bump pre-commit hook versions across docs and templates
+
+## Architecture notes
+
+- **Template directory**: `{{cookiecutter.project_name}}/` contains the
+  cookiecuttter template. Copier reads `copier.yml`; cookiecutter reads
+  `cookiecutter.json`. Keep them in sync; `compare_copier` checks this.
+- **Entry points**: `sp_repo_review` registers `repo-review`
+  checks/families/fixtures via `[project.entry-points]` in `pyproject.toml`.
+- **Generated docs**: The README check list (line ~300+) is a cog block. Do not
+  edit it by hand; run `nox -s readme` or cog will fail in CI.
+- **Cookie template `.pre-commit-config.yaml`** uses `prek` (a Rust-based
+  pre-commit alternative), not `pre-commit`.
+- **Ruff hook ID**: `.pre-commit-config.yaml` uses `ruff-check` as the hook id
+  (not `ruff`), for pre-commit 4.x compatibility.
+
+## Style and conventions
+
+- `tool.pytest.ini_options.norecursedirs` excludes
+  `{{cookiecutter.project_name}}` so pytest does not descend into the template
+  directory.
+- `tool.ruff.extend-exclude` also excludes `\{\{cookiecutter.project_name\}\}`
+  (double-escaped in TOML).
+- `tool.mypy.python_version = "3.10"`; the `sp_repo_review.*` override enforces
+  `disallow_untyped_defs=True`.
+- `tool.pylint.master.ignore-paths` ignores `src/sp_repo_review/_version.py`
+  (auto-generated by hatch-vcs).
+- Ruff selects `ALL` with many ignores; notable: `S101` (assert) and `D`
+  (docstrings) are globally disabled.
+
+## CI quirks
+
+- CI uses change detection to decide whether to run cookie tests or rr-tests.
+  Both are required to pass for the `pass` job.
+- rr-tests matrix runs on Python 3.10, 3.12, 3.14 across ubuntu/macos/windows.
+- Cookie tests reuse the same `reusable-cookie.yml` workflow.
+
+## Docs site (MyST)
+
+- Migrated from Jekyll to [MyST](https://mystmd.org) (JupyterBook 2.0) using the
+  `scientific-python-myst-theme`.
+- Node/Bun-based; from the repo root, run `bun install` then `bun run build` to
+  build the site.
+- Config: `docs/myst.yml` (TOC, project settings),
+  `docs/config/scientific-python.yml` (theme options).
+- Custom plugin: `docs/rr-role.mjs` — provides `{rr}` inline role for
+  repo-review badge spans.
+- Custom CSS: `docs/assets/css/site.css` — only `.rr-btn` badge styling remains.
+- Docs pages in `docs/pages/` contain cog blocks that auto-generate config
+  examples from the template.
+- The repo-review interactive page uses an `{iframe}` pointing to the WASM app
+  at `https://scientific-python.github.io/repo-review/`.
+- Tab-sets use `:sync: <tab-name>` for cross-page tab synchronization, where the
+  sync key is the tab label itself (e.g., `sphinx`, `mkdocs`,
+  `trusted-publishing`, `scikit-build-core`).
+- TOML code bloacks use "ini" to get syntax highlighting for now.
diff --git a/Gemfile b/Gemfile
deleted file mode 100644
index 01fee0f6..00000000
--- a/Gemfile
+++ /dev/null
@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-# Hello! This is where you manage which Jekyll version is used to run.
-# When you want to use a different version, change it below, save the
-# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
-#
-#     bundle exec jekyll serve
-#
-# This will help ensure the proper Jekyll version is running.
-# Happy Jekylling!
-
-gem 'jekyll'
-
-# This is the theme
-gem 'just-the-docs'
-
-# This is needed for GitHub Flavored Markdown
-gem 'kramdown-parser-gfm'
-
-# Used to be in the stdlib
-gem 'logger'
-
-# If you have any plugins, put them here!
-group :jekyll_plugins do
-  gem 'jekyll-feed'
-  gem 'jekyll-seo-tag'
-end
-
-group :development do
-  # Verify good coding practices in Ruby files
-  gem 'rubocop', '~>1.52', require: false
-
-  # Check links. Use:
-  #   bundle exec jekyll build
-  #   bundle exec htmlproofer --assume_extension '.html' ./_site
-  gem 'html-proofer'
-end
-
-# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
-# and associated library.
-platforms :mingw, :x64_mingw, :mswin, :jruby do
-  gem 'tzinfo'
-  gem 'tzinfo-data'
-end
-
-gem 'wdm', install_if: Gem.win_platform?
diff --git a/Gemfile.lock b/Gemfile.lock
deleted file mode 100644
index 40ecaa71..00000000
--- a/Gemfile.lock
+++ /dev/null
@@ -1,243 +0,0 @@
-GEM
-  remote: https://rubygems.org/
-  specs:
-    Ascii85 (2.0.1)
-    addressable (2.8.9)
-      public_suffix (>= 2.0.2, < 8.0)
-    afm (1.0.0)
-    ast (2.4.3)
-    async (2.38.1)
-      console (~> 1.29)
-      fiber-annotation
-      io-event (~> 1.11)
-      metrics (~> 0.12)
-      traces (~> 0.18)
-    base64 (0.3.0)
-    benchmark (0.5.0)
-    bigdecimal (3.3.1)
-    colorator (1.1.0)
-    concurrent-ruby (1.3.6)
-    console (1.34.3)
-      fiber-annotation
-      fiber-local (~> 1.1)
-      json
-    csv (3.3.5)
-    em-websocket (0.5.3)
-      eventmachine (>= 0.12.9)
-      http_parser.rb (~> 0)
-    ethon (0.18.0)
-      ffi (>= 1.15.0)
-      logger
-    eventmachine (1.2.7)
-    ffi (1.17.4-aarch64-linux-gnu)
-    ffi (1.17.4-aarch64-linux-musl)
-    ffi (1.17.4-arm-linux-gnu)
-    ffi (1.17.4-arm-linux-musl)
-    ffi (1.17.4-arm64-darwin)
-    ffi (1.17.4-x86_64-darwin)
-    ffi (1.17.4-x86_64-linux-gnu)
-    ffi (1.17.4-x86_64-linux-musl)
-    fiber-annotation (0.2.0)
-    fiber-local (1.1.0)
-      fiber-storage
-    fiber-storage (1.0.1)
-    forwardable-extended (2.6.0)
-    google-protobuf (4.34.1)
-      bigdecimal
-      rake (~> 13.3)
-    google-protobuf (4.34.1-aarch64-linux-gnu)
-      bigdecimal
-      rake (~> 13.3)
-    google-protobuf (4.34.1-aarch64-linux-musl)
-      bigdecimal
-      rake (~> 13.3)
-    google-protobuf (4.34.1-arm64-darwin)
-      bigdecimal
-      rake (~> 13.3)
-    google-protobuf (4.34.1-x86_64-darwin)
-      bigdecimal
-      rake (~> 13.3)
-    google-protobuf (4.34.1-x86_64-linux-gnu)
-      bigdecimal
-      rake (~> 13.3)
-    google-protobuf (4.34.1-x86_64-linux-musl)
-      bigdecimal
-      rake (~> 13.3)
-    hashery (2.1.2)
-    html-proofer (5.2.1)
-      addressable (~> 2.3)
-      async (~> 2.1)
-      benchmark (~> 0.5)
-      nokogiri (~> 1.13)
-      pdf-reader (~> 2.11)
-      rainbow (~> 3.0)
-      typhoeus (~> 1.3)
-      yell (~> 2.0)
-      zeitwerk (~> 2.5)
-    http_parser.rb (0.8.1)
-    i18n (1.14.8)
-      concurrent-ruby (~> 1.0)
-    io-event (1.14.5)
-    jekyll (4.4.1)
-      addressable (~> 2.4)
-      base64 (~> 0.2)
-      colorator (~> 1.0)
-      csv (~> 3.0)
-      em-websocket (~> 0.5)
-      i18n (~> 1.0)
-      jekyll-sass-converter (>= 2.0, < 4.0)
-      jekyll-watch (~> 2.0)
-      json (~> 2.6)
-      kramdown (~> 2.3, >= 2.3.1)
-      kramdown-parser-gfm (~> 1.0)
-      liquid (~> 4.0)
-      mercenary (~> 0.3, >= 0.3.6)
-      pathutil (~> 0.9)
-      rouge (>= 3.0, < 5.0)
-      safe_yaml (~> 1.0)
-      terminal-table (>= 1.8, < 4.0)
-      webrick (~> 1.7)
-    jekyll-feed (0.17.0)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-include-cache (0.2.1)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-sass-converter (3.1.0)
-      sass-embedded (~> 1.75)
-    jekyll-seo-tag (2.8.0)
-      jekyll (>= 3.8, < 5.0)
-    jekyll-watch (2.2.1)
-      listen (~> 3.0)
-    json (2.19.3)
-    just-the-docs (0.12.0)
-      jekyll (>= 3.8.5)
-      jekyll-include-cache
-      jekyll-seo-tag (>= 2.0)
-      rake (>= 12.3.1)
-    kramdown (2.5.2)
-      rexml (>= 3.4.4)
-    kramdown-parser-gfm (1.1.0)
-      kramdown (~> 2.0)
-    language_server-protocol (3.17.0.5)
-    lint_roller (1.1.0)
-    liquid (4.0.4)
-    listen (3.10.0)
-      logger
-      rb-fsevent (~> 0.10, >= 0.10.3)
-      rb-inotify (~> 0.9, >= 0.9.10)
-    logger (1.7.0)
-    mercenary (0.4.0)
-    metrics (0.15.0)
-    nokogiri (1.19.2-aarch64-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.19.2-aarch64-linux-musl)
-      racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-musl)
-      racc (~> 1.4)
-    nokogiri (1.19.2-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-musl)
-      racc (~> 1.4)
-    parallel (1.28.0)
-    parser (3.3.11.1)
-      ast (~> 2.4.1)
-      racc
-    pathutil (0.16.2)
-      forwardable-extended (~> 2.6)
-    pdf-reader (2.15.1)
-      Ascii85 (>= 1.0, < 3.0, != 2.0.0)
-      afm (>= 0.2.1, < 2)
-      hashery (~> 2.0)
-      ruby-rc4
-      ttfunk
-    prism (1.9.0)
-    public_suffix (7.0.5)
-    racc (1.8.1)
-    rainbow (3.1.1)
-    rake (13.3.1)
-    rb-fsevent (0.11.2)
-    rb-inotify (0.11.1)
-      ffi (~> 1.0)
-    regexp_parser (2.11.3)
-    rexml (3.4.4)
-    rouge (4.7.0)
-    rubocop (1.86.0)
-      json (~> 2.3)
-      language_server-protocol (~> 3.17.0.2)
-      lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
-      parser (>= 3.3.0.2)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.49.0, < 2.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
-      parser (>= 3.3.7.2)
-      prism (~> 1.7)
-    ruby-progressbar (1.13.0)
-    ruby-rc4 (0.1.5)
-    safe_yaml (1.0.5)
-    sass-embedded (1.98.0-aarch64-linux-gnu)
-      google-protobuf (~> 4.31)
-    sass-embedded (1.98.0-aarch64-linux-musl)
-      google-protobuf (~> 4.31)
-    sass-embedded (1.98.0-arm-linux-gnueabihf)
-      google-protobuf (~> 4.31)
-    sass-embedded (1.98.0-arm-linux-musleabihf)
-      google-protobuf (~> 4.31)
-    sass-embedded (1.98.0-arm64-darwin)
-      google-protobuf (~> 4.31)
-    sass-embedded (1.98.0-x86_64-darwin)
-      google-protobuf (~> 4.31)
-    sass-embedded (1.98.0-x86_64-linux-gnu)
-      google-protobuf (~> 4.31)
-    sass-embedded (1.98.0-x86_64-linux-musl)
-      google-protobuf (~> 4.31)
-    terminal-table (3.0.2)
-      unicode-display_width (>= 1.1.1, < 3)
-    traces (0.18.2)
-    ttfunk (1.8.0)
-      bigdecimal (~> 3.1)
-    typhoeus (1.6.0)
-      ethon (>= 0.18.0)
-    unicode-display_width (2.6.0)
-    wdm (0.2.0)
-    webrick (1.9.2)
-    yell (2.2.2)
-    zeitwerk (2.7.5)
-
-PLATFORMS
-  aarch64-linux
-  aarch64-linux-gnu
-  aarch64-linux-musl
-  arm-linux-gnu
-  arm-linux-gnueabihf
-  arm-linux-musl
-  arm-linux-musleabihf
-  arm64-darwin
-  x86_64-darwin
-  x86_64-linux
-  x86_64-linux-gnu
-  x86_64-linux-musl
-
-DEPENDENCIES
-  html-proofer
-  jekyll
-  jekyll-feed
-  jekyll-seo-tag
-  just-the-docs
-  kramdown-parser-gfm
-  logger
-  rubocop (~> 1.52)
-  tzinfo
-  tzinfo-data
-  wdm
-
-BUNDLED WITH
-   2.6.5
diff --git a/README.md b/README.md
index 005b5878..2aca5c4a 100644
--- a/README.md
+++ b/README.md
@@ -42,30 +42,30 @@ hand, from `{{cookiecutter.project_name}}/`).
 
 During generation you can select from the following backends for your package:
 
-1.  [hatch][]: This uses hatchling, a modern builder with nice file inclusion,
-    extendable via plugins, and good error messages. **(Recommended for pure
-    Python projects)**
-2.  [uv][]: The `uv_build` backend is written in Rust and is integrated into'
-    `uv`, meaning it can build without downloading anything extra and can even
-    avoid running Python at all when building, making it the fastest backend for
-    simple packages. No dynamic metadata support.
-3.  [flit][]: A modern, lightweight [PEP 621][] build system for pure Python
-    projects. Replaces setuptools, no MANIFEST.in, setup.py, or setup.cfg. Low
-    learning curve. Easy to bootstrap into new distributions. Difficult to get
-    the right files included, little dynamic metadata support.
-4.  [pdm][]: A modern, less opinionated all-in-one solution to pure Python
-    projects supporting standards. Replaces setuptools, venv/pipenv, pip, wheel,
-    and twine. Supports [PEP 621][].
-5.  [poetry][]: An all-in-one solution to pure Python projects. Replaces
-    setuptools, venv/pipenv, pip, wheel, and twine. Higher learning curve, but
-    is all-in-one. Makes some bad default assumptions for libraries.
-6.  [setuptools][]: The classic build system, but with the new standardized
-    configuration.
-7.  [pybind11][]: This is setuptools but with an C++ extension written in
-    [pybind11][] and wheels generated by [cibuildwheel][].
-8.  [scikit-build][]: A scikit-build (CMake) project also using pybind11, using
-    scikit-build-core. **(Recommended for C++ projects)**
-9.  [meson-python][]: A Meson project also using pybind11. (No VCS versioning)
+1. [hatch][]: This uses hatchling, a modern builder with nice file inclusion,
+   extendable via plugins, and good error messages. **(Recommended for pure
+   Python projects)**
+2. [uv][]: The `uv_build` backend is written in Rust and is integrated into'
+   `uv`, meaning it can build without downloading anything extra and can even
+   avoid running Python at all when building, making it the fastest backend for
+   simple packages. No dynamic metadata support.
+3. [flit][]: A modern, lightweight [PEP 621][] build system for pure Python
+   projects. Replaces setuptools, no MANIFEST.in, setup.py, or setup.cfg. Low
+   learning curve. Easy to bootstrap into new distributions. Difficult to get
+   the right files included, little dynamic metadata support.
+4. [pdm][]: A modern, less opinionated all-in-one solution to pure Python
+   projects supporting standards. Replaces setuptools, venv/pipenv, pip, wheel,
+   and twine. Supports [PEP 621][].
+5. [poetry][]: An all-in-one solution to pure Python projects. Replaces
+   setuptools, venv/pipenv, pip, wheel, and twine. Higher learning curve, but
+   is all-in-one. Makes some bad default assumptions for libraries.
+6. [setuptools][]: The classic build system, but with the new standardized
+   configuration.
+7. [pybind11][]: This is setuptools but with an C++ extension written in
+   [pybind11][] and wheels generated by [cibuildwheel][].
+8. [scikit-build][]: A scikit-build (CMake) project also using pybind11, using
+   scikit-build-core. **(Recommended for C++ projects)**
+9. [meson-python][]: A Meson project also using pybind11. (No VCS versioning)
 10. [maturin][]: A [PEP 621][] builder for Rust binary extensions. (No VCS
     versioning) **(Recommended for Rust projects)**
 
@@ -73,7 +73,7 @@ Currently, the best choice is probably hatch for pure Python projects, and
 scikit-build (such as the scikit-build-core + pybind11 choice) for binary
 projects.
 
-#### To use (copier version)
+### To use (copier version)
 
 Install `copier` and `copier-templates-extensions`. Using [uv][], that's:
 
@@ -132,7 +132,7 @@ There are a few example dependencies and a minimum Python version of 3.10, feel
 free to change it to whatever you actually need/want. There is also a basic
 backports structure with a small typing example.
 
-#### Contained components:
+#### Contained components
 
 - GitHub Actions runs testing for the generation itself
   - Uses nox so cookie development can be checked locally
@@ -160,7 +160,7 @@ backports structure with a small typing example.
 - A README
 - Code coverage reporting with automatic uploads to Codecov after tests run
 
-#### For developers:
+#### For developers
 
 You can test locally with [nox][]:
 
@@ -196,8 +196,6 @@ A lot of the guide, cookiecutter, and repo-review started out as part of
 [Scikit-HEP][]. These projects were merged, generalized, and combined with the
 [NSLS-II][] guide during the 2023 Scientific-Python Developers Summit.
 
-<!-- prettier-ignore-start -->
-
 [actions-badge]: https://github.com/scientific-python/cookie/actions/workflows/ci.yml/badge.svg
 [actions-link]: https://github.com/scientific-python/cookie/actions
 [cibuildwheel]: https://cibuildwheel.readthedocs.io
@@ -227,8 +225,6 @@ A lot of the guide, cookiecutter, and repo-review started out as part of
 [setuptools]: https://setuptools.readthedocs.io
 [uv]: https://docs.astral.sh/uv
 
-<!-- prettier-ignore-end -->
-
 ---
 
 ## sp-repo-review
@@ -302,7 +298,7 @@ CLI requirements are included.
 
 ## List of checks
 
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 
 <!-- [[[cog
 import itertools
@@ -440,4 +436,4 @@ Will not show up if no `setup.cfg` file is present.
 [conda-badge]: https://img.shields.io/conda/vn/conda-forge/sp-repo-review
 [conda-link]: https://github.com/conda-forge/sp-repo-review-feedstock
 
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
diff --git a/_config.yml b/_config.yml
deleted file mode 100644
index f55fae1d..00000000
--- a/_config.yml
+++ /dev/null
@@ -1,57 +0,0 @@
-title: Scientific Python Development Guide
-email: guide@scientific-python.org
-description: >-
-  This guide is maintained by the scientific Python community for the benefit of
-  fellow scientists and research software engineers.
-github_username: scientific-python
-source: docs
-
-# Build settings
-markdown: kramdown
-theme: "just-the-docs"
-plugins:
-  - jekyll-feed
-
-# Theme settings
-
-logo: "/assets/images/logo.svg"
-
-# Enable or disable the site search
-search_enabled: true
-
-# Aux links for the upper right navigation
-aux_links:
-  Scientific Python:
-    - https://scientific-python.org
-  Learn:
-    - https://learn.scientific-python.org
-  Cookie:
-    - https://github.com/scientific-python/cookie
-
-gh_edit_link: true
-gh_edit_link_text: "View source for this page on GitHub."
-gh_edit_repository: "https://github.com/scientific-python/cookie"
-gh_edit_branch: "main"
-gh_edit_source: "docs"
-gh_edit_view_mode: "tree" # "tree" or "edit"
-
-callouts:
-  warning:
-    color: red
-    title: Warning
-  note:
-    color: yellow
-    title: Note
-  important:
-    color: green
-    title: Important
-  highlight:
-    color: blue
-
-# Workaround for dep warnings
-sass:
-  quiet_deps: true
-  silence_deprecations:
-    - import
-    - color-functions
-    - global-builtin
diff --git a/action.yml b/action.yml
index 8649d4cb..007365a7 100644
--- a/action.yml
+++ b/action.yml
@@ -26,7 +26,6 @@ runs:
         python-version: "3.13"
         update-environment: false
 
-    # prettier-ignore
     - name: Run repo-review
       shell: bash
       run: >
diff --git a/bun.lock b/bun.lock
new file mode 100644
index 00000000..1b32acea
--- /dev/null
+++ b/bun.lock
@@ -0,0 +1,15 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "scientific-python-development-guide",
+      "dependencies": {
+        "mystmd": "^1.0",
+      },
+    },
+  },
+  "packages": {
+    "mystmd": ["mystmd@1.9.1", "", { "bin": { "myst": "dist/myst.cjs" } }, "sha512-ya8u48V7Hn2EtE6DJTEtrWCZEnpIboiN5Ed6lDlvMikiSk8NHUxpocR2okf3BF8vNlC7Auj5s3T/Ulj3taN6bQ=="],
+  }
+}
diff --git a/docs/_includes/head.html b/docs/_includes/head.html
deleted file mode 100644
index 732e0399..00000000
--- a/docs/_includes/head.html
+++ /dev/null
@@ -1,74 +0,0 @@
-<head>
-  <meta charset="UTF-8" />
-  <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
-
-  {% unless site.plugins contains "jekyll-seo-tag" %}
-  <title>{{ page.title }} - {{ site.title }}</title>
-
-  {% if page.description %}
-  <meta name="Description" content="{{ page.description }}" />
-  {% endif %} {% endunless %}
-
-  <link
-    rel="shortcut icon"
-    href="{% link assets/favicon.ico %}"
-    type="image/x-icon"
-  />
-
-  {% if false %}
-  <link
-    rel="stylesheet"
-    href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}"
-  />
-  {% endif %}
-
-  <script>
-    /* If `prefers-color-scheme` is not supported, fall back to default mode */
-    if (window.matchMedia('(prefers-color-scheme: dark)').media === 'not all') {
-      /* document.documentElement.style.display = 'none'; */
-      document.head.insertAdjacentHTML(
-        'beforeend',
-        '<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}" onload="document.documentElement.style.display = \'\'">',
-      );
-    }
-  </script>
-
-  <link
-    rel="stylesheet"
-    href="{{ '/assets/css/just-the-docs-dark.css' | relative_url }}"
-    media="(prefers-color-scheme: dark)"
-  />
-  <link
-    rel="stylesheet"
-    href="{{ '/assets/css/just-the-docs-light.css' | relative_url }}"
-    media="(prefers-color-scheme: light)"
-  />
-
-  {% if site.ga_tracking != nil %}
-  <script
-    async
-    src="https://www.googletagmanager.com/gtag/js?id={{ site.ga_tracking }}"
-  ></script>
-  <script>
-    window.dataLayer = window.dataLayer || [];
-    function gtag(){dataLayer.push(arguments);}
-    gtag('js', new Date());
-
-    gtag('config', '{{ site.ga_tracking }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %});
-  </script>
-
-  {% endif %} {% if site.search_enabled != false %}
-  <script
-    type="text/javascript"
-    src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"
-  ></script>
-  {% endif %}
-  <script
-    type="text/javascript"
-    src="{{ '/assets/js/just-the-docs.js' | relative_url }}"
-  ></script>
-
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-
-  {% seo %} {% include head_custom.html %}
-</head>
diff --git a/docs/_includes/head_custom.html b/docs/_includes/head_custom.html
deleted file mode 100644
index 96fd84d7..00000000
--- a/docs/_includes/head_custom.html
+++ /dev/null
@@ -1,20 +0,0 @@
-<meta name="theme-color" content="#ffffff" />
-
-{%- if page.interactive_repo_review %}
-
-<script
-  src="https://cdn.jsdelivr.net/pyodide/v0.29.3/full/pyodide.js"
-  crossorigin
-></script>
-<!-- Fonts to support Material Design -->
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap"
-/>
-<!-- Icons to support Material Design -->
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/icon?family=Material+Icons"
-/>
-<link rel="modulepreload" href="{% link assets/js/repo-review-app.min.js %}" />
-{%- endif %}
diff --git a/docs/_includes/interactive_repo_review.html b/docs/_includes/interactive_repo_review.html
deleted file mode 100644
index ce4ff0dc..00000000
--- a/docs/_includes/interactive_repo_review.html
+++ /dev/null
@@ -1,25 +0,0 @@
-<div id="root">Loading (requires javascript and WebAssembly)...</div>
-<style>
-  .main-content ul > li::before {
-    position: inherit;
-    margin-left: none;
-    color: none;
-    content: none;
-  }
-  .main-content ul {
-    padding-left: none;
-  }
-</style>
-<script type="module">
-  import { mountApp } from "{% link assets/js/repo-review-app.min.js %}";
-
-  mountApp({
-    header: false,
-    deps: [
-      "repo-review~=1.0.0",
-      "sp-repo-review==2026.04.04",
-      "validate-pyproject-schema-store==2026.04.03",
-      "validate-pyproject[all]~=0.25.0",
-    ],
-  });
-</script>
diff --git a/docs/_includes/toc.html b/docs/_includes/toc.html
deleted file mode 100644
index fb09be8b..00000000
--- a/docs/_includes/toc.html
+++ /dev/null
@@ -1,7 +0,0 @@
-<!-- prettier-ignore -->
-<details markdown="1">
-  <summary class="text-delta fs-4">Table of contents</summary>
-
-  * TOC
-  {:toc .m-1}
-</details>
diff --git a/docs/_includes/pyproject.md b/docs/_partials/pyproject.md
similarity index 95%
rename from docs/_includes/pyproject.md
rename to docs/_partials/pyproject.md
index 66bd8bd7..55b8cf65 100644
--- a/docs/_includes/pyproject.md
+++ b/docs/_partials/pyproject.md
@@ -1,4 +1,4 @@
-## pyproject.toml: project table
+# pyproject.toml: project table
 
 <!-- [[[cog
 from cog_helpers import code_fence, render_cookie, TOMLMatcher
@@ -13,8 +13,8 @@ The metadata is specified in a [standards-based][metadata] format:
 with code_fence("toml"):
     print(pyproject.get_source("project"))
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [project]
 name = "package"
 version = "0.1.0"
@@ -50,7 +50,7 @@ Homepage = "https://github.com/org/package"
 Discussions = "https://github.com/org/package/discussions"
 Changelog = "https://github.com/org/package/releases"
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 In this example, `"package"` is the name of the thing you are working on. You
@@ -64,7 +64,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.
 
@@ -82,14 +82,14 @@ other tools often did the wrong thing (such as load the entire file into the
 metadata's free-form one line text field that was intended to describe
 deviations from the classifier license(s)).
 
-```toml
+```ini
 classifiers = [
   "License :: OSI Approved :: BSD License",
 ]
 ```
 
 You should not include the `License ::` classifiers if you use the `license`
-field {% rr PP007 %}.
+field {rr}`PP007`.
 
 ### Extras
 
@@ -100,7 +100,7 @@ package or wheel name when installing, like `package[cli,mpl]`.
 
 Here is an example of a simple extras:
 
-```toml
+```ini
 [project.optional-dependencies]
 cli = [
   "click",
@@ -118,7 +118,7 @@ Self dependencies can be used by using the name of the package, such as
 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:
 
-```toml
+```ini
 [project.scripts]
 cliapp = "package.__main__:main"
 ```
@@ -138,15 +138,15 @@ forward) and they are more composable. In contrast with extras,
 dependency-groups are not available when installing your package via PyPI, but
 they are available for local installation (and can be installed separately from
 your package); the `dev` group is even installed, by default, when using `uv`'s
-high level commands like `uv run` and `uv sync`. {% rr PP0086 %} Here is an
+high level commands like `uv run` and `uv sync`. {rr}`PP006` Here is an
 example:
 
 <!-- [[[cog
 with code_fence("toml"):
     print(pyproject.get_source("dependency-groups"))
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [dependency-groups]
 test = [
   "pytest >=9",
@@ -163,7 +163,7 @@ docs = [
   "furo>=2023.08.17",
 ]
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 You can include one dependency group in another. Most tools allow you to install
diff --git a/docs/_plugins/details.rb b/docs/_plugins/details.rb
deleted file mode 100644
index 25d4d35e..00000000
--- a/docs/_plugins/details.rb
+++ /dev/null
@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module SP
-  # Sets up a details / summary block
-  class Details < Liquid::Block
-    def initialize(tag_name, markup, tokens)
-      super
-      @title = markup.strip
-    end
-
-    def render(context)
-      <<~RETURN
-        <details markdown="1">
-        <summary>#{@title}</summary>
-        #{super}
-        </details>
-      RETURN
-    end
-  end
-end
-
-Liquid::Template.register_tag('details', SP::Details)
diff --git a/docs/_plugins/repo_review.rb b/docs/_plugins/repo_review.rb
deleted file mode 100644
index 82882f56..00000000
--- a/docs/_plugins/repo_review.rb
+++ /dev/null
@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module SP
-  # Sets up a repo review badge
-  class RepoReview < Liquid::Tag
-    def initialize(tag_name, markup, tokens)
-      super
-      @code = markup.strip
-      raise SyntaxError, 'RepoReview requires a code' unless @code
-      raise SyntaxError, 'RepoReview code must not contain a space' if @code.include? ' '
-    end
-
-    def render(_context)
-      %(<span class="rr-btn" id="#{@code}">#{@code}</span>)
-    end
-  end
-end
-
-Liquid::Template.register_tag('rr', SP::RepoReview)
diff --git a/docs/_plugins/tabs.rb b/docs/_plugins/tabs.rb
deleted file mode 100644
index b182746d..00000000
--- a/docs/_plugins/tabs.rb
+++ /dev/null
@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module SP
-  # Sets up a tabs with top switcher bar
-  class Tabs < Liquid::Block
-    def initialize(tag_name, markup, tokens)
-      super
-      @group = markup.strip.empty? ? 'default' : markup.strip
-    end
-
-    def render(context)
-      tab_bar_content = ''
-      context['tabs'] = []
-      context['tab_group'] = @group
-      result = super
-
-      context['tabs'].each_with_index do |(label, title), index|
-        res = index.zero? ? ' btn-purple' : ''
-        tab_bar_content += <<~CONTENT
-          <button class="skhep-bar-item #{@group}-#{label}-btn btn m-2#{res}" onclick="openTab('#{label}', '#{@group}')">#{title}</button>
-        CONTENT
-      end
-
-      <<~RETURN
-        <div class="skhep-bar d-flex m-2" style="justify-content:center;">
-        #{tab_bar_content}
-        </div>
-        #{result}
-      RETURN
-    end
-  end
-
-  # Sets up tabs without the top switcher bar
-  class TabBodies < Liquid::Block
-    def initialize(tag_name, markup, tokens)
-      super
-      @group = markup.strip.empty? ? 'default' : markup.strip
-    end
-
-    def render(context)
-      context['tabs'] = []
-      context['tab_group'] = @group
-      super
-    end
-  end
-
-  # This is the content of each tab
-  class Tab < Liquid::Block
-    def initialize(tag_name, markup, tokens)
-      super
-      @label, @title = markup.strip.split(/ /, 2)
-    end
-
-    def render(context)
-      raise SyntaxError, "'tab' be in 'tabs' or 'tabbodies'" unless context.key?('tabs')
-
-      group = context['tab_group'] || 'default'
-      res = context['tabs'].empty? ? '' : ' style="display:none;"'
-      context['tabs'] << [@label, @title]
-      <<~RETURN
-        <div class="skhep-tab #{group}-#{@label}-tab" markdown="1"#{res}>
-        #{super}
-        </div>
-      RETURN
-    end
-  end
-end
-
-Liquid::Template.register_tag('tabs', SP::Tabs)
-Liquid::Template.register_tag('tabbodies', SP::TabBodies)
-Liquid::Template.register_tag('tab', SP::Tab)
diff --git a/docs/_sass/color_schemes/skhep.scss b/docs/_sass/color_schemes/skhep.scss
deleted file mode 100644
index acf9f5b4..00000000
--- a/docs/_sass/color_schemes/skhep.scss
+++ /dev/null
@@ -1 +0,0 @@
-$link-color: #7092be;
diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss
deleted file mode 100644
index 05d5b483..00000000
--- a/docs/_sass/custom/custom.scss
+++ /dev/null
@@ -1,155 +0,0 @@
-@media (min-width: 50rem) {
-  div.site-header {
-    height: 264px;
-    max-height: 264px;
-  }
-}
-
-details > summary {
-  font-weight: bold;
-}
-
-div.site-logo {
-  background-position: center center;
-}
-
-a.site-title {
-  padding: 0px 6px 0px 6px;
-}
-
-div.noted {
-  color: #ff6347;
-  font-weight: bold;
-  float: right;
-}
-
-a.package {
-  font-size: larger;
-  font-weight: bold;
-}
-
-div.project {
-  display: flex;
-  flex-direction: row;
-  flex-wrap: wrap;
-  justify-content: center;
-  box-shadow: 0px 5px 5px #88888840;
-  margin: 10px 0px;
-  padding: 2px;
-  border-radius: 5px;
-  background-color: #f5f6fa;
-  @media (prefers-color-scheme: dark) {
-    background-color: #000000;
-    box-shadow: 0px 0px 5px rgb(106, 143, 188);
-  }
-}
-
-div.project.affiliated {
-}
-
-div.project.deprecated {
-  background-color: #ffdad9;
-  @media (prefers-color-scheme: dark) {
-    background-color: #501109;
-  }
-}
-
-div.project .nameorlogo {
-  flex-basis: 200px;
-  flex-shrink: 0;
-  padding: 2px;
-  text-align: center;
-}
-
-div.project .nameorlogo a img {
-  vertical-align: middle;
-}
-
-div.project .description {
-  flex-basis: 150px;
-  flex-shrink: 0;
-  flex-grow: 1;
-  padding: 2px;
-}
-
-div.description .inner p {
-  display: inline;
-}
-
-pre.highlight {
-  line-height: 1.2;
-}
-
-details {
-  padding: 4px;
-  margin-bottom: 1.5rem;
-  border-radius: 4px;
-  box-shadow:
-    0 2px 3px rgba(0, 0, 0, 0.12),
-    0 3px 10px rgba(0, 0, 0, 0.08);
-  @media (prefers-color-scheme: dark) {
-    box-shadow: 0 0 4px rgba(255, 255, 255, 0.4);
-    background-color: black;
-  }
-}
-
-details:not([open]) > summary::after {
-  content: "(expand)";
-  float: right;
-}
-details[open] > summary::after {
-  content: "(close)";
-  float: right;
-}
-
-details[open] {
-  summary {
-    margin-bottom: 1em;
-  }
-  padding-bottom: 0.5em;
-}
-
-blockquote {
-  display: block;
-  margin-block-start: 0;
-  margin-block-end: 0;
-  margin-inline-start: 0;
-  margin-inline-end: 0;
-
-  padding: 4px 1em;
-  margin-bottom: 1.5rem;
-  border-radius: 4px;
-  box-shadow:
-    0 2px 3px rgba(0, 0, 0, 0.12),
-    0 3px 10px rgba(0, 0, 0, 0.08);
-  @media (prefers-color-scheme: dark) {
-    box-shadow: 0 0 4px rgba(255, 255, 255, 0.4);
-    background-color: black;
-  }
-}
-
-blockquote > h2 {
-  font-size: 16px !important;
-  text-transform: uppercase;
-  line-height: 1.25;
-  font-weight: 300;
-  letter-spacing: 2px;
-}
-
-.rr-btn {
-  border-radius: 4px;
-  background-color: #808080;
-  color: white;
-  padding: 1px 4px;
-  font-size: 9pt;
-  font-family: sans-serif;
-  display: inline-block;
-  text-align: center;
-  line-height: 1;
-}
-.rr-btn::before {
-  content: "sp-repo-review";
-  font-size: 5pt;
-  display: block;
-  text-align: center;
-}
diff --git a/docs/assets/css/site.css b/docs/assets/css/site.css
new file mode 100644
index 00000000..4b366d63
--- /dev/null
+++ b/docs/assets/css/site.css
@@ -0,0 +1,110 @@
+/* Scientific Python theme base
+ * Adapted from https://github.com/scientific-python/scientific-python-myst-theme
+ */
+
+body {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+main {
+  min-height: 0;
+  flex: 1 0 auto;
+}
+
+.article.content {
+  min-height: 0;
+}
+
+.footer {
+  flex-shrink: 0;
+  background: #013243;
+  color: white;
+  padding-left: 2rem;
+  padding-right: 2rem;
+  padding-left: 3.5rem;
+  padding-right: 3.5rem;
+
+  & .outer-grid {
+    grid-template-columns: 3fr 3fr 4fr;
+    align-items: center;
+    margin-bottom: 0rem;
+
+    & li {
+      list-style: none;
+    }
+  }
+
+  @media (max-width: 640px) {
+    & .outer-grid {
+      grid-template-columns: 1fr;
+      justify-items: start;
+    }
+  }
+
+  & a,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    color: white;
+  }
+
+  & h1 {
+    font-size: 1.25rem;
+    font-weight: bold;
+  }
+}
+
+.myst-fm-downloads-button {
+  display: none;
+}
+
+.myst-home-link {
+  font-weight: bold;
+}
+
+.bd-main .bd-content .bd-article-container {
+  max-width: 900px;
+}
+
+h1,
+h2,
+h3,
+h4 {
+  letter-spacing: -0.01em;
+}
+
+.bd-header {
+  box-shadow: none;
+}
+
+.bd-sidebar-primary {
+  border-right: 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* rr-btn: inline repo-review check badge, rendered by {rr} MyST role  */
+/* ------------------------------------------------------------------ */
+
+.rr-btn {
+  border-radius: 4px;
+  background-color: #808080;
+  color: white;
+  padding: 1px 4px;
+  font-size: 9pt;
+  font-family: sans-serif;
+  display: inline-block;
+  text-align: center;
+  line-height: 1;
+}
+
+.rr-btn::before {
+  content: "sp-repo-review";
+  font-size: 5pt;
+  display: block;
+  text-align: center;
+}
diff --git a/docs/assets/js/tabs.js b/docs/assets/js/tabs.js
deleted file mode 100644
index 41b87fdb..00000000
--- a/docs/assets/js/tabs.js
+++ /dev/null
@@ -1,36 +0,0 @@
-function openTab(tabName, groupName = "default") {
-  var tab = document.getElementsByClassName("skhep-tab");
-  for (const t of tab) {
-    if (t.classList.contains(`${groupName}-${tabName}-tab`)) {
-      t.style.display = "block";
-    } else if (
-      Array.from(t.classList).some(
-        (c) => c.startsWith(`${groupName}-`) && c.endsWith("-tab"),
-      )
-    ) {
-      t.style.display = "none";
-    }
-  }
-  var btn = document.getElementsByClassName("skhep-bar-item");
-  for (const b of btn) {
-    if (b.classList.contains(`${groupName}-${tabName}-btn`)) {
-      b.classList.add("btn-purple");
-    } else if (
-      Array.from(b.classList).some(
-        (c) => c.startsWith(`${groupName}-`) && c.endsWith("-btn"),
-      )
-    ) {
-      b.classList.remove("btn-purple");
-    }
-  }
-}
-function ready() {
-  const urlParams = new URLSearchParams(window.location.search);
-  const tabs = urlParams.getAll("tabs");
-
-  for (const tab of tabs) {
-    openTab(tab);
-  }
-}
-
-document.addEventListener("DOMContentLoaded", ready, false);
diff --git a/docs/config/scientific-python.yml b/docs/config/scientific-python.yml
new file mode 100644
index 00000000..00bf1391
--- /dev/null
+++ b/docs/config/scientific-python.yml
@@ -0,0 +1,9 @@
+version: 1
+
+site:
+  template: book-theme
+  options:
+    hide_toc: false
+    hide_footer_links: true
+    folders: true
+    hide_myst_branding: true
diff --git a/docs/myst.yml b/docs/myst.yml
new file mode 100644
index 00000000..2774e1be
--- /dev/null
+++ b/docs/myst.yml
@@ -0,0 +1,60 @@
+version: 1
+extends: config/scientific-python.yml
+
+project:
+  title: Scientific Python Development Guide
+  github: https://github.com/scientific-python/cookie
+  plugins:
+    - rr-role.mjs
+
+  toc:
+    - file: pages/index.md
+    - file: pages/tutorials/index.md
+      children:
+        - file: pages/tutorials/dev-environment.md
+        - file: pages/tutorials/module.md
+        - file: pages/tutorials/packaging.md
+        - file: pages/tutorials/test.md
+        - file: pages/tutorials/docs.md
+    - file: pages/guides/index.md
+      children:
+        - file: pages/guides/pytest.md
+        - file: pages/guides/coverage.md
+        - file: pages/guides/docs.md
+        - file: pages/guides/packaging_simple.md
+        - file: pages/guides/packaging_compiled.md
+        - file: pages/guides/packaging_classic.md
+        - file: pages/guides/style.md
+        - file: pages/guides/mypy.md
+        - file: pages/guides/gha_basic.md
+        - file: pages/guides/gha_pure.md
+        - file: pages/guides/gha_wheels.md
+        - file: pages/guides/tasks.md
+    - file: pages/principles/index.md
+      children:
+        - file: pages/principles/process.md
+        - file: pages/principles/design.md
+        - file: pages/principles/testing.md
+    - file: pages/patterns/index.md
+      children:
+        - file: pages/patterns/exports.md
+        - file: pages/patterns/backports.md
+        - file: pages/patterns/data_files.md
+    - file: pages/guides/repo_review.md
+
+site:
+  template: book-theme
+  nav:
+    - title: Scientific Python
+      url: https://scientific-python.org
+    - title: Learn
+      url: https://learn.scientific-python.org
+  actions:
+    - title: src
+      url: https://github.com/scientific-python/cookie
+  options:
+    favicon: assets/favicon.ico
+    logo: assets/images/logo.svg
+    logo_text: Scientific Python Development Guide
+    style: assets/css/site.css
+    hide_footer_links: false
diff --git a/docs/pages/guides/coverage.md b/docs/pages/guides/coverage.md
index d1469897..18ca0be8 100644
--- a/docs/pages/guides/coverage.md
+++ b/docs/pages/guides/coverage.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: "Code coverage"
-permalink: /guides/coverage/
-nav_order: 3
-parent: Topical Guides
 ---
 
-{% include toc.html %}
-
-# 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
@@ -27,20 +21,16 @@ Tools and libraries used to calculate, read, and visualize coverage reports:
 - `GitHub Actions`: allows users to automatically upload coverage reports to
   `Codecov`
 
-{: .note-title }
-
-> Are there any alternatives?
->
-> Coveralls is an alternative coverage platform, but we recommend using Codecov
-> because of its ease of use and integration with GitHub Actions.
-
-{: .highlight-title }
+:::{note} Are there any alternatives?
+Coveralls is an alternative coverage platform, but we recommend using Codecov
+because of its ease of use and integration with GitHub Actions.
+:::
 
-> Should increasing the coverage value be my top priority?
->
-> A low coverage percentage will definitely motivate you to add more tests, but
-> 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.
+:::{tip} Should increasing the coverage value be my top priority?
+A low coverage percentage will definitely motivate you to add more tests, but
+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
 
@@ -53,8 +43,9 @@ directly is hidden away from normal use, so we recommend that, but will show
 both methods below. If you are not running `pytest`, but instead are running an
 example or a script, you have to use `coverage` directly.
 
-{% tabs %} {% tab cov coverage %}
-
+::::{tab-set}
+:::{tab-item} coverage
+:sync: coverage
 Make sure you install `coverage[toml]`.
 
 `coverage` has several commands; the most important one is `coverage run`. This
@@ -75,9 +66,9 @@ coverage report
 
 This looks for a `.coverage` file and displays the result. There are many output
 formats for reports.
-
-{% endtab %} {% tab pycov pytest-cov %}
-
+:::
+:::{tab-item} pytest-cov
+:sync: pytest-cov
 Make sure you install `pytest-cov`.
 
 `pytest` allows users to pass the `--cov` option to automatically invoke
@@ -98,16 +89,16 @@ See the [docs](https://pytest-cov.readthedocs.io/en/latest/) for more options.
 Coverage pytest arguments can be placed in your pytest configuration file or in
 your task runner. It also will (mostly) respect the coverage configuration,
 shown below.
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-### Configuring coverage
+#### Configuring coverage
 
 There is a configuration section in `pyproject.toml` for coverage. Here are some
 common options
 [(see the docs for more)](https://coverage.readthedocs.io/en/latest/config.html):
 
-```toml
+```ini
 [tool.coverage]
 run.core = "sysmon"
 run.disable_warnings = ["no-sysmon"]
@@ -135,7 +126,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.
@@ -144,7 +135,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, either with `pytest-xdist`, you can set
 `run.parallel` to `true`, which will add a unique suffix to the coverage file(s)
@@ -158,42 +149,39 @@ manually produce multiple files from task runner jobs.
 
 Here's an example nox job:
 
-{% tabs %} {% tab cov coverage %}
+::::{tab-set}
+:::{tab-item} coverage
+:sync: coverage
 
 ```python
-@nox.session(python=ALL_PYTHONS)
-def tests(session: nox.Session) -> None:
-    coverage_file = f".coverage.{sys.platform}.{session.python}"
-    session.install("-e.", "--group=cov")
-    session.run(
-        "coverage",
-        "run",
-        "-m",
-        "pytest",
-        *session.posargs,
-        env={"COVERAGE_FILE": coverage_file},
-    )
+session.run(
+    "coverage",
+    "run",
+    "-m",
+    "pytest",
+    *session.posargs,
+    env={"COVERAGE_FILE": coverage_file},
+)
 ```
 
-{% endtab %} {% tab pycov pytest-cov %}
+:::
+:::{tab-item} pytest-cov
+:sync: pytest-cov
 
 ```python
-@nox.session(python=ALL_PYTHONS)
-def tests(session: nox.Session) -> None:
-    coverage_file = f".coverage.{sys.platform}.{session.python}"
-    session.install("-e.", "--group=cov")
-    session.run(
-        "pytest",
-        "--cov=<package_name>",
-        "--cov-config=pyproject.toml",
-        *session.posargs,
-        env={"COVERAGE_FILE": coverage_file},
-    )
+session.run(
+    "pytest",
+    "--cov=<package_name>",
+    "--cov-config=pyproject.toml",
+    *session.posargs,
+    env={"COVERAGE_FILE": coverage_file},
+)
 ```
 
-{% endtab %} {% endtabs %}
+:::
+::::
 
-#### 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
@@ -213,7 +201,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
@@ -225,8 +213,6 @@ uploading coverage reports easy for users. A minimal working example for
 uploading coverage reports through your workflow, which should be more than
 enough for a simple testing suite, can be written as follows:
 
-{% raw %}
-
 ```yaml
 - name: Upload coverage report
   uses: codecov/codecov-action@v6
@@ -234,14 +220,12 @@ enough for a simple testing suite, can be written as follows:
     token: ${{ secrets.CODECOV_TOKEN }}
 ```
 
-{% endraw %}
-
 The lines above should be added after the step that runs your tests with the
 `--cov` option. See the [docs](https://github.com/codecov/codecov-action#usage)
 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
@@ -280,5 +264,3 @@ loss of coverage to fail. See the
 TODO -->
 
 [codecov/codecov-action]: https://github.com/codecov/codecov-action
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/guides/docs.md b/docs/pages/guides/docs.md
index bceb5281..99184e1a 100644
--- a/docs/pages/guides/docs.md
+++ b/docs/pages/guides/docs.md
@@ -1,61 +1,51 @@
 ---
-layout: page
 title: Writing documentation
-permalink: /guides/docs/
-nav_order: 4
-parent: Topical Guides
 ---
 
-{% include toc.html %}
-
-# 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,
 the same format used by GitHub, Wikipedia, and others. This guide covers Sphinx
 and Mkdocs, and uses the modern MyST plugin to get Markdown support.
 
-{: .note-title }
-
-> Popular frameworks
->
-> There are other frameworks as well; these often are simpler, but are not as
-> commonly used, and have somewhat fewer examples and plugins. They are:
->
-> - [Sphinx](https://www.sphinx-doc.org/en/master/): A popular documentation
->   framework for scientific libraries with a history of close usage with
->   scientific tools like LaTeX. Examples include
->   [astropy](https://docs.astropy.org/en/stable/index_user_docs.html) and
->   [corner](https://docs.astropy.org/en/stable/index_user_docs.html).
-> - [MkDocs](https://www.mkdocs.org): A from-scratch new documentation system
->   based on markdown and HTML. Less support for man pages & PDFs than Sphinx,
->   since it doesn't use docutils. Has over
->   [200 plugins](https://github.com/mkdocs/catalog) - they are much easier to
->   write than Sphinx. Example sites include [hatch](https://hatch.pypa.io),
->   [PDM](https://pdm.fming.dev),
->   [cibuildwheel](https://cibuildwheel.readthedocs.io),
->   [Textual](https://textual.textualize.io),
->   [pipx](https://pypa.github.io/pipx/),
->   [Pydantic](https://docs.pydantic.dev/latest/),
->   [Polars](https://docs.pola.rs/), and
->   [FastAPI](https://fastapi.tiangolo.com/)
-> - [JupyterBook](https://jupyterbook.org): A powerful system for rendering a
->   collection of notebooks using Sphinx internally. Can also be used for docs,
->   though, see [echopype](https://echopype.readthedocs.io).
-
-{: .warning-title }
-
-> The Future of MkDocs
->
-> The creators of `mkdocs-material` and `mkdocstrings` have come together to
-> create a new documentation package called
-> [Zensical](https://zensical.org/about/). The framework is still in alpha
-> development, but aims to simplify the documentation process, be blazing fast,
-> and move away from the limitations of MkDocs. This also means MkDocs's future
-> is uncertain, and mkdocs-material will be minimally maintained until
-> late 2026.
-
-## What to include
+:::{note} Popular frameworks
+There are other frameworks as well; these often are simpler, but are not as
+commonly used, and have somewhat fewer examples and plugins. They are:
+
+- [Sphinx](https://www.sphinx-doc.org/en/master/): A popular documentation
+  framework for scientific libraries with a history of close usage with
+  scientific tools like LaTeX. Examples include
+  [astropy](https://docs.astropy.org/en/stable/index_user_docs.html) and
+  [corner](https://docs.astropy.org/en/stable/index_user_docs.html).
+- [MkDocs](https://www.mkdocs.org): A from-scratch new documentation system
+  based on markdown and HTML. Less support for man pages & PDFs than Sphinx,
+  since it doesn't use docutils. Has over
+  [200 plugins](https://github.com/mkdocs/catalog) - they are much easier to
+  write than Sphinx. Example sites include [hatch](https://hatch.pypa.io),
+  [PDM](https://pdm.fming.dev),
+  [cibuildwheel](https://cibuildwheel.readthedocs.io),
+  [Textual](https://textual.textualize.io),
+  [pipx](https://pypa.github.io/pipx/),
+  [Pydantic](https://docs.pydantic.dev/latest/),
+  [Polars](https://docs.pola.rs/), and
+  [FastAPI](https://fastapi.tiangolo.com/)
+- [JupyterBook](https://jupyterbook.org): A powerful system for rendering a
+  collection of notebooks using Sphinx internally. Can also be used for docs,
+  though, see [echopype](https://echopype.readthedocs.io).
+:::
+
+:::{warning} The Future of MkDocs
+The creators of `mkdocs-material` and `mkdocstrings` have come together to
+create a new documentation package called
+[Zensical](https://zensical.org/about/). The framework is still in alpha
+development, but aims to simplify the documentation process, be blazing fast,
+and move away from the limitations of MkDocs. This also means MkDocs's future
+is uncertain, and mkdocs-material will be minimally maintained until
+late 2026.
+:::
+
+### What to include
 
 Ideally, software documentation should include:
 
@@ -67,12 +57,10 @@ Ideally, software documentation should include:
 - **Explanations** to convey deeper understanding of why and how the software
   operates the way it does.
 
-{: .note-title }
-
-> The Diátaxis framework
->
-> This overall framework has a name, [Diátaxis][], and you can read more about
-> it if you are interested.
+:::{note} The Diátaxis framework
+This overall framework has a name, [Diátaxis][], and you can read more about
+it if you are interested.
+:::
 
 <!-- [[[cog
 from cog_helpers import code_fence, render_cookie, PyMatcher
@@ -88,18 +76,20 @@ 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.
 
-{% tabs %}{% tab sphinx Sphinx %}
+::::{tab-set}
+:::{tab-item} Sphinx
+:sync: sphinx
 
-### pyproject.toml additions
+#### pyproject.toml additions
 
 Setting a `docs` dependency group looks like this:
 
-```toml
+```ini
 [dependency-groups]
 docs = [
   "furo",
@@ -117,13 +107,13 @@ 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"):
     print(docs_conf_py)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 from __future__ import annotations
 
@@ -190,7 +180,7 @@ nitpick_ignore = [
 
 always_document_param_types = True
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 We start by setting some configuration values, but most notably we are getting
@@ -237,7 +227,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:
 
@@ -245,7 +235,7 @@ Your `index.md` file can start out like this:
 with code_fence("md", width=4):
     print(docs_index_md)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ````md
 # package
 
@@ -265,7 +255,7 @@ with code_fence("md", width=4):
 - {ref}`modindex`
 - {ref}`search`
 ````
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 You can put your project name in as the title. The `toctree` directive houses
@@ -277,9 +267,9 @@ docs, so you can add a expression to your README (`<!-- SPHINX-START -->` above)
 to mark where you want the docs portion to start.
 
 You can add the standard indices and tables at the end.
-
-{% endtab %} {% tab mkdocs MkDocs %}
-
+:::
+:::{tab-item} MkDocs
+:sync: mkdocs
 While the cookie cutter creates a basic structure for your MkDocs (a top level
 `mkdocs.yml` file and the `docs` directory), you can also follow the official
 [Getting started](https://squidfunk.github.io/mkdocs-material/getting-started/)
@@ -289,7 +279,7 @@ If you selected the `mkdocs` option when using the template cookie-cutter
 repository, you will already have this group. Otherwise, add to your
 `pyproject.toml`:
 
-```toml
+```ini
 [dependency-groups]
 docs = [
     "markdown>=3.9",
@@ -321,7 +311,7 @@ Here's the whole file for completeness. We'll break it into sections underneath.
 with code_fence("yaml"):
     print(mkdocs_conf_yaml)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```yaml
 site_name: package
 site_url: https://package.readthedocs.io/
@@ -376,7 +366,7 @@ nav:
   - Home: index.md
   - Python API: api.md
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 First, the basic site metadata contains authors, repository details, URLs, etc:
@@ -478,21 +468,23 @@ nav:
   - Python API: api.md
 ```
 
-{% endtab %} {% endtabs %}
+:::
+::::
 
-### .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
+documentation, you must have a `.readthedocs.yaml` file {rr}`RTD100` like
 this:
 
-{% tabs %} {% tab sphinx Sphinx %}
-
+::::{tab-set}
+:::{tab-item} Sphinx
+:sync: sphinx
 <!-- [[[cog
 with code_fence("yaml"):
     print(readthedocs_yaml)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
@@ -514,16 +506,16 @@ python:
       groups:
         - docs
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
-
-{% endtab %} {% tab mkdocs MkDocs %}
-
+:::
+:::{tab-item} MkDocs
+:sync: mkdocs
 <!-- [[[cog
 with code_fence("yaml"):
     print(readthedocs_yaml_mkdocs)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
@@ -542,31 +534,32 @@ build:
     - uv sync --group docs
     - uv run mkdocs build --site-dir $READTHEDOCS_OUTPUT/html
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-This sets the Read the Docs config version (2 is required) {% rr RTD101 %}.
+This sets the Read the Docs config version (2 is required) {rr}`RTD101`.
 
 The `build` table is the modern way to specify a runner. You need an `os` (a
-modern Ubuntu should be fine) {% rr RTD102 %} and a `tools` table (we'll use
-Python {% rr RTD103 %}, several languages are supported here).
+modern Ubuntu should be fine) {rr}`RTD102` and a `tools` table (we'll use
+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:
 
-{% tabs %} {% tab sphinx Sphinx %}
-
+::::{tab-set}
+:::{tab-item} Sphinx
+:sync: sphinx
 <!-- [[[cog
 with code_fence("python"):
     print(noxfile.get_source("docs"))
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 @nox.session(reuse_venv=True, default=False)
 def docs(session: nox.Session) -> None:
@@ -599,7 +592,7 @@ def docs(session: nox.Session) -> None:
     else:
         session.run("sphinx-build", "--keep-going", *shared_args)
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 This is a more complex Nox job just because it's taking some options (the
@@ -614,14 +607,14 @@ links, and doesn't really produce output. Finally, we collect some useful args,
 and run either the autobuild (for `--serve`) or regular build. We could have
 just added `python -m http.server` pointing at the built documentation, but
 autobuild will rebuild if you change a file while serving.
-
-{% endtab %} {% tab mkdocs MkDocs %}
-
+:::
+:::{tab-item} MkDocs
+:sync: mkdocs
 <!-- [[[cog
 with code_fence("python"):
     print(noxfile_mkdocs.get_source("docs"))
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 @nox.session(reuse_venv=True, default=False)
 def docs(session: nox.Session) -> None:
@@ -637,7 +630,7 @@ def docs(session: nox.Session) -> None:
     else:
         session.run("mkdocs", "build", "--clean", *session.posargs)
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 This Nox job will invoke MkDocs to serve a live copy of your documentation under
@@ -646,25 +639,26 @@ output). By requesting a `serve` instead of a `build`, any time documentation or
 the source code is changed, the documentation will automatically update. For
 documentation on how to configure what directories are watched for changes,
 [consult the MkDocs configuration page](https://www.mkdocs.org/user-guide/configuration/#live-reloading).
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-## API docs
-
-{% tabs %} {% tab sphinx Sphinx %}
+### API docs
 
+::::{tab-set}
+:::{tab-item} Sphinx
+:sync: sphinx
 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"):
     txt = noxfile.get_source("build_api_docs")
     print(txt.replace("package", "<package-name-here>"))
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 @nox.session(default=False)
 def build_api_docs(session: nox.Session) -> None:
@@ -683,13 +677,13 @@ def build_api_docs(session: nox.Session) -> None:
         "src/<package-name-here>",
     )
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 And you'll need this added to your `docs/index.md`:
 
 ````md
-```{toctree}
+```text {toctree}
 :maxdepth: 2
 :hidden:
 :caption: API
@@ -699,9 +693,9 @@ api/<package-name-here>
 ````
 
 Note that your docstrings are still parsed as reStructuredText.
-
-{% endtab %} {% tab mkdocs MkDocs %}
-
+:::
+:::{tab-item} MkDocs
+:sync: mkdocs
 API documentation can be built from your docstring using the `mkdocstrings`
 plugin, as referenced previously. Unlike with Sphinx, which requires a direct
 invocation of `sphinx-apidoc`, MkDocs plugins are integrated into the MkDocs
@@ -724,13 +718,14 @@ like built. In this case, we are asking to document the entire module
 `my_module` (and all classes and functions within it) which is located in
 `my_package`. You could instead ask for only a single component inside your
 module by being more specific, like `::: my_package.my_module.MyClass`.
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-## Notebooks in docs
-
-{% tabs %} {% tab sphinx Sphinx %}
+### Notebooks in docs
 
+::::{tab-set}
+:::{tab-item} Sphinx
+:sync: sphinx
 You can combine notebooks into your docs. The tool for this is `nbsphinx`. If
 you want to use it, add `nbsphinx` and `ipykernel` to your documentation
 requirements, add `"nbsphinx"` to your `conf.py`'s `extensions =` list, and add
@@ -757,9 +752,9 @@ for this to work. CI services like readthedocs usually have it installed.
 
 If you want to use Markdown instead of notebooks, you can use jupytext (see
 [here](https://nbsphinx.readthedocs.io/en/0.9.2/a-markdown-file.html)).
-
-{% endtab %} {% tab mkdocs MkDocs %}
-
+:::
+:::{tab-item} MkDocs
+:sync: mkdocs
 You can combine notebooks into your docs. The plugin for this is
 `mkdocs-jupyter`, and configuration is detailed
 [here](https://github.com/danielfrg/mkdocs-jupyter) and you can find examples
@@ -784,16 +779,11 @@ and notebooks. If you have a directory of example python files to run, consider
 For an external example, the
 [ChainConsumer docs](https://samreay.github.io/ChainConsumer/generated/gallery/)
 show `mkdocs-gallery` in action.
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-<!-- prettier-ignore-start -->
 [diátaxis]: https://diataxis.fr/
 [sphinx]: https://www.sphinx-doc.org/
 [myst]: https://myst-parser.readthedocs.io/
-[organizing content]: https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html
 [sphinx-autodoc2]: https://sphinx-autodoc2.readthedocs.io/
 [`sphinx.ext.napoleon`]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
-<!-- prettier-ignore-end -->
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/guides/gha_basic.md b/docs/pages/guides/gha_basic.md
index a161cd96..31524989 100644
--- a/docs/pages/guides/gha_basic.md
+++ b/docs/pages/guides/gha_basic.md
@@ -1,17 +1,11 @@
 ---
-layout: page
 title: "GHA: GitHub Actions intro"
-permalink: /guides/gha-basic/
-nav_order: 10
-parent: Topical Guides
-custom_title: GitHub Actions introduction
+short_title: GitHub Actions introduction
 ---
 
-{% include toc.html %}
+## GitHub Actions: Intro
 
-# GitHub Actions: Intro
-
-{% rr GH100 %} The recommended CI for scientific Python projects is GitHub
+{rr}`GH100` The recommended CI for scientific Python projects is GitHub
 Actions (GHA), although its predecessor Azure is also in heavy usage, and other
 popular services (Travis, Appveyor, and Circle CI) may be found in a few
 packages. GHA is preferred due to the flexible, extensible design and the tight
@@ -31,7 +25,7 @@ with render_cookie() as package:
 ]]] -->
 <!-- [[[end]]] -->
 
-## Header
+### Header
 
 Your main CI workflow file should begin something like this:
 
@@ -47,20 +41,20 @@ on:
 jobs:
 ```
 
-This gives the workflow a nice name {% rr GH101 %}, and defines the conditions
+This gives the workflow a nice name {rr}`GH101`, and defines the conditions
 under which it runs. This will run on all pull requests, or pushes to main. If
 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
 world usage and supports the same configuration and hooks.
 
-{% tabs runner %} {% tab prek Prek %}
-
+::::{tab-set}
+:::{tab-item} Prek
 Prek can run using the official action:
 
 ```yaml
@@ -72,8 +66,8 @@ lint:
     - uses: j178/prek-action@v2
 ```
 
-{% endtab %} {% tab pre-commit Pre-commit %}
-
+:::
+:::{tab-item} Pre-commit
 Pre-commit can run using the official action:
 
 ```yaml
@@ -88,7 +82,8 @@ lint:
     - uses: pre-commit/action@v3.0.1
 ```
 
-{% endtab %} {% endtabs %}
+:::
+::::
 
 If you do use [pre-commit.ci](https://pre-commit.ci), but you need this job to
 run a manual check, like check-manifest, then you can keep it but just use
@@ -96,7 +91,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
@@ -105,8 +100,6 @@ adjust the Python versions to suit your taste; you can also test on different
 OS's if you'd like by adding them to the matrix and inputting them into
 `runs-on`.
 
-{% raw %}
-
 ```yaml
 tests:
   runs-on: ubuntu-latest
@@ -136,8 +129,6 @@ tests:
       run: uv run pytest
 ```
 
-{% endraw %}
-
 A few things to note from above:
 
 The matrix should contain the versions you are interested in. You can also test
@@ -167,9 +158,9 @@ 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
+{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
 up to date. GitHub provided a way to do this with dependabot. Just add the
 following file as `.github/dependabot.yml`:
@@ -192,16 +183,16 @@ This will check to see if there are updates to the action weekly, and will make
 a PR if there are updates, including the changelog and commit summary in the PR.
 If you select a name like `v1`, this should only look for updates of the same
 form (since April 2022) - there is no need to restrict updates for "moving tag"
-updates anymore {% rr GH211 %}. You can also use SHA's and dependabot will
-respect that too. And `groups` will combine actions updates {% rr GH212 %},
+updates anymore {rr}`GH211`. You can also use SHA's and dependabot will
+respect that too. And `groups` will combine actions updates {rr}`GH212`,
 which is both cleaner and sometimes required for dependent actions, like
 `upload-artifact`/`download-artifact`.
 
 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`:
@@ -213,7 +204,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:
@@ -224,7 +215,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:
@@ -234,16 +225,12 @@ actions have outputs, and bash actions can manually write to output:
   run: echo "something=true" >> $GITHUB_OUTPUT
 ```
 
-{% raw %}
-
 You can now refer to this step in a later step with
 `${{ steps.someid.something }}`. You also can get it from another job by using
 `${{ needs.<jobname>.outputs.something }}`. The `toJson()` function is useful
 for inputting JSON - you can even generate matrices dynamically this way!
 
-{% endraw %}
-
-### Pretty output
+#### Pretty output
 
 You can write GitHub flavored markdown to `$GITHUB_STEP_SUMMARY`, and it will be
 shown on the summary page.
@@ -260,7 +247,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:
 
@@ -338,31 +325,27 @@ 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
+{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:
 
-{% raw %}
-
 ```yaml
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 ```
 
-{% endraw %}
-
 Anything with a matching group name will count in the same group - the ref is
 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
@@ -373,8 +356,6 @@ pass).
 
 As an example, if you had `lint` and `checks` jobs, use this:
 
-{% raw %}
-
 ```yaml
 pass:
   if: always()
@@ -386,8 +367,6 @@ pass:
         jobs: ${{ toJSON(needs) }}
 ```
 
-{% endraw %}
-
 We want the job to always run, so we set `if: always()`. Otherwise, it might be
 skipped if any job it depends on is skipped, and skipped jobs count as "passing"
 to GitHub's automerge (yikes!). The important part of the job is the `needs:`
@@ -403,7 +382,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)
@@ -446,8 +425,6 @@ ideally shouldn't change the user's environment; suddenly changing the active
 Python version might come as a surprise. You can do that, though, using
 `update-environment: false` with `setup-python` and `pipx`:
 
-{% raw %}
-
 ```yaml
 - uses: actions/setup-python@v6
   id: python
@@ -462,23 +439,21 @@ Python version might come as a surprise. You can do that, though, using
     github.action_path }}' ${{ inputs.some-input }}
 ```
 
-{% endraw %}
-
 You use the `python-path` output from `setup-python` to get the Python you
 activated. You use `github.action_path` to get the path to the checked-out
 action.
 
-{: .highlight }
+:::{tip}
+Examples of custom composite actions include:
 
-> Examples of custom composite actions include:
->
-> - [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel/blob/main/action.yml)
-> - [wntrblm/nox](https://github.com/wntrblm/nox/blob/main/action.yml)
-> - [scientific-python/repo-review](https://github.com/scientific-python/repo-review/blob/main/action.yml)
-> - [scientific-python/cookie](https://github.com/scientific-python/cookie/blob/main/action.yml)
->   (This repo)
+- [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel/blob/main/action.yml)
+- [wntrblm/nox](https://github.com/wntrblm/nox/blob/main/action.yml)
+- [scientific-python/repo-review](https://github.com/scientific-python/repo-review/blob/main/action.yml)
+- [scientific-python/cookie](https://github.com/scientific-python/cookie/blob/main/action.yml)
+  (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
@@ -495,7 +470,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
@@ -515,8 +490,6 @@ on:
 Otherwise, they look like normal workflows. Then you need another reusable
 workflow file to decide when to run a specific situation.
 
-{% raw %}
-
 ```yaml
 # reusable-change-detection.yml
 on:
@@ -527,8 +500,6 @@ on:
       # More here if you have more situations to detect
 ```
 
-{% endraw %}
-
 You start by specifying outputs when running this. You'll want one output per
 situation you want to detect. The value will be output from our
 `change-detection` job below, and defaults to "false" if we don't output
@@ -536,8 +507,6 @@ anything.
 
 Now, we need our job:
 
-{% raw %}
-
 ```yaml
 jobs:
   change-detection:
@@ -571,8 +540,6 @@ jobs:
       # Add 2 more steps per situation you have to detect
 ```
 
-{% endraw %}
-
 This has a bit of boilerplate (mostly around passing variables around), but what
 it's doing is fairly simple. Instead of stepping through it, let's look at what
 it's trying to do. First, you need to find a list of all changed files in the
@@ -588,21 +555,18 @@ Everything else in the job is about getting the output from the step
 `changed-tests-files` to `tests-changes`, then from there into the reusable
 workflow output as `run-tests`.
 
-{: .note }
-
+:::{note}
 Someone probably could write an action (maybe even an composite action using
 either `gh` or `shell: python`) that could directly report changes true/false
 instead of a file list, saving the two step process and greatly simplifying
 this.
-
+:::
 If you have more situations, you just repeat these two steps with different
 `id`s and inputs.
 
 Finally, you write the overarching CI workflow that combines the reusable
 workflows, something like `ci.yml`:
 
-{% raw %}
-
 ```yaml
 on:
   workflow_dispatch:
@@ -648,17 +612,15 @@ If you have more situations, add another `${{ ... }}` above, after the first
 one, and add them to the needs list. This is really just injecting "tests" only
 if the "tests" job is being skipped into `allowed-skips`.
 
-{% endraw %}
-
-{: .highlight }
+:::{tip}
+Some examples of repos using this method are:
 
-> Some examples of repos using this method are:
->
-> - [pypa/build](https://github.com/pypa/build/tree/main/.github/workflows)
-> - [scientific-python/cookie](https://github.com/scientific-python/cookie/tree/main/.github/workflows)
->   (this repo)
+- [pypa/build](https://github.com/pypa/build/tree/main/.github/workflows)
+- [scientific-python/cookie](https://github.com/scientific-python/cookie/tree/main/.github/workflows)
+  (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/)
@@ -679,7 +641,7 @@ permissions:
   id-token: write
 ```
 
-{% rr GH103 %} You probably only want one deployment at a time, so you can use:
+{rr}`GH103` You probably only want one deployment at a time, so you can use:
 
 ```yaml
 concurrency:
@@ -696,16 +658,12 @@ configure Pages.
   uses: actions/configure-pages@v6
 ```
 
-{% raw %}
-
 Notice this action sets an `id:`; this will allow you to use the outputs from
 this action later; specifically, may want to use
 `${{ steps.pages.outputs.base_path }}` when building (you can also get `origin`,
 `base_url`, or `host` - see the action
 [config](https://github.com/actions/configure-pages/blob/main/action.yml)).
 
-{% endraw %}
-
 ```yaml
 - name: Upload artifact
   uses: actions/upload-pages-artifact@v5
@@ -718,8 +676,6 @@ Finally, you'll need to deploy the artifact (named `github-pages`) to Pages. You
 can make this a custom job with `needs:` pointing at your previous job (in this
 example, the previous job is called `build`):
 
-{% raw %}
-
 ```yaml
 deploy:
   environment:
@@ -733,22 +689,20 @@ deploy:
       uses: actions/deploy-pages@v5
 ```
 
-{% endraw %}
-
 The deploy-pages job gives a `page_url`, which is the same as `base_url` on the
 configure step, and can be set in the `environment`. If you want to do
 everything in one job, you only need one of these.
 
-{: .highlight }
+:::{tip}
+See the
+[official starter workflows](https://github.com/actions/starter-workflows/tree/main/pages)
+for examples. Some other examples include:
 
-> See the
-> [official starter workflows](https://github.com/actions/starter-workflows/tree/main/pages)
-> for examples. Some other examples include:
->
-> - [CLIUtils.github.io/CLI11](https://github.com/CLIUtils/CLI11/blob/main/.github/workflows/docs.yml)
-> - [iris-hep.org](https://github.com/iris-hep/iris-hep.github.io/blob/master/.github/workflows/deploy.yml)
+- [CLIUtils.github.io/CLI11](https://github.com/CLIUtils/CLI11/blob/main/.github/workflows/docs.yml)
+- [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
@@ -759,7 +713,7 @@ pre-commit-ci PRs for you:
 with code_fence("yaml"):
     print(github_release_yaml)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```yaml
 changelog:
   exclude:
@@ -767,15 +721,9 @@ changelog:
       - dependabot[bot]
       - pre-commit-ci[bot]
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
-<!-- prettier-ignore-start -->
-
 [pre-commit]: https://pre-commit.com
 [prek]: https://github.com/j178/prek
 [gh-changelog]: https://docs.github.com/en/repositories/releasing-projects
-
-<!-- prettier-ignore-end -->
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/guides/gha_pure.md b/docs/pages/guides/gha_pure.md
index 37d72572..d80a857d 100644
--- a/docs/pages/guides/gha_pure.md
+++ b/docs/pages/guides/gha_pure.md
@@ -1,15 +1,9 @@
 ---
-layout: page
 title: "GHA: Pure Python wheels"
-permalink: /guides/gha-pure/
-nav_order: 11
-parent: Topical Guides
-custom_title: GitHub Actions for pure Python wheels
+short_title: GitHub Actions for pure Python wheels
 ---
 
-{% include toc.html %}
-
-# GitHub Actions: Pure Python wheels
+## GitHub Actions: Pure Python wheels
 
 We will cover binary wheels [on the next page][], but if you do not have a
 compiled extension, this is called a universal (pure Python) package, and the
@@ -17,25 +11,25 @@ procedure to make a "built" wheel is simple. At the end of this page, there is a
 recipe that can often be used exactly for pure Python wheels (if the previous
 recommendations were followed).
 
-{: .note }
+:::{note}
+Why make a wheel when there is nothing to compile? There are a multitude of
+reasons that a wheel is better than only providing an sdist:
 
-> Why make a wheel when there is nothing to compile? There are a multitude of
-> reasons that a wheel is better than only providing an sdist:
->
-> - Wheels do not run `setup.py`, but simply install files into locations
->   - Lower install requirements - users don't need your setup tools
->   - Faster installs
->   - Safer installs - no arbitrary code execution
->   - Highly consistent installs
-> - Wheels pre-compile bytecode when they install
->   - Initial import is not slower than subsequent import
->   - Less chance of a permission issue
-> - You can look in the `.whl` (it's a `.zip`, really) and see where everything
->   is going to go
+- Wheels do not run `setup.py`, but simply install files into locations
+  - Lower install requirements - users don't need your setup tools
+  - Faster installs
+  - Safer installs - no arbitrary code execution
+  - Highly consistent installs
+- Wheels pre-compile bytecode when they install
+  - Initial import is not slower than subsequent import
+  - Less chance of a permission issue
+- You can look in the `.whl` (it's a `.zip`, really) and see where everything
+  is going to go
+:::
 
-[on the next page]: {% link pages/guides/gha_wheels.md %}
+[on the next page]: pages/guides/gha_wheels
 
-## Job setup
+### Job setup
 
 ```yaml
 name: CD
@@ -62,9 +56,7 @@ releases(-only). You will also need to change the event filter below.
 You can merge the CI job and the CD job if you want. To do that, preferably with
 the name "CI/CD", you can just combine the two `on` dicts.
 
-## Distribution: Pure Python wheels
-
-{% raw %}
+### Distribution: Pure Python wheels
 
 ```yaml
 dist:
@@ -86,8 +78,6 @@ dist:
       run: pipx run twine check dist/*
 ```
 
-{% endraw %}
-
 We use [PyPA-Build](https://pypa-build.readthedocs.io/en/latest/), a new build
 tool designed to make building wheels and SDists easy. It run a [PEP 517][]
 backend and can get [PEP 518][] requirements even for making SDists.
@@ -105,38 +95,36 @@ GitHub Actions (in fact, they use it to setup other applications).
 We upload the artifact just to make it available via the GitHub PR/Checks API.
 You can download a file to test locally if you want without making a release.
 
-{: .warning }
-
-> As of `upload-artifact@v4`, the artifact name must be unique. Extending an
-> existing artifact is no longer supported.
+:::{warning}
+As of `upload-artifact@v4`, the artifact name must be unique. Extending an
+existing artifact is no longer supported.
+:::
 
 We also add an optional check using twine for the metadata (it will be tested
 later in the upload action for the release job, as well).
 
-{: .highlight-title }
-
-> All-in-one action
->
-> There is an
-> [all-in-one action](https://github.com/hynek/build-and-inspect-python-package)
-> that does all the work for you for a pure Python package, including extra
-> pre-upload checks & nice GitHub summaries.
->
-> ```yaml
-> steps:
->   - uses: actions/checkout@v6
->   - uses: hynek/build-and-inspect-python-package@v2
-> ```
->
-> The artifact it produces is named `Packages`, so that's what you need to use
-> later to publish. This will be used instead of the manual steps below.
+:::{tip} All-in-one action
+There is an
+[all-in-one action](https://github.com/hynek/build-and-inspect-python-package)
+that does all the work for you for a pure Python package, including extra
+pre-upload checks & nice GitHub summaries.
 
-And then, you need a release job. Trusted Publishing is more secure and
-recommended {% rr GH105 %}:
+```yaml
+steps:
+  - uses: actions/checkout@v6
+  - uses: hynek/build-and-inspect-python-package@v2
+```
 
-{% tabs %} {% tab oidc Trusted Publishing (recommended) %}
+The artifact it produces is named `Packages`, so that's what you need to use
+later to publish. This will be used instead of the manual steps below.
+:::
 
-{% raw %}
+And then, you need a release job. Trusted Publishing is more secure and
+recommended {rr}`GH105`:
+
+::::{tab-set}
+:::{tab-item} Trusted Publishing (recommended)
+:sync: trusted-publishing
 
 ```yaml
 publish:
@@ -162,8 +150,6 @@ publish:
     - uses: pypa/gh-action-pypi-publish@release/v1
 ```
 
-{% endraw %}
-
 When you make a GitHub release in the web UI, we publish to PyPI. You'll just
 need to tell PyPI which org, repo, workflow, and set the `pypi` environment to
 allow pushes from GitHub. If it's the first time you've published a package, go
@@ -172,10 +158,9 @@ accept your initial package publish.
 
 We are also generating artifact attestations, which can allow users to verify
 that the artifacts were built on your actions.
-
-{% endtab %} {% tab token Token %}
-
-{% raw %}
+:::
+:::{tab-item} Token
+:sync: token
 
 ```yaml
 publish:
@@ -193,25 +178,22 @@ publish:
         password: ${{ secrets.pypi_password }}
 ```
 
-{% endraw %}
-
 If you cannot use Trusted Publishing, this publishes to PyPI with a token.
 You'll need to go to PyPI, generate a token for your user, and put it into
 `pypi_password` on your repo's secrets page. Once you have a project, you should
 delete your user-scoped token and generate a new project-scoped token.
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-{% details Complete recipe %}
-
+:::::{dropdown} Complete recipe
 This can be used on almost any package with a standard
 `.github/workflows/cd.yml` recipe. This works because `pyproject.toml` describes
 exactly how to build your package, hence all packages build exactly via the same
 interface:
 
-{% tabbodies %} {% tab oidc Trusted Publishing (recommended) %}
-
-{% raw %}
+::::{tab-set}
+:::{tab-item} Trusted Publishing (recommended)
+:sync: trusted-publishing
 
 ```yaml
 name: CD
@@ -260,11 +242,9 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@release/v1
 ```
 
-{% endraw %}
-
-{% endtab %} {% tab token Token %}
-
-{% raw %}
+:::
+:::{tab-item} Token
+:sync: token
 
 ```yaml
 name: CD
@@ -305,25 +285,15 @@ jobs:
           password: ${{ secrets.pypi_password }}
 ```
 
-{% endraw %}
-
 If you cannot use Trusted Publishing, this publishes to PyPI with a token.
 You'll need to go to PyPI, generate a token for your user, and put it into
 `pypi_password` on your repo's secrets page. Once you have a project, you should
 delete your user-scoped token and generate a new project-scoped token.
-
-{% endtab %} {% endtabbodies %}
-
-{% enddetails %}
-
-<!-- prettier-ignore-start -->
+:::
+::::
+:::::
 
 [pep 517]: https://www.python.org/dev/peps/pep-0517/
 [pep 518]: https://www.python.org/dev/peps/pep-0518/
 [pypi trusted publisher docs]: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
 [`workflow_dispatch`]: https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/
-
-
-<!-- prettier-ignore-end -->
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/guides/gha_wheels.md b/docs/pages/guides/gha_wheels.md
index 6d4e6582..e3492cd7 100644
--- a/docs/pages/guides/gha_wheels.md
+++ b/docs/pages/guides/gha_wheels.md
@@ -1,21 +1,15 @@
 ---
-layout: page
 title: "GHA: Binary wheels"
-permalink: /guides/gha-wheels/
-nav_order: 12
-parent: Topical Guides
-custom_title: GitHub Actions for Binary Wheels
+short_title: GitHub Actions for Binary Wheels
 ---
 
-{% include toc.html %}
-
-# GitHub Actions: Binary wheels
+## GitHub Actions: Binary wheels
 
 Building binary wheels is a bit more involved, but can still be done effectively
 with GHA. This document will introduce [cibuildwheel][] for use in your project.
 We will focus on GHA below.
 
-## Header
+### Header
 
 Wheel building should only happen rarely, so you will want to limit it to
 releases, and maybe a rarely moving branch or other special tag (such as
@@ -43,18 +37,15 @@ wheels before making a release; you can download them from the "artifacts". You
 can even define variables that you can set in the GUI and access in the CI!
 Finally, if you change the workflow itself in a PR, then rebuild the wheels too.
 
-<!-- prettier-ignore-start -->
 [workflow_dispatch]: https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/
 
-### Useful suggestion:
-{: .no_toc }
-<!-- prettier-ignore-end -->
+#### Useful suggestion
 
 Since these variables will be used by all jobs, you could make them available in
 your `pyproject.toml` file, so they can be used everywhere (even locally for
 Linux and Windows):
 
-```toml
+```ini
 [tool.cibuildwheel]
 test-groups = ["test"]
 test-command = "pytest {project}/tests"
@@ -69,7 +60,7 @@ will cause the pip install to use the dependency-group(s) specified. The
 `test-command` will use pytest to run your tests. You can also set the build
 verbosity (`-v` in pip) if you want to.
 
-## Making an SDist
+### Making an SDist
 
 You probably should not forget about making an SDist! A simple job, like before,
 will work:
@@ -98,12 +89,10 @@ Instead of using `uv`, you can also run `pipx run build --sdist`, or install
 build via pip and use `python -m build --sdist`. You can also pin the version
 with `pipx run build==<version>`.
 
-## The core job (3 main OS's)
+### The core job (3 main OS's)
 
 The core of the work is down here:
 
-{% raw %}
-
 ```yaml
 build_wheels:
   name: Wheel on ${{ matrix.os }}
@@ -136,8 +125,6 @@ build_wheels:
         path: wheelhouse/*.whl
 ```
 
-{% endraw %}
-
 There are several things to note here. First, one of the reasons this works is
 because you followed the suggestions in the previous sections, and your package
 builds nicely into a wheel without strange customizations (if you _really_ need
@@ -166,13 +153,13 @@ set that in the `pyproject.toml` file instead.
 You can skip specifying the `build[uv]` build-frontend option and pre-installing
 `uv` on the runners, but it will be a slower.
 
-## Publishing
-
-Trusted Publishing is more secure and recommended {% rr GH105 %}:
+### Publishing
 
-{% tabs %} {% tab oidc Trusted Publishing (recommended) %}
+Trusted Publishing is more secure and recommended {rr}`GH105`:
 
-{% raw %}
+::::{tab-set}
+:::{tab-item} Trusted Publishing (recommended)
+:sync: trusted-publishing
 
 ```yaml
 upload_all:
@@ -200,8 +187,6 @@ upload_all:
     - uses: pypa/gh-action-pypi-publish@release/v1
 ```
 
-{% endraw %}
-
 When you make a GitHub release in the web UI, we publish to PyPI. You'll just
 need to tell PyPI which org, repo, workflow, and set the `pypi` environment to
 allow pushes from GitHub. If it's the first time you've published a package, go
@@ -210,10 +195,9 @@ accept your initial package publish.
 
 We are also generating artifact attestations, which can allow users to verify
 that the artifacts were built on your actions.
-
-{% endtab %} {% tab token Token %}
-
-{% raw %}
+:::
+:::{tab-item} Token
+:sync: token
 
 ```yaml
 upload_all:
@@ -232,14 +216,12 @@ upload_all:
         password: ${{ secrets.pypi_password }}
 ```
 
-{% endraw %}
-
 If you cannot use Trusted Publishing, this publishes to PyPI with a token.
 You'll need to go to PyPI, generate a token for your user, and put it into
 `pypi_password` on your repo's secrets page. Once you have a project, you should
 delete your user-scoped token and generate a new project-scoped token.
-
-{% endtab %} {% endtabs %}
+:::
+::::
 
 If you have multiple jobs, you will want to collect your artifacts from above.
 If you only have one job, you can combine this into a single job like we did for
@@ -248,25 +230,17 @@ multiple places, you can set `skip_existing` (but generally it's better to not
 try to upload the same file from two places - you can trick Travis into avoiding
 the sdist, for example).
 
-{: .note-title }
-
-> Other architectures
->
-> GitHub Actions supports ARM on Linux and Windows as well. On Travis,
-> `cibuildwheel` even has the ability to create rarer architectures like PowerPC
-> builds natively. IBM Z builds are also available but in beta. However, due to
-> Travis CI's recent dramatic reduction on open source support, emulating these
-> architectures on GHA or Azure is probably better. Maybe look into Cirrus CI,
-> which has some harder-to-find architectures.
-
-<!-- prettier-ignore-start -->
+:::{note} Other architectures
+GitHub Actions supports ARM on Linux and Windows as well. On Travis,
+`cibuildwheel` even has the ability to create rarer architectures like PowerPC
+builds natively. IBM Z builds are also available but in beta. However, due to
+Travis CI's recent dramatic reduction on open source support, emulating these
+architectures on GHA or Azure is probably better. Maybe look into Cirrus CI,
+which has some harder-to-find architectures.
+:::
 
 [`cibw_before_build`]: https://cibuildwheel.readthedocs.io/en/stable/options/#before-build
 [`cibw_environment`]: https://cibuildwheel.readthedocs.io/en/stable/options/#environment
 [cibw custom]: https://cibuildwheel.readthedocs.io/en/stable/options/#build-skip
 [cibuildwheel]: https://cibuildwheel.readthedocs.io/en/stable/
 [pypi trusted publisher docs]: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
-
-<!-- prettier-ignore-end -->
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/guides/index.md b/docs/pages/guides/index.md
index 33e935ff..c79bc775 100644
--- a/docs/pages/guides/index.md
+++ b/docs/pages/guides/index.md
@@ -1,12 +1,8 @@
 ---
-layout: page
 title: Topical Guides
-permalink: /guides/
-nav_order: 2
-has_children: true
 ---
 
-# Topical Guides
+## Topical Guides
 
 The pages here are intended for developers who are making or maintaining a
 package and want to follow modern best practices in Python.
@@ -28,40 +24,33 @@ and one for [compiled extensions][gha_wheels]. You can read about setting up
 good tests on the [pytest page][pytest], with [coverage][]. There's also a page
 on setting up [docs][], as well.
 
-{: .highlight-title }
+:::{tip} New project template
+Once you have completed the guidelines, there is a
+[copier][]/[cookiecutter][]/[cruft][] project, [scientific-python/cookie][],
+that implements these guidelines and lets you setup a new package from a
+template in less than 60 seconds! Nine build backends including compiled
+backends, generation tested in Nox, and kept in-sync with the guide.
+:::
 
-> New project template
->
-> Once you have completed the guidelines, there is a
-> [copier][]/[cookiecutter][]/[cruft][] project, [scientific-python/cookie][],
-> that implements these guidelines and lets you setup a new package from a
-> template in less than 60 seconds! Nine build backends including compiled
-> backends, generation tested in Nox, and kept in-sync with the guide.
+:::{important} Checking an existing project
+We provide [sp-repo-review][], a set of [repo-review][] checks for comparing
+your repository with the guidelines, runnable [right in the guide][] via
+WebAssembly! All checks point to a linked badge in the guide.
+:::
 
-{: .important-title }
-
-> Checking an existing project
->
-> We provide [sp-repo-review][], a set of [repo-review][] checks for comparing
-> your repository with the guidelines, runnable [right in the guide][] via
-> WebAssembly! All checks point to a linked badge in the guide.
-
-<!-- prettier-ignore-start -->
-
-[tutorials]:          {% link pages/tutorials/index.md %}
-[style]:              {% link pages/guides/style.md %}
-[mypy]:               {% link pages/guides/mypy.md %}
-[docs]:               {% link pages/guides/docs.md %}
-[simple packaging]:   {% link pages/guides/packaging_simple.md %}
-[compiled packaging]: {% link pages/guides/packaging_compiled.md %}
-[classic packaging]:  {% link pages/guides/packaging_classic.md %}
-[coverage]:           {% link pages/guides/coverage.md %}
-[gha_basic]:          {% link pages/guides/gha_basic.md %}
-[gha_pure]:           {% link pages/guides/gha_pure.md %}
-[gha_wheels]:         {% link pages/guides/gha_wheels.md %}
-[pytest]:             {% link pages/guides/pytest.md %}
-[task runners]:       {% link pages/guides/tasks.md  %}
-[right in the guide]: {% link pages/guides/repo_review.md %}
+[tutorials]:          pages/tutorials/index
+[style]:              pages/guides/style
+[mypy]:               pages/guides/mypy
+[docs]:               pages/guides/docs
+[simple packaging]:   pages/guides/packaging_simple
+[compiled packaging]: pages/guides/packaging_compiled
+[classic packaging]:  pages/guides/packaging_classic
+[coverage]:           pages/guides/coverage
+[gha_basic]:          pages/guides/gha_basic
+[gha_pure]:           pages/guides/gha_pure
+[gha_wheels]:         pages/guides/gha_wheels
+[pytest]:             pages/guides/pytest
+[right in the guide]: pages/guides/repo_review
 
 [cookiecutter]:             https://cookiecutter.readthedocs.io
 [copier]:                   https://copier.readthedocs.io
@@ -70,4 +59,6 @@ on setting up [docs][], as well.
 [sp-repo-review]:           https://pypi.org/project/sp-repo-review
 [scientific-python/cookie]: https://github.com/scientific-python/cookie
 
-<!-- prettier-ignore-end -->
+
+```text {tableofcontents}
+```
diff --git a/docs/pages/guides/mypy.md b/docs/pages/guides/mypy.md
index 7adb3543..494699b6 100644
--- a/docs/pages/guides/mypy.md
+++ b/docs/pages/guides/mypy.md
@@ -1,16 +1,10 @@
 ---
-layout: page
 title: "Static type checking"
-permalink: /guides/mypy/
-nav_order: 9
-parent: Topical Guides
 ---
 
-{% include toc.html %}
+## Static type checking
 
-# Static type checking
-
-## Basics
+### Basics
 
 The most exciting thing happening right now in Python development is static
 typing. Since Python 3.0, we've had function annotations, and since 3.6,
@@ -42,7 +36,7 @@ Your tests cannot test every possible branch, every line of code. MyPy can
 runs rarely, that requires remote resources, that is slow, etc. All those can be
 checked by MyPy. It also keeps you (too?) truthful in your types.
 
-### Adding types
+#### Adding types
 
 There are three ways to add types.
 
@@ -66,7 +60,7 @@ it for parameters and returns from functions. When running MyPy, you can use
 print statement but at type-checking time, or `reveal_locals()` to see all local
 types.
 
-### Configuration
+#### Configuration
 
 By default, MyPy does as little as possible, so that you can add it iteratively
 to a code base. By default:
@@ -80,7 +74,7 @@ everything. Try to turn on as much as possible, and increase it until you can
 run with full `strict` checking. See the [style page][] for configuration
 suggestions.
 
-[style page]: {% link pages/guides/style.md %}
+[style page]: pages/guides/style
 
 For a library to support typing, it has to a) add types using any of the three
 methods, and b) add a `py.typed` empty file to indicate that it's okay to look
@@ -90,9 +84,9 @@ type hints for (mostly) the standard library.
 Third party libraries that are typed sometimes forget this last step, by the
 way!
 
-## Features
+### Features
 
-### Type narrowing
+#### Type narrowing
 
 One of the key features of type checking is type narrowing. The type checker
 monitors the types of a variable, and "narrows" it when something restricts it.
@@ -122,7 +116,7 @@ reveal_type(x)
 This will print `A` because you removed B via the type narrowing using the
 `assert`.
 
-### Protocols
+#### Protocols
 
 One of the best features of MyPy is support for structural subtyping via
 Protocols - formalized duck-typing, basically. This allows cross library
@@ -174,7 +168,7 @@ There are lots of built-in Protocols, most of which pre-date typing and are
 available in an Abstract Base Class form. Most of them check for one or more
 special methods, like `Iterable`, `Iterator`, etc.
 
-### Other features
+#### Other features
 
 Static typing has some great features worth checking out:
 
@@ -186,9 +180,9 @@ Static typing has some great features worth checking out:
 - MyPy validates with the Python version you ask for, regardless of what version
   you are actually running.
 
-## Complete example
+### Complete example
 
-### Runtime compatible types
+#### Runtime compatible types
 
 Here's the classic syntax, which you need to use if you want to access the type
 annotations at runtime and you need to support Python < 3.10:
@@ -213,7 +207,7 @@ def g(x: Union[str, int]) -> None:
     # Calling x.lower() is invalid here!
 ```
 
-### Types as strings
+#### Types as strings
 
 If you don't access the types at runtime, or if you use Python 3.10+ only, then
 you can use a much nicer syntax. The `annotations` future feature causes the
@@ -243,11 +237,11 @@ annotations at runtime.
 You can use the above in earlier Python versions if you use strings manually,
 with the same caveats.
 
-## Tips for good types
+### Tips for good types
 
 These are some guidelines to help you in writing good type hints.
 
-### Loose vs. specific types
+#### Loose vs. specific types
 
 When you have a function, you should take as generic a type as possible, and
 return as specific a type as possible. For example:
@@ -295,7 +289,7 @@ Also note that the best place to get these in modern Python is
 `collections.abc`, but if you need to subscript them at runtime, you'll need
 Python 3.9+ or the versions in `typing`.
 
-## Final words
+### Final words
 
 When run alongside a good linter like flake8, this can catch a huge number of
 issues before tests or they are discovered in the wild! It also prompts _better
diff --git a/docs/pages/guides/packaging_classic.md b/docs/pages/guides/packaging_classic.md
index cbd613fa..c32b361d 100644
--- a/docs/pages/guides/packaging_classic.md
+++ b/docs/pages/guides/packaging_classic.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Classic packaging
-permalink: /guides/packaging-classic/
-nav_order: 7
-parent: Topical Guides
 ---
 
-{% include toc.html %}
-
-# Classic packaging
+## Classic packaging
 
 The libraries in the scientific Python ecosytem have a variety of different
 packaging styles, but this document is intended to outline a recommended style
@@ -18,31 +12,31 @@ outlined as well.
 There are several popular packaging systems. This guide covers the old
 configuration style for [Setuptools][]. Unless you really need it, you should be
 using the modern style described in [Simple
-Packaging]({% link pages/guides/packaging_simple.md %}). The modern style is
+Packaging](pages/guides/packaging_simple). The modern style is
 guided by Python Enhancement Proposals (PEPs), and is more stable than the
 setuptools-specific mechanisms that evolve over the years. This page is kept to
 help users with legacy code (and hopefully upgrade it).
 
-{: .note }
-
-> Raw source lives in git and has a `pyproject.toml` and/or a `setup.py`. You
-> _can_ install directly from git via pip, but normally users install from
-> distributions hosted on PyPI. There are three options: **A)** A source
-> package, called an SDist and has a name that ends in `.tar.gz`. This is a copy
-> of the GitHub repository, stripped of a few specifics like CI files, and
-> possibly with submodules included (if there are any). **B)** A pure python
-> wheel, which ends in `.whl`; this is only possible if there are no compiled
-> extensions in the library. This does _not_ contain a setup.py, but rather a
-> `PKG_INFO` file that is rendered from setup.py (or from another build system).
-> **C)** If not pure Python, a collection of wheels for every binary platform,
-> generally one per supported Python version and OS as well.
->
-> Developer requirements (users of A or git) are generally higher than the
-> requirements to use B or C. Poetry and optionally flit create SDists that
-> include a `setup.py`, and all alternate packing systems produce "normal"
-> wheels.
-
-## Package structure (medium priority)
+:::{note}
+Raw source lives in git and has a `pyproject.toml` and/or a `setup.py`. You
+_can_ install directly from git via pip, but normally users install from
+distributions hosted on PyPI. There are three options: **A)** A source
+package, called an SDist and has a name that ends in `.tar.gz`. This is a copy
+of the GitHub repository, stripped of a few specifics like CI files, and
+possibly with submodules included (if there are any). **B)** A pure python
+wheel, which ends in `.whl`; this is only possible if there are no compiled
+extensions in the library. This does _not_ contain a setup.py, but rather a
+`PKG_INFO` file that is rendered from setup.py (or from another build system).
+**C)** If not pure Python, a collection of wheels for every binary platform,
+generally one per supported Python version and OS as well.
+
+Developer requirements (users of A or git) are generally higher than the
+requirements to use B or C. Poetry and optionally flit create SDists that
+include a `setup.py`, and all alternate packing systems produce "normal"
+wheels.
+:::
+
+### Package structure (medium priority)
 
 All packages _should_ have a `src` folder, with the package code residing inside
 it, such as `src/<package>/`. This may seem like extra hassle; after all, you
@@ -52,11 +46,11 @@ common bugs, such as running `pytest` and getting the local version instead of
 the installed version - this obviously tends to break if you build parts of the
 library or if you access package metadata.
 
-## PEP 517/518 support (high priority)
+### PEP 517/518 support (high priority)
 
 Packages should provide a `pyproject.toml` file that _at least_ looks like this:
 
-```toml
+```ini
 [build-system]
 requires = ["setuptools>=42"]
 build-backend = "setuptools.build_meta"
@@ -85,16 +79,16 @@ these "[hypermodern][]" packaging tools is growing in scientific Python
 packages. All tools build the same wheels (and they often build setuptools
 compliant SDists, as well).
 
-{% rr PP003 %} Note that `"wheel"` is never required; it was injected
+{rr}`PP003` Note that `"wheel"` is never required; it was injected
 automatically by setuptools in older versions, and is no longer used at all.
 
-### Special additions: NumPy
+#### Special additions: NumPy
 
 You may want to build against NumPy (mostly for Cython packages, pybind11 does
 not need to access the NumPy headers). This is the recommendation for scientific
 Python packages supporting older versions of NumPy:
 
-```toml
+```ini
 requires = [
     "oldest-supported-numpy",
 ```
@@ -104,32 +98,33 @@ package. Whether you build the wheel locally or on CI, you can transfer it to
 someone else and it will work on any supported NumPy. The
 `oldest-supported-numpy` package is a SciPy metapackage from the NumPy
 developers that tracks the
-[correct version of NumPy to build wheels against for each version of Python and for each OS/implementation](https://github.com/scipy/oldest-supported-numpy/blob/master/setup.cfg).
+[correct version of NumPy to build wheels against for each version of Python
+and for each OS/implementation][oldest-supported-numpy].
 Otherwise, you would have to list the earliest version of NumPy that had support
 for each Python version here.
 
-{: .note }
+:::{note}
+Modern versions of NumPy (1.25+) allow you to target older versions when
+building, which is _highly_ recommended, and this will become required in
+NumPy 2.0. Now you add:
 
-> Modern versions of NumPy (1.25+) allow you to target older versions when
-> building, which is _highly_ recommended, and this will become required in
-> NumPy 2.0. Now you add:
->
-> ```cpp
-> #define NPY_TARGET_VERSION NPY_1_22_API_VERSION
-> ```
->
-> (Where that number is whatever version you support as a minimum) then make
-> sure you build with NumPy 1.25+ (or 2.0+ when it comes out).
+```cpp
+#define NPY_TARGET_VERSION NPY_1_22_API_VERSION
+```
 
-## Versioning (medium/high priority)
+(Where that number is whatever version you support as a minimum) then make
+sure you build with NumPy 1.25+ (or 2.0+ when it comes out).
+:::
+
+### Versioning (medium/high priority)
 
 Scientific Python packages should use one of the following systems:
 
-### Git tags: official PyPA method
+#### Git tags: official PyPA method
 
 One more section is very useful in your `pyproject.toml` file:
 
-```toml
+```ini
 requires = [
     "setuptools>=42",
     "setuptools_scm[toml]>=3.4",
@@ -189,8 +184,6 @@ computed correctly from a checkout that is too shallow. For GitHub Actions, use
 For GitHub actions, you can add a few lines that will enable you to manually
 trigger builds with custom versions:
 
-{% raw %}
-
 ```yaml
 on:
   workflow_dispatch:
@@ -201,16 +194,14 @@ env:
   SETUPTOOLS_SCM_PRETEND_VERSION: ${{ github.event.inputs.overrideVersion }}
 ```
 
-{% endraw %}
-
 If you fill in the override version setting when triggering a manual workflow
 run, that version will be forced, otherwise, it works as normal.
 
-{: .note }
-
-> Make sure you have a good gitignore, probably starting from
-> [GitHub's Python one](https://github.com/github/gitignore/blob/main/Python.gitignore)
-> or using a [generator site](https://www.toptal.com/developers/gitignore).
+:::{note}
+Make sure you have a good gitignore, probably starting from
+[GitHub's Python one](https://github.com/github/gitignore/blob/main/Python.gitignore)
+or using a [generator site](https://www.toptal.com/developers/gitignore).
+:::
 
 You should also add these two files:
 
@@ -232,7 +223,7 @@ This will allow git archives (including the ones generated from GitHub) to also
 support versioning. This will only work with `setuptools_scm>=7` (though adding
 the files won't hurt older versions).
 
-### Classic in-source versioning
+#### Classic in-source versioning
 
 Recent versions of `setuptools` have improved in-source versioning. If you have
 a simple file that includes a line with a simple PEP 440 style version, like
@@ -253,7 +244,7 @@ requirements only, this will fail.
 Flit will always look for `package.__version__`, and so will always import your
 package; you just have to deal with that if you use Flit.
 
-## Setup configuration (medium priority)
+### Setup configuration (medium priority)
 
 You should put as much as possible in your `setup.cfg`, and leave `setup.py` for
 _only_ parts that need custom logic or binary building. This keeps your
@@ -324,7 +315,7 @@ where = src
 #     extern
 ```
 
-{% rr SCFG001 %} Note that all keys use underscores; using a dash will cause
+{rr}`SCFG001` Note that all keys use underscores; using a dash will cause
 warnings and eventually failures.
 
 And, a possible `setup.py`; though in recent versions of pip, there no longer is
@@ -357,13 +348,13 @@ SDist structure that shows up in another place in the package, then replace
 With the exception of flake8, all package configuration should be possible via
 `pyproject.toml`, such as pytest (6+):
 
-```toml
+```ini
 [tool.pytest]
 junit_family = "xunit2"
 testpaths = ["tests"]
 ```
 
-## Extras (low/medium priority)
+### Extras (low/medium priority)
 
 It is recommended to use extras instead of or in addition to making requirement
 files. These extras a) correctly interact with install requires and other
@@ -407,7 +398,7 @@ Self dependencies can be placed in `setup.cfg` using the name of the package,
 such as `dev = package[test,examples]`, but this requires Pip 21.2 or newer. We
 recommend providing at least `test`, `docs`, and `dev`.
 
-## Including/excluding files in the SDist
+### Including/excluding files in the SDist
 
 Python packaging goes through a 3-stage procedure if you have the above
 recommended `pyproject.toml` file. If you type `pip install .`, then
@@ -435,7 +426,7 @@ be all of git][setuptools_scm file]; if you do not, the default is a few common
 files, like any `.py` files and standard tooling. Here is a useful default,
 though be sure to update it to include any files that need to be included:
 
-```
+```text
 graft src
 graft tests
 
@@ -443,7 +434,7 @@ include LICENSE README.md pyproject.toml setup.py setup.cfg
 global-exclude __pycache__ *.py[cod] .venv
 ```
 
-## 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 `console_scripts` entry point. The form is:
@@ -470,15 +461,11 @@ the app.
     default behavior is changing, though, as there's much less reason today to
     have a legacy `setup.py`.
 
-<!-- prettier-ignore-start -->
-
 [flit]: https://flit.readthedocs.io
 [poetry]: https://python-poetry.org
-[hatch]: https://hatch.pypa.io
 [hypermodern]: https://cjolowicz.github.io/posts/hypermodern-python-01-setup/
 [setuptools_scm file]: https://setuptools-scm.readthedocs.io/en/latest/usage/#file-finders-hook-makes-most-of-manifestin-unnecessary
 [manifest.in]: https://packaging.python.org/guides/using-manifest-in/
 [setuptools]: https://setuptools.readthedocs.io/en/latest/userguide/index.html
 [setuptools cfg]: https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html
-
-<!-- prettier-ignore-end -->
+[oldest-supported-numpy]: https://github.com/scipy/oldest-supported-numpy/blob/master/setup.cfg
diff --git a/docs/pages/guides/packaging_compiled.md b/docs/pages/guides/packaging_compiled.md
index 049df61b..bfdc6c65 100644
--- a/docs/pages/guides/packaging_compiled.md
+++ b/docs/pages/guides/packaging_compiled.md
@@ -1,13 +1,7 @@
 ---
-layout: page
 title: Compiled packaging
-permalink: /guides/packaging-compiled/
-nav_order: 6
-parent: Topical Guides
 ---
 
-{% include toc.html %}
-
 <!-- [[[cog
 from cog_helpers import code_fence, render_cookie, TOMLMatcher
 with render_cookie(backend="skbuild", vcs=False) as skbuild:
@@ -26,15 +20,13 @@ with render_cookie(backend="maturin", vcs=False) as maturin:
 ]]] -->
 <!-- [[[end]]] -->
 
-{: .highlight-title }
-
-> Quick start
->
-> Once you've done this at least once, feel free to use
-> [our cookiecutter/copier template](https://github.com/scientific-python/cookie),
-> or `uv init` to get started quickly on new packages!
+:::{tip} Quick start
+Once you've done this at least once, feel free to use
+[our cookiecutter/copier template](https://github.com/scientific-python/cookie),
+or `uv init` to get started quickly on new packages!
+:::
 
-# Packaging Compiled Projects
+## Packaging Compiled Projects
 
 There are a variety of ways to package compiled projects. In the past, the only
 way to do it was to use setuptools/distutils, which required using lots of
@@ -50,135 +42,136 @@ The most exciting developments have been new native build backends:
 - [enscons][]: Builds C/C++ using SCONs. (Aging now, but this was the first
   native backend!)
 
-{: .note }
-
+:::{note}
 You should be familiar with [packing a pure Python
-project]({% link pages/guides/packaging_compiled.md %}) - the metadata
+project](pages/guides/packaging_compiled) - the metadata
 configuration is the same.
-
+:::
 There are also classic setuptools plugins:
 
 - [scikit-build][]: Builds C/C++/Fortran using CMake.
 - [setuptools-rust][]: Builds Rust using Cargo.
 
-{: .highlight-title }
-
-> Selecting a backend
->
-> Selecting a backend: If you are using Rust, use maturin. If you are using
-> CUDA, use scikit-build-core. If you are using a classic language (C, C++,
-> Fortran), then you can use either scikit-build-core or meson-python, depending
-> on whether you prefer writing CMake or Meson. Meson is a lot more opinionated;
-> it requires you use version control, it requires a README.md and LICENSE file.
-> It requires your compiler be properly set up. Etc. While CMake can be as
-> elegant as Meson, there are a lot of historical examples of poorly written
-> CMake.
+:::{tip} Selecting a backend
+Selecting a backend: If you are using Rust, use maturin. If you are using
+CUDA, use scikit-build-core. If you are using a classic language (C, C++,
+Fortran), then you can use either scikit-build-core or meson-python, depending
+on whether you prefer writing CMake or Meson. Meson is a lot more opinionated;
+it requires you use version control, it requires a README.md and LICENSE file.
+It requires your compiler be properly set up. Etc. While CMake can be as
+elegant as Meson, there are a lot of historical examples of poorly written
+CMake.
+:::
 
-## pyproject.toml: build-system
+### pyproject.toml: build-system
 
-{% rr PY001 %} Packages must have a `pyproject.toml` file {% rr PP001 %} that
+{rr}`PY001` Packages must have a `pyproject.toml` file {rr}`PP001` that
 selects the backend:
 
-{% tabs %} {% tab skbc Scikit-build-core %}
-
+::::{tab-set}
+:::{tab-item} Scikit-build-core
+:sync: scikit-build-core
 <!-- [[[cog
 with code_fence("toml"):
     print(skbuild_pyproject.get_source("build-system"))
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [build-system]
 requires = ["pybind11", "scikit-build-core>=0.12"]
 build-backend = "scikit_build_core.build"
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
-
-{% endtab %} {% tab meson Meson-python %}
-
+:::
+:::{tab-item} Meson-python
+:sync: meson-python
 <!-- [[[cog
 with code_fence("toml"):
     print(mesonpy_pyproject.get_source("build-system"))
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [build-system]
 requires = ["meson-python>=0.18", "pybind11"]
 build-backend = "mesonpy"
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
-
-{% endtab %} {% tab maturin Maturin %}
-
+:::
+:::{tab-item} Maturin
+:sync: maturin
 <!-- [[[cog
 with code_fence("toml"):
     print(maturin_pyproject.get_source("build-system"))
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [build-system]
 requires = ["maturin>=1.9,<2"]
 build-backend = "maturin"
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-{% include pyproject.md %}
+```{include} ../../_partials/pyproject.md
+```
 
-## Tool section in pyproject.toml
+### Tool section in pyproject.toml
 
 These tools all read the project table. They also have extra configuration
 options in `tool.*` settings.
 
-{% tabs %} {% tab skbc Scikit-build-core %}
-
+::::{tab-set}
+:::{tab-item} Scikit-build-core
+:sync: scikit-build-core
 <!-- [[[cog
 with code_fence("toml"):
     print(skbuild_pyproject.get_source("tool.scikit-build"))
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [tool.scikit-build]
 minimum-version = "build-system.requires"
 build-dir = "build/{wheel_tag}"
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 These options are not required, but can improve your experience.
-
-{% endtab %} {% tab meson Meson-python %}
-
+:::
+:::{tab-item} Meson-python
+:sync: meson-python
 No `tool.meson-python` configuration required for this example.
-
-{% endtab %} {% tab maturin Maturin %}
-
+:::
+:::{tab-item} Maturin
+:sync: maturin
 <!-- [[[cog
 with code_fence("toml"):
     print(maturin_pyproject.get_source("tool.maturin"))
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [tool.maturin]
 module-name = "package._core"
 python-source = "src"
 sdist-generator = "git"  # default is cargo
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 Maturin assumes you follow Rust's package structure, so we need a little bit of
 configuration here to follow the convention of the other tools here.
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-## Backend specific files
-
-{% tabs %} {% tab skbc Scikit-build-core %}
+### Backend specific files
 
+::::{tab-set}
+:::{tab-item} Scikit-build-core
+:sync: scikit-build-core
 Example `CMakeLists.txt` file (using pybind11, so include `pybind11` in
 `build-system.requires` too):
 
@@ -186,7 +179,7 @@ Example `CMakeLists.txt` file (using pybind11, so include `pybind11` in
 with code_fence("cmake"):
     print(skbuild_cmakelists_txt)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```cmake
 cmake_minimum_required(VERSION 3.15...3.26)
 project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
@@ -197,15 +190,15 @@ find_package(pybind11 CONFIG REQUIRED)
 pybind11_add_module(_core MODULE src/main.cpp)
 install(TARGETS _core DESTINATION ${SKBUILD_PROJECT_NAME})
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 Scikit-build-core will use your `.gitignore` to help it avoid adding ignored
 files to your distributions; it also has a default ignore for common cache
 files, so you can get started without one, but it's recommended.
-
-{% endtab %} {% tab meson Meson-python %}
-
+:::
+:::{tab-item} Meson-python
+:sync: meson-python
 Example `meson.build` file (using pybind11, so include `pybind11` in
 `build-system.requires` too):
 
@@ -213,7 +206,7 @@ Example `meson.build` file (using pybind11, so include `pybind11` in
 with code_fence("meson"):
     print(mesonpy_meson_build)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```meson
 project(
     'package',
@@ -238,23 +231,23 @@ py.extension_module('_core',
 
 install_subdir('src/package', install_dir: py.get_install_dir() / 'package', strip_directory: true)
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 Meson requires that your source be tracked by version control. In a real
 project, you will likely be doing this, but when trying out a build backend you
 might not think to set up a git repo to build it.
-
-{% endtab %} {% tab maturin Maturin %}
-
+:::
+:::{tab-item} Maturin
+:sync: maturin
 Example `Cargo.toml` file:
 
 <!-- [[[cog
 with code_fence("toml"):
     print(maturin_cargo_toml)
 ]]] -->
-<!-- prettier-ignore-start -->
-```toml
+<!-- rumdl-disable MD013 -->
+```ini
 [package]
 name = "package"
 version = "0.1.0"
@@ -274,27 +267,28 @@ version = "0.27.2"
 # "abi3-py310" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.10
 features = ["extension-module", "abi3-py310"]
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-## Example compiled file
+### Example compiled file
 
 This example will make a `_core` extension inside your package; this pattern
 allows you to easily provide both Python files and compiled extensions, and
 keeping the details of your compiled extension private. You can select whatever
 name you wish, though, or even make your compiled extension a top level module.
 
-{% tabs %} {% tab skbc Scikit-build-core %}
-
+::::{tab-set}
+:::{tab-item} Scikit-build-core
+:sync: scikit-build-core
 Example `src/main.cpp` file:
 
 <!-- [[[cog
 with code_fence("cpp"):
     print(skbuild_src_main_cpp)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```cpp
 #include <pybind11/pybind11.h>
 
@@ -324,18 +318,18 @@ PYBIND11_MODULE(_core, m) {
   )pbdoc");
 }
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
-
-{% endtab %} {% tab meson Meson-python %}
-
+:::
+:::{tab-item} Meson-python
+:sync: meson-python
 Example `src/main.cpp` file:
 
 <!-- [[[cog
 with code_fence("cpp"):
     print(mesonpy_src_main_cpp)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```cpp
 #include <pybind11/pybind11.h>
 
@@ -365,18 +359,18 @@ PYBIND11_MODULE(_core, m) {
   )pbdoc");
 }
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
-
-{% endtab %} {% tab maturin Maturin %}
-
+:::
+:::{tab-item} Maturin
+:sync: maturin
 Example `src/lib.rs` file:
 
 <!-- [[[cog
 with code_fence("rs"):
     print(maturin_src_lib_rs)
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```rs
 use pyo3::prelude::*;
 
@@ -405,37 +399,37 @@ mod _core {
     }
 }
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
+:::
+::::
 
-{% endtab %} {% endtabs %}
-
-## Package structure
+### Package structure
 
 The recommendation (followed above) is to have source code in `/src`, and the
 Python package files in `/src/<package>`. The compiled files also can go in
 `/src`.
 
-## Versioning
+### Versioning
 
 Check the documentation for the tools above to see what forms of dynamic
 versioning the tool supports.
 
-## Including/excluding files in the SDist
+### Including/excluding files in the SDist
 
 Each tool uses a different mechanism to include or remove files from the SDist,
 though the defaults are reasonable.
 
-## Distributing
+### Distributing
 
 Unlike pure Python, you'll need to build redistributable wheels for each
 platform and supported Python version if you want to avoid compilation on the
 user's system using cibuildwheel. See [the CI page on wheels][gha_wheels] for a
 suggested workflow.
 
-## Special considerations
+### Special considerations
 
-### NumPy
+#### NumPy
 
 Modern versions of NumPy (1.25+) allow you to target older versions when
 building, which is _highly_ recommended, and this became required in NumPy 2.0.
@@ -453,24 +447,14 @@ for those versions.
 
 If using pybind11, you don't need NumPy at build-time in the first place.
 
-{: .important }
-
+:::{important}
 Python 3.13.4 is broken on Windows for compiling code - it always reports that
 it is free-threaded. 3.13.5 was rushed out to fix it.
-
-<!-- prettier-ignore-start -->
+:::
 
 [scikit-build-core]: https://scikit-build-core.readthedocs.io
 [scikit-build]: https://scikit-build.readthedocs.io
 [meson-python]: https://meson-python.readthedocs.io
-[cmake]: https://cmake.org
-[meson]: https://mesonbuild.com
-[enscons]: https://pypi.org/project/enscons
-[scons]: https://scons.org/
 [setuptools-rust]: https://setuptools-rust.readthedocs.io/en/latest/
 [maturin]: https://www.maturin.rs
-[gha_wheels]: {% link pages/guides/gha_wheels.md %}
-
-<!-- prettier-ignore-end -->
-
-<script src="{% link assets/js/tabs.js %}"></script>
+[gha_wheels]: pages/guides/gha_wheels
diff --git a/docs/pages/guides/packaging_simple.md b/docs/pages/guides/packaging_simple.md
index b22b7766..499ca354 100644
--- a/docs/pages/guides/packaging_simple.md
+++ b/docs/pages/guides/packaging_simple.md
@@ -1,22 +1,14 @@
 ---
-layout: page
 title: Simple packaging
-permalink: /guides/packaging-simple/
-nav_order: 5
-parent: Topical Guides
 ---
 
-{% include toc.html %}
+:::{tip} Quick start
+Once you've done this at least once, feel free to use
+[our cookiecutter/copier template](https://github.com/scientific-python/cookie),
+or `uv init` to get started quickly on new packages!
+:::
 
-{: .highlight-title }
-
-> Quick start
->
-> Once you've done this at least once, feel free to use
-> [our cookiecutter/copier template](https://github.com/scientific-python/cookie),
-> or `uv init` to get started quickly on new packages!
-
-# Simple packaging
+## Simple packaging
 
 Python packages can now use a modern build system instead of the classic but
 verbose setuptools and `setup.py`. The one you select doesn't really matter that
@@ -30,80 +22,83 @@ and compiled backends (see the next page).
 Also see the [Python packaging guide][], especially the [Python packaging
 tutorial][].
 
-{: .note-title }
-
-> Classic files
->
-> These systems do not use or require `setup.py`, `setup.cfg`, or `MANIFEST.in`.
-> Those are for setuptools. Unless you are using setuptools, of course, which
-> still uses `MANIFEST.in`. You can convert the old files using
-> `pipx run hatch new --init` or with
-> [ini2toml](https://ini2toml.readthedocs.io/en/latest/).
+:::{note} Classic files
+These systems do not use or require `setup.py`, `setup.cfg`, or `MANIFEST.in`.
+Those are for setuptools. Unless you are using setuptools, of course, which
+still uses `MANIFEST.in`. You can convert the old files using
+`pipx run hatch new --init` or with
+[ini2toml](https://ini2toml.readthedocs.io/en/latest/).
+:::
 
-{: .important-title }
+:::{important} Selecting a backend
+Backends handle metadata the same way, so the choice comes down to how you
+specify what files go into an SDist and extra features, like getting a version
+from VCS. If you don't have an existing preference, hatchling is an excellent
+choice, balancing speed, configurability, and extendability.
+:::
 
-> Selecting a backend
->
-> Backends handle metadata the same way, so the choice comes down to how you
-> specify what files go into an SDist and extra features, like getting a version
-> from VCS. If you don't have an existing preference, hatchling is an excellent
-> choice, balancing speed, configurability, and extendability.
+### pyproject.toml: build-system
 
-## pyproject.toml: build-system
-
-{% rr PY001 %} Packages must have a `pyproject.toml` file {% rr PP001 %} that
+{rr}`PY001` Packages must have a `pyproject.toml` file {rr}`PP001` that
 selects the backend:
 
-{% tabs %} {% tab hatch Hatchling %}
+::::{tab-set}
+:::{tab-item} Hatchling
 
-```toml
+```ini
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 ```
 
-{% endtab %} {% tab uv uv_build %}
+:::
+:::{tab-item} uv_build
 
-```toml
+```ini
 [build-system]
 requires = ["uv_build>=0.7.19"]
 build-backend = "uv_build"
 ```
 
-{% endtab %} {% tab flit Flit-core %}
+:::
+:::{tab-item} Flit-core
 
-```toml
+```ini
 [build-system]
 requires = ["flit_core>=3.12"]
 build-backend = "flit_core.buildapi"
 ```
 
-{% endtab %} {% tab pdm PDM-backend %}
+:::
+:::{tab-item} PDM-backend
 
-```toml
+```ini
 [build-system]
 requires = ["pdm-backend"]
 build-backend = "pdm.backend"
 ```
 
-{% endtab %} {% tab setuptools Setuptools %}
+:::
+:::{tab-item} Setuptools
 
-```toml
+```ini
 [build-system]
 requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 ```
 
-{% endtab %} {% endtabs %}
+:::
+::::
 
-{% include pyproject.md %}
+```{include} ../../_partials/pyproject.md
+```
 
 For `requires-python`, you should specify the minimum you require, and you
-should not put an upper cap on it {% rr PY004 %}, as this field is used to
+should not put an upper cap on it {rr}`PY004`, as this field is used to
 back-solve for old package versions that pass this check, allowing you to safely
 drop Python versions.
 
-## Package structure
+### Package structure
 
 All packages _should_ have a `src` folder, with the package code residing inside
 it, such as `src/<package>/`. This may seem like extra hassle; after all, you
@@ -120,11 +115,11 @@ detection.
 If you don't match your package name and import name (which you should except
 for very special cases), you will likely need extra configuration here.
 
-You should have a `README` {% rr PY002 %} and a `LICENSE` {% rr PY003 %} file.
-You should have a `docs/` folder {% rr PY004 %}. You should have a `/tests`
-folder {% rr PY005 %} (recommended) and/or a `src/<package>/tests` folder.
+You should have a `README` {rr}`PY002` and a `LICENSE` {rr}`PY003` file.
+You should have a `docs/` folder {rr}`PY004`. You should have a `/tests`
+folder {rr}`PY005` (recommended) and/or a `src/<package>/tests` folder.
 
-## Versioning
+### Versioning
 
 You can specify the version manually (as shown in the example), but the backends
 usually provide some automatic features to help you avoid this. Flit will pull
@@ -134,18 +129,17 @@ in a file or use git.
 You will always need to specify that the version will be supplied dynamically
 with:
 
-```toml
+```ini
 dynamic = ["version"]
 ```
 
 Then you'll configure your backend to compute the version.
 
-{% details Hatchling dynamic versioning %}
-
+:::{dropdown} Hatchling dynamic versioning
 You can tell hatchling to get the version from VCS. Add `hatch-vcs` to your
 `build-backend.requires`, then add the following configuration:
 
-```toml
+```ini
 [tool.hatch]
 version.source = "vcs"
 build.hooks.vcs.version-file = "src/<package>/version.py"
@@ -153,7 +147,7 @@ build.hooks.vcs.version-file = "src/<package>/version.py"
 
 Or you can tell it to look for it in a file (see docs for arbitrary regex's):
 
-```toml
+```ini
 [tool.hatch]
 version.path = "src/<package>/__init__.py"
 ```
@@ -178,10 +172,9 @@ And `.gitattributes` (or add this line if you are already using this file):
 
 This will allow git archives (including the ones generated from GitHub) to also
 support versioning.
+:::
 
-{% enddetails %}
-
-## Including/excluding files in the SDist
+### Including/excluding files in the SDist
 
 This is tool specific.
 
@@ -194,25 +187,24 @@ This is tool specific.
 - [PDM info here](https://pdm-backend.fming.dev/build_config/#include-or-exclude-files).
 - Setuptools still uses `MANIFEST.in`.
 
-{: .warning }
-
-> Flit will not use VCS (like git) to populate the SDist if you use standard
-> tooling, even if it can do that using its own tooling. So make sure you list
-> explicit include/exclude rules, and test the contents:
->
-> ```bash
-> # Show SDist contents
-> tar -tvf dist/*.tar.gz
-> # Show wheel contents
-> unzip -l dist/*.whl
-> ```
+:::{warning}
+Flit will not use VCS (like git) to populate the SDist if you use standard
+tooling, even if it can do that using its own tooling. So make sure you list
+explicit include/exclude rules, and test the contents:
 
-{: .note-title }
+```bash
+# Show SDist contents
+tar -tvf dist/*.tar.gz
+# Show wheel contents
+unzip -l dist/*.whl
+```
 
-> Flit _requires_ `license.file` to be set in your `[project]` section to ensure
-> it finds the license file.
+:::
 
-<!-- prettier-ignore-start -->
+:::{note}
+Flit _requires_ `license.file` to be set in your `[project]` section to ensure
+it finds the license file.
+:::
 
 [flit]: https://flit.readthedocs.io
 [poetry]: https://python-poetry.org
@@ -224,7 +216,4 @@ This is tool specific.
 [meson-python]: https://meson-python.readthedocs.io
 [python packaging guide]: https://packaging.python.org
 [python packaging tutorial]: https://packaging.python.org/tutorials/packaging-projects/
-
-<!-- prettier-ignore-end -->
-
-<script src="{% link assets/js/tabs.js %}"></script>
+[metadata]: https://packaging.python.org/en/latest/specifications/core-metadata/
diff --git a/docs/pages/guides/pytest.md b/docs/pages/guides/pytest.md
index 6c0612de..97441e87 100644
--- a/docs/pages/guides/pytest.md
+++ b/docs/pages/guides/pytest.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: "Testing with pytest"
-permalink: /guides/pytest/
-nav_order: 2
-parent: Topical Guides
 ---
 
-{% include toc.html %}
-
-# Testing with pytest
+## Testing with pytest
 
 Tests are crucial to writing reliable software. A good test suite allows you to:
 
@@ -29,17 +23,15 @@ in using pytest. The goals of writing good tests are:
 - Reporting: when things break, you should get good information about what
   broke.
 
-{: .note-title }
-
-> What about other choices?
->
-> The alternative library, `nose`, has been abandoned in favor of `pytest`,
-> which can run nose-style tests. The standard library has a test suite as well,
-> but it's extremely verbose and complex; and since "developers" run tests, your
-> test requirements don't affect users. And `pytest` can run stdlib style
-> testing too. So just use `pytest`. All major packages use it too, including
-> `NumPy`. Most other choices, like [Hypothesis][], are related to `pytest` and
-> just extend it.
+:::{note} What about other choices?
+The alternative library, `nose`, has been abandoned in favor of `pytest`,
+which can run nose-style tests. The standard library has a test suite as well,
+but it's extremely verbose and complex; and since "developers" run tests, your
+test requirements don't affect users. And `pytest` can run stdlib style
+testing too. So just use `pytest`. All major packages use it too, including
+`NumPy`. Most other choices, like [Hypothesis][], are related to `pytest` and
+just extend it.
+:::
 
 ### Basic test structure
 
@@ -63,17 +55,18 @@ This looks simple, but it is doing several things:
   happens. If it fails, you will get a clear, detailed report on what each value
   was.
 
-### Configuring pytest
+#### Configuring pytest
 
 pytest supports configuration in `pytest.ini`, `setup.cfg`, or, since version 6,
-`pyproject.toml` {% rr PP301 %}, or, since version 9, `pytest.toml` or
+`pyproject.toml` {rr}`PP301`, or, since version 9, `pytest.toml` or
 `.pytest.toml`. Remember, pytest is a developer requirement, not a user one, so
 always require 6+ (or 9+) and use `pyproject.toml` or the pytest TOML ones. This
 is an example configuration:
 
-{% tabs %} {% tab conf-modern Pytest 9+ %}
+::::{tab-set}
+:::{tab-item} Pytest 9+
 
-```toml
+```ini
 [tool.pytest]
 minversion = "9.0"
 addopts = ["-ra", "--showlocals"]
@@ -85,9 +78,10 @@ testpaths = [
 ]
 ```
 
-{% endtab %} {% tab conf-classic Pytest 6+ %}
+:::
+:::{tab-item} Pytest 6+
 
-```toml
+```ini
 [tool.pytest.ini_options]
 minversion = "6.0"
 addopts = ["-ra", "--showlocals", "--strict-markers", "--strict-config"]
@@ -99,24 +93,25 @@ testpaths = [
 ]
 ```
 
-{% endtab %} {% endtabs %}
+:::
+::::
 
-{% rr PP302 %} The `minversion` will print a nicer error if your `pytest` is too
+{rr}`PP302` The `minversion` will print a nicer error if your `pytest` is too
 old (though, ironically, it won't read this if the version is too old, so
 setting "6" or less in `pyproject.toml` is rather pointless, similarly for 9 if
 using the new config location). The `addopts` setting will add whatever you put
-there to the command line when you run; {% rr PP308 %} `-ra` will print a
+there to the command line when you run; {rr}`PP308` `-ra` will print a
 summary "r"eport of "a"ll results, which gives you a quick way to review what
 tests failed and were skipped, and why. `--showlocals` will print locals in
 tracebacks - depending on your tests, you might or might not like this one.
-{% rr PP307 %} `--strict-markers` will make sure you don't try to use an
-unspecified fixture. {% rr PP306 %} And `--strict-config` will error if you make
-a mistake in your config. {% rr PP305 %} `xfail_strict` will change the default
+{rr}`PP307` `--strict-markers` will make sure you don't try to use an
+unspecified fixture. {rr}`PP306` And `--strict-config` will error if you make
+a mistake in your config. {rr}`PP305` `xfail_strict` will change the default
 for `xfail` to fail the tests if it doesn't fail - you can still override
-locally in a specific xfail for a flaky failure. {% rr PP309 %}
+locally in a specific xfail for a flaky failure. {rr}`PP309`
 `filter_warnings` will cause all warnings to be errors (you can add allowed
-warnings here too, see below). {% rr PP304 %} `log_level` will report `INFO` and
-above log messages on a failure. {% rr PP303 %} Finally, `testpaths` will limit
+warnings here too, see below). {rr}`PP304` `log_level` will report `INFO` and
+above log messages on a failure. {rr}`PP303` Finally, `testpaths` will limit
 `pytest` to just looking in the folders given - useful if it tries to pick up
 things that are not tests from other directories.
 [See the docs](https://docs.pytest.org/en/stable/customize.html) for more
@@ -144,7 +139,7 @@ becoming errors using the syntax
 tends to be `default` (show the first time) or `ignore` (never show). The regex
 matches at the beginning of the error unless you prefix it with `.*`.
 
-### Running pytest
+#### Running pytest
 
 You can run pytest directly with `pytest` or `python -m pytest`. You can
 optionally give a directory or file to run on. You can also select just some
@@ -161,13 +156,13 @@ start out in your debugger at the beginning of the last failed test with
 `--trace --lf`. [See the docs](https://docs.pytest.org/en/stable/usage.html) for
 more running tips.
 
-## Guidelines for writing good tests
+### Guidelines for writing good tests
 
 Time spent learning all the powerful tools pytest has to offer will be well
 spent! You can make your tests more granular, mock things that aren't available
 (or are slow to run), parametrize, and much more.
 
-### Tests should be easy
+#### Tests should be easy
 
 Always use pytest. The built-in unittest is _very_ verbose; the simpler the
 writing of tests, the more tests you will write!
@@ -210,7 +205,7 @@ This natively works with NumPy arrays, too! Always prefer
 `array1 == approx(array2)` over the functions in the `numpy.testing` module if
 you can, it is simpler and the reporting is better.
 
-### Tests should test for failures too
+#### Tests should test for failures too
 
 You should make sure that expected errors are thrown:
 
@@ -226,7 +221,7 @@ def test_raises():
 You can check for warnings as well, with `pytest.warns` or
 `pytest.deprecated_call`.
 
-### Tests should stay easy when scaling out
+#### Tests should stay easy when scaling out
 
 pytest [uses fixtures](https://docs.pytest.org/en/stable/fixture.html) to
 represent complex ideas, like setup/teardown, temporary resources, or
@@ -289,7 +284,7 @@ conftest) will run three times, and each time will identify as a different
 `platform.system()`! Leave `autouse` off, and it becomes opt-in; adding
 `platform_system` to the list of arguments will opt in.
 
-### Tests should be organized
+#### Tests should be organized
 
 You can use `pytest.mark.*` to
 [mark](https://docs.pytest.org/en/stable/mark.html) tests, so you can easily
@@ -321,7 +316,7 @@ Many pytest plugins support new marks too, like `pytest-parametrize`. You can
 also use custom marks to enable/disable groups of tests, or to pass data into
 fixtures.
 
-### Tests should test the installed version, not the local version
+#### Tests should test the installed version, not the local version
 
 Your tests should run against an _installed_ version of your code. Testing
 against the _local_ version might work while the installed version does not (due
@@ -332,7 +327,7 @@ directories and `pytest` does not. Also, there may come a time when someone
 a build system, and if you are unable to test against an installed version, you
 won't be able to run your tests! (It happens more than you might think).
 
-### Mock expensive or tricky calls
+#### Mock expensive or tricky calls
 
 If you have to call something that is expensive or hard to call, it is often
 better to mock it. To isolate parts of your own code for "unit" testing, mocking
@@ -392,5 +387,3 @@ redirects to the standard library [unittest.mock][].
 [pytest]: https://docs.pytest.org
 [pytest-mock]: https://pypi.org/project/pytest-mock/
 [unittest.mock]: https://docs.python.org/3/library/unittest.mock.html
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/guides/repo_review.md b/docs/pages/guides/repo_review.md
index b68913c7..b8f27090 100644
--- a/docs/pages/guides/repo_review.md
+++ b/docs/pages/guides/repo_review.md
@@ -1,12 +1,8 @@
 ---
-layout: page
 title: Repo-Review
-permalink: /guides/repo-review/
-nav_order: 110
-interactive_repo_review: true
 ---
 
-# Repo-Review
+## Repo-Review
 
 You can check the style of a GitHub repository below. Enter any repository, such
 as `scikit-hep/hist`, and the branch you want to check, such as `main` (it must
@@ -25,6 +21,14 @@ pipx run 'sp-repo-review[cli]' <path to repo>
 
 ---
 
-{% include interactive_repo_review.html %}
-
-[Open in new page](https://scientific-python.github.io/repo-review/).
+:::{anywidget} <https://cdn.jsdelivr.net/npm/repo-review-webapp@1.1.2/dist/repo-review-anywidget.mjs>
+{
+  "url_sync": true,
+  "deps": [
+    "repo-review~=1.1.0",
+    "sp-repo-review==2026.04.04",
+    "validate-pyproject[all]~=0.25.0",
+    "validate-pyproject-schema-store==2026.03.29",
+  ]
+}
+:::
diff --git a/docs/pages/guides/style.md b/docs/pages/guides/style.md
index 9f4878e7..1f982135 100644
--- a/docs/pages/guides/style.md
+++ b/docs/pages/guides/style.md
@@ -1,32 +1,25 @@
 ---
-layout: page
 title: Style & static checks
-permalink: /guides/style/
-nav_order: 8
-parent: Topical Guides
-custom_title: Style and static checks
+short_title: Style and static checks
 ---
 
-{% include toc.html %}
+## Style and static checks
 
-# Style and static checks
+### Pre-commit
 
-## Pre-commit
-
-{% rr PY006 %} Scientific Python projects often use [pre-commit][] (or [prek][])
+{rr}`PY006` Scientific Python projects often use [pre-commit][] (or [prek][])
 to check code style. The original, `pre-commit`, has support for more languages,
 but `prek` is a faster Rust rewrite that supports most real world usage.
 
-{% tabs runner %} {% tab prek Prek %}
-
+::::{tab-set}
+:::{tab-item} Prek
 Prek can be installed through `brew` (macOS) or `pipx/uv` (anywhere). There are
 two modes to use it locally; you can check manually with `prek run` (changes
 only) or `prek run -a` (all). You can omit the `run`, as well; such as
 `prek -a`. You can also run `prek install` to add checks as a git pre-commit
 hook.
-
-{% endtab %} {% tab pre-commit Pre-commit %}
-
+:::
+:::{tab-item} Pre-commit
 Pre-commit can be installed through `brew` (macOS) or `pipx/uv` (anywhere).
 There are two modes to use it locally; you can check manually with
 `pre-commit run` (changes only) or `pre-commit run -a` (all). You can also run
@@ -35,8 +28,8 @@ gets its name).
 
 Pre-commit's setup is much slower than prek, but you can install `pre-commit-uv`
 with pre-commit to speed up the setup time quite a bit.
-
-{% endtab %} {% endtabs %}
+:::
+::::
 
 Local runs (with `-a`) are the standard way to use it. That will run all the
 checks in optimized, isolated environments. After the first run, it's quite fast
@@ -47,7 +40,7 @@ a custom pre-commit hook before; it's quite elegant and does not add or commit
 the changes, it just makes the changes and allows you to check and add them. You
 can always override the hook with `-n`.
 
-{% rr PC100 %} Here is a minimal `.pre-commit-config.yaml` file with some handy
+{rr}`PC100` Here is a minimal `.pre-commit-config.yaml` file with some handy
 options:
 
 ```yaml
@@ -94,7 +87,7 @@ docker), you cannot enable a `--manual` flag, so extra checks will not run, and
 jobs should not download packages (use `additional-dependencies:` to add what
 you need).
 
-{% rr PC901 %} {% rr PC902 %} {% rr PC903 %} You can customize the pre-commit
+{rr}`PC901` {rr}`PC902` {rr}`PC903` You can customize the pre-commit
 message with:
 
 ```yaml
@@ -124,9 +117,9 @@ updates:
       default-days: 7
 ```
 
-## Format
+### Format
 
-{% rr PC110 %} [Black](https://black.readthedocs.io/en/latest/) is a popular
+{rr}`PC110` [Black](https://black.readthedocs.io/en/latest/) is a popular
 auto-formatter from the Python Software Foundation. One of the main features of
 Black is that it is "opinionated"; that is, it is almost completely
 unconfigurable. Instead of allowing you to come up with your own format, it
@@ -147,8 +140,8 @@ There are a _few_ options, mostly to enable/disable certain files, remove string
 normalization, and to change the line length, and those go in your
 `pyproject.toml` file.
 
-{% tabs formatters %} {% tab ruff Ruff-format %}
-
+:::::{tab-set}
+::::{tab-item} Ruff-format
 Ruff, the powerful Rust-based linter, has a formatter that is designed with the
 help of some of the Black authors to look 99.9% like Black, but run 30x faster.
 Here is the snippet to add the formatter to your `.pre-commit-config.yml`
@@ -165,23 +158,21 @@ Here is the snippet to add the formatter to your `.pre-commit-config.yml`
 As you likely will be using Ruff if you follow this guide, the formatter is
 recommended as well.
 
-{% details You can add a Ruff badge to your repo as well %}
-
+:::{dropdown} You can add a Ruff badge to your repo as well
 [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
 
 ```md
 [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
 ```
 
-```
+```text
 .. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json
     :target: https://github.com/astral-sh/ruff
 ```
 
-{% enddetails %}
-
-{% endtab %} {% tab black Black %}
-
+:::
+::::
+::::{tab-item} Black
 Here is the snippet to add Black to your `.pre-commit-config.yml`:
 
 ```yaml
@@ -191,22 +182,21 @@ Here is the snippet to add Black to your `.pre-commit-config.yml`:
     - id: black
 ```
 
-{% details You can add a Black badge to your repo as well %}
-
+:::{dropdown} You can add a Black badge to your repo as well
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 ```md
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 ```
 
-```
+```text
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 ```
 
-{% enddetails %}
-
-{% endtab %} {% endtabs %}
+:::
+::::
+:::::
 
 In _very_ specific situations, like when making a 2D array, you may want to
 retain special formatting. After carefully deciding that it is a special use
@@ -216,9 +206,8 @@ option! Most of the time, you can find a way to make the Blacked code look
 better by rewriting your code; factor out long unreadable portions into a
 variable, avoid writing matrices as 1D lists, etc.
 
-{% details Documentation / README snippets support %}
-
-{% rr PC111 %} If you want Black used in your documentation, you can use
+:::{dropdown} Documentation / README snippets support
+{rr}`PC111` If you want Black used in your documentation, you can use
 blacken-docs. This can even catch syntax errors in code snippets! It supports
 markdown and restructured text. Note that because black is in
 `additional_dependencies`, you'll have to keep it up to date manually.
@@ -231,11 +220,11 @@ markdown and restructured text. Note that because black is in
       additional_dependencies: [black==24.*]
 ```
 
-{% enddetails %}
+:::
 
-## Ruff
+### Ruff
 
-{% rr PC190 %} [Ruff][] [(docs)][ruff docs] is a Python code linter and
+{rr}`PC190` [Ruff][] [(docs)][ruff docs] is a Python code linter and
 autofixer that replaces many other tools in the ecosystem with a ultra-fast
 (written in Rust), single zero-dependency package. All plugins are compiled in,
 so you can't get new failures from plugins updating without updating your
@@ -252,16 +241,17 @@ pre-commit hook.
       args: ["--fix", "--show-fixes"]
 ```
 
-{% rr PC192 %} The hook is named `ruff-check`. {% rr PC191 %} The `--fix`
+{rr}`PC192` The hook is named `ruff-check`. {rr}`PC191` The `--fix`
 argument is optional, but recommended, since you can inspect and undo changes in
 git. `--show-fixes` is highly recommended if `--fix` is present, otherwise it
 won't tell you what or why it fixed things.
 
-{% rr RF001 %} Ruff is configured in your `pyproject.toml`. Here's an example:
+{rr}`RF001` Ruff is configured in your `pyproject.toml`. Here's an example:
 
-{% tabs ruff-config %} {% tab ruff-simple Simple config %}
+::::{tab-set}
+:::{tab-item} Simple config
 
-```toml
+```ini
 [tool.ruff.lint]
 extend-select = [
   "B",      # flake8-bugbear
@@ -271,9 +261,10 @@ extend-select = [
 ]
 ```
 
-{% endtab %} {% tab ruff-full Full config %}
+:::
+:::{tab-item} Full config
 
-```toml
+```ini
 [tool.ruff.lint]
 extend-select = [
   "ARG",    # flake8-unused-arguments
@@ -323,9 +314,10 @@ typing-modules = ["mypackage._compat.typing"]
 "tests/**" = ["T20"]
 ```
 
-{% endtab %} {% tab ruff-ignore Ignore-based config %}
+:::
+:::{tab-item} Ignore-based config
 
-```toml
+```ini
 [tool.ruff.lint]
 select = ["ALL"]
 ignore = [
@@ -353,7 +345,8 @@ typing-modules = ["mypackage._compat.typing"]
 "tests/**" = ["T20"]
 ```
 
-{% endtab %} {% endtabs %}
+:::
+::::
 
 Ruff [provides dozens of rule sets](https://beta.ruff.rs/docs/rules/); you can
 select what you want from these. Like Flake8, plugins match by whole letter
@@ -373,31 +366,31 @@ entirely from pre-commit (default excludes include "build", so if you have a
 this).
 
 The `src` list which tells it where to look for top level packages is no longer
-needed if just set to `["src"]` in Ruff 0.6+. {% rr RF003 %}
+needed if just set to `["src"]` in Ruff 0.6+. {rr}`RF003`
 
-{: .warning }
+:::{warning}
+If you don't use a `[project]` table (older setuptools or Poetry), then you
+should also set:
 
-> If you don't use a `[project]` table (older setuptools or Poetry), then you
-> should also set:
->
-> ```toml
-> target-version = "py39"
-> ```
->
-> This selects the minimum version you want to target (primarily for `"UP"` and
-> `"I"`) {% rr RF002 %}
+```ini
+target-version = "py39"
+```
+
+This selects the minimum version you want to target (primarily for `"UP"` and
+`"I"`) {rr}`RF002`
+:::
 
 Here are some good error codes to enable on most (but not all!) projects:
 
 - `E`, `F`, `W`: These are the standard flake8 checks, classic checks that have
   stood the test of time. Not required if you use `extend-select` (`W` not
   needed if you use a formatter)
-- `B`: This finds patterns that are very bug-prone. {% rr RF101 %}
+- `B`: This finds patterns that are very bug-prone. {rr}`RF101`
 - `I`: This sorts your includes. There are multiple benefits, such as smaller
   diffs, fewer conflicts, a way to auto-inject `__future__` imports, and easier
   for readers to tell what's built-in, third-party, and local. It has a lot of
   configuration options, but defaults to a Black-compatible style.
-  {% rr RF102 %}
+  {rr}`RF102`
 - `ARG`: This looks for unused arguments. You might need to `# noqa: ARG001`
   occasionally, but it's overall pretty useful.
 - `C4`: This looks for places that could use comprehensions, and can autofix
@@ -419,7 +412,7 @@ Here are some good error codes to enable on most (but not all!) projects:
 - `RUF`: Codes specific to Ruff, including removing noqa's that aren't used.
 - `T20`: Disallow `print` in your code (built on the assumption that it's a
   common debugging tool).
-- `UP`: Upgrade old Python syntax to your `target-version`. {% rr RF103 %}
+- `UP`: Upgrade old Python syntax to your `target-version`. {rr}`RF103`
 - `FURB`: From the refurb tool, a collection of helpful cleanups.
 - `PYI`: Typing related checks
 
@@ -428,8 +421,7 @@ Ruff. You can use `ALL` to get them all, then ignore the ones you want to
 ignore. New checks go into `--preview` before being activated in a minor
 release.
 
-{% details You can add a Ruff badge to your repo as well %}
-
+:::{dropdown} You can add a Ruff badge to your repo as well
 [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json))](https://github.com/astral-sh/ruff)
 
 ```md
@@ -441,11 +433,11 @@ release.
     :target: https://github.com/astral-sh/ruff
 ```
 
-{% enddetails %}
+:::
 
-{% details Separate tools that Ruff replaces %}
+::::{dropdown} Separate tools that Ruff replaces
 
-### PyCln
+#### PyCln
 
 [PyCln][] will clean up your imports if you have any that are not needed. There
 is a Flake8 check for this, but it's usually nicer to automatically do the
@@ -461,7 +453,7 @@ use the manual stage, it's opt-in instead of automatic.
       stages: [manual]
 ```
 
-### Flake8
+#### Flake8
 
 [Flake8][] can check a collection of good practices for you, ranging from simple
 style to things that might confuse or detract users, such as unused imports,
@@ -520,8 +512,7 @@ enable more checks. A few interesting plugins:
 - [`flake8-print`](https://pypi.org/project/pep8-naming/): Makes sure you don't
   have print statements that sneak in. Code: `T`
 
-{% details Flake8-print details %}
-
+:::{dropdown} Flake8-print details
 Having something verify you don't add a print statement by mistake is _very_
 useful. A common need for the print checker would be to add it to a single
 directory (`src` if you are following the convention recommended). You can do
@@ -535,9 +526,9 @@ per-file-ignores =
     examples/*: T
 ```
 
-{% enddetails %}
+:::
 
-### YesQA
+#### YesQA
 
 Over time, you can end up with extra "noqa" comments that are no longer needed.
 This is a flake8 helper that removes those comments when they are no longer
@@ -554,7 +545,7 @@ You need to have the same extra dependencies as flake8. In YAML, you can save
 the list given to yesqa and repeat it in flake8 using `&flake8-dependencies` and
 `*flake8-dependencies` after the colon.
 
-### isort
+#### isort
 
 You can have your imports sorted automatically by [isort][]. This will sort your
 imports, and is black compatible. One reason to have sorted imports is to reduce
@@ -580,9 +571,7 @@ In order to use it, you need to add some configuration. You can add it to
 profile = "black"
 ```
 
-[isort]: https://pycqa.github.io/isort/
-
-### PyUpgrade
+#### PyUpgrade
 
 Another useful tool is [PyUpgrade][], which monitors your codebase for "old"
 style syntax. Most useful to keep Python 2 outdated constructs out, it can even
@@ -600,23 +589,22 @@ when clearly better (please always use them, they are faster) if you set
 
 [pyupgrade]: https://github.com/asottile/pyupgrade
 
-{: .note }
+:::{note}
+If you set this to at least `--py37-plus`, you can add the annotations import
+by adding the following line to your isort pre-commit hook configuration:
 
-> If you set this to at least `--py37-plus`, you can add the annotations import
-> by adding the following line to your isort pre-commit hook configuration:
->
-> ```yaml
-> args: ["-a", "from __future__ import annotations"]
-> ```
->
-> Also make sure isort comes before pyupgrade. Now when you run pre-commit, it
-> will clean up your annotations to 3.7+ style, too!
+```yaml
+args: ["-a", "from __future__ import annotations"]
+```
 
-{% enddetails %}
+Also make sure isort comes before pyupgrade. Now when you run pre-commit, it
+will clean up your annotations to 3.7+ style, too!
+:::
+::::
 
-## Type checking
+### Type checking
 
-{% rr PC140 %} One of the most exciting advancements in Python in the last 10
+{rr}`PC140` One of the most exciting advancements in Python in the last 10
 years has been static type hints. Scientific Python projects vary in the degree
 to which they are type-hint ready. One of the challenges for providing static
 type hints is that it was developed in the Python 3 era and it really shines in
@@ -652,7 +640,7 @@ add items to the virtual environment setup for MyPy by pre-commit, for example:
 additional_dependencies: [attrs==23.1.0]
 ```
 
-{% rr MY100 %} MyPy has a config section in `pyproject.toml` that looks like
+{rr}`MY100` MyPy has a config section in `pyproject.toml` that looks like
 this:
 
 ```ini
@@ -679,23 +667,23 @@ enable `check_untyped_defs` first, followed by `disallow_untyped_defs` then
 `disallow_incomplete_defs`. You can add these _per file_ by adding a
 `# mypy: <option>` at the top of a file. You can also pass `--strict` on the
 command line. `strict = true` is now allowed in config files, too
-{% rr MY101 %}.
+{rr}`MY101`.
 
-The extra strict options shown above, like `warn_unreachable` {% rr MY103 %},
-and `ignore-without-code` {% rr MY104 %}, `redundant-expr` {% rr MY105 %}, and
-`truthy-bool` {% rr MY106 %} can trigger too often (like on `sys.platform`
+The extra strict options shown above, like `warn_unreachable` {rr}`MY103`,
+and `ignore-without-code` {rr}`MY104`, `redundant-expr` {rr}`MY105`, and
+`truthy-bool` {rr}`MY106` can trigger too often (like on `sys.platform`
 checks) and have to be ignored occasionally, but can find some significant logic
 errors in your typing.
 
-[mypy page]: {% link pages/guides/mypy.md %}
+[mypy page]: pages/guides/mypy
 
-## Setuptools specific checks
+### Setuptools specific checks
 
 If you use setuptools, these checks are useful:
 
-{% details Setuptools-only checks %}
+::::{dropdown} Setuptools-only checks
 
-### Check-Manifest (setuptools only)
+#### Check-Manifest (setuptools only)
 
 [Check-manifest](https://pypi.org/project/check-manifest/) is a fantastic,
 highly recommended tool that verifies you have working SDists. You can install
@@ -703,7 +691,7 @@ it from PyPI. Run it on your repository and see what it says. If you want to
 ignore files (like test folders, example folders, docs, etc) you can add these
 into your `pyproject.toml` file:
 
-```toml
+```ini
 [tool.check-manifest]
 ignore = [
     ".travis.yml",
@@ -725,8 +713,7 @@ If you use `setuptools_scm`, you might want to add:
 additional_dependencies: ["setuptools_scm[toml]"]
 ```
 
-{% details If this is too slow: %}
-
+:::{dropdown} If this is too slow:
 **Warning**: For a complex package, this may be slow. You can optionally set
 `stages: [manual]` just below the id, and then only run this explicitly
 (probably in CI only). In GHA, you should enable the manual stage, which will
@@ -738,9 +725,9 @@ run all checks:
     extra_args: --show-diff-on-failure --all-files --hook-stage manual
 ```
 
-{% enddetails %}
+:::
 
-### Setup.cfg format (setuptools only)
+#### Setup.cfg format (setuptools only)
 
 There is a tool that keeps your `setup.cfg` organized, and makes sure that
 important parts (like Python classifiers) are in sync. This tool,
@@ -755,18 +742,17 @@ important parts (like Python classifiers) are in sync. This tool,
 ```
 
 Make sure you list the highest version of Python you are testing with here.
+::::
 
-{% enddetails %}
-
-## Spelling
+### Spelling
 
-{% rr PC160 %} You can and should check for spelling errors in your code too. If
+{rr}`PC160` You can and should check for spelling errors in your code too. If
 you want to add this, you can use a code-ready spell checker for common spelling
 mistakes. Unlike most spell checkers, these have a list of mistakes they look
 for, rather than a list of "valid" words. To use:
 
-{% tabs spell %} {% tab codespell codespell %}
-
+::::{tab-set}
+:::{tab-item} codespell
 If you want a Python based tool, [codespell] is the classic tool used.
 
 ```yaml
@@ -791,9 +777,8 @@ ignore-words-list = ["sur", "nd"]
 You can also add the `-w` flag to have it automatically correct errors - this is
 very helpful to quickly make corrections if you have a lot of them when first
 adding the check. `uvx codespell -w` will quickly correct all non-hidden files.
-
-{% endtab %} {% tab typos typos %}
-
+:::
+:::{tab-item} typos
 A rust rewrite of [codespell][], [typos][] has a defining feature: It can find
 typos in CamelCase or snake_case variable names. It also is probably faster,
 though codespell is very fast too. This one is not available on PyPI, use
@@ -810,7 +795,7 @@ integration.
 
 To configure it, you can use this section in `pyproject.toml`:
 
-```toml
+```ini
 [tool.typos.default.extend-words]
 nd = "nd"
 sur = "sur"
@@ -820,8 +805,8 @@ It has quite a few supported configuration options, like adding your own
 corrections, feel free to check the [full reference][typos-ref]. If you want it
 to write changes, you can remove the `args: []` in the pre-commit hook, or add
 `-w` when running it locally.
-
-{% endtab %} {% endtabs %}
+:::
+::::
 
 You can also use a local pygrep check to eliminate common capitalization errors,
 such as the one below:
@@ -836,9 +821,9 @@ such as the one below:
       exclude: .pre-commit-config.yaml
 ```
 
-## PyGrep hooks
+### PyGrep hooks
 
-{% rr PC170 %} This is a repository with a
+{rr}`PC170` This is a repository with a
 [collection of pre-commit extra hooks](https://github.com/pre-commit/pygrep-hooks)
 that protect against some common, easy to detect, mistakes. You can pick and
 choose the hooks you want from the repo; here are some common ones for
@@ -862,20 +847,21 @@ called `mypy_error_report.txt`, then run `pipx run mypy_clean_slate -a`.
 
 [codespell]: https://github.com/codespell-project/codespell
 
-{: .note }
+:::{note}
+Note that if you are not using Ruff's "PGH" code, there are `python-*` hooks
+also:
+
+```yaml
+- id: python-check-blanket-noqa
+- id: python-check-blanket-type-ignore
+- id: python-no-log-warn
+- id: python-no-eval
+- id: python-use-type-annotations
+```
 
-> Note that if you are not using Ruff's "PGH" code, there are `python-*` hooks
-> also:
->
-> ```yaml
-> - id: python-check-blanket-noqa
-> - id: python-check-blanket-type-ignore
-> - id: python-no-log-warn
-> - id: python-no-eval
-> - id: python-use-type-annotations
-> ```
+:::
 
-## Clang-format (C++ only)
+### Clang-format (C++ only)
 
 If you have C++ code, you should have a `.clang-format` file and use the
 following pre-commit config:
@@ -892,7 +878,7 @@ This will use 1-2 MB binary wheels from PyPI on all common platforms. You can
 generated such a file using
 `pipx run clang-format -style=llvm -dump-config > .clang-format`.
 
-## Shellcheck (shell scripts only)
+### Shellcheck (shell scripts only)
 
 If you have shell scripts, you can protect against common mistakes using
 [shellcheck](https://github.com/koalaman/shellcheck).
@@ -904,9 +890,9 @@ If you have shell scripts, you can protect against common mistakes using
     - id: shellcheck
 ```
 
-## Prettier
+### Prettier
 
-{% rr PC180 %} The [prettier](https://prettier.io) tool can format a large
+{rr}`PC180` The [prettier](https://prettier.io) tool can format a large
 number of different file types. An example of usage:
 
 ```yaml
@@ -933,7 +919,7 @@ be set to `"never"` or `"always"` to have prettier reflow text. You can turn off
 prettier for blocks with
 [comments depending on language](https://prettier.io/docs/en/ignore.html).
 
-## Schema validation
+### Schema validation
 
 There are two tools, both based on JSON Schema, that you can use to validate
 various configuration files. The first, [validate-pyproject][], validates your
@@ -941,7 +927,7 @@ various configuration files. The first, [validate-pyproject][], validates your
 (`build-system` and `project`), along with `tool.setuptools`. There are also
 plugins for some other tools, like `scikit-build-core` and `cibuildwheel`. You
 can even get all [SchemaStore][]'s plugins with the
-[validate-pyproject-schema-store][] plugin. Using it looks like this:
+validate-pyproject-schema-store plugin. Using it looks like this:
 
 ```yaml
 - repo: https://github.com/abravalheri/validate-pyproject
@@ -966,7 +952,7 @@ schemas, and you can load them via URL. It work on JSON, YAML, and TOML.
     - id: check-readthedocs
 ```
 
-## Pylint (noisy)
+### Pylint (noisy)
 
 Pylint is very opinionated, with a high signal-to-noise ratio. However, by
 limiting the default checks or by starting off a new project using them, you can
@@ -976,7 +962,7 @@ pre-commit, since it needs to have your package installed - it is less static of
 check than Ruff or Flake8. Here is a suggested `pyproject.toml` entry to get you
 started:
 
-```toml
+```ini
 [tool.pylint]
 py-version = "3.10"
 jobs = "0"
@@ -1005,26 +991,26 @@ And you can add this to your GitHub Actions using
 `run: pipx run nox -s pylint -- --output-format=github`. You can replace
 `<your package>` with the module name.
 
-## Jupyter notebook support
+### Jupyter notebook support
 
-### Ruff
+#### Ruff
 
 Ruff natively supports notebooks. You no longer need to enable it, it's on by
 default with Ruff 0.6+. If you want to control rules based on being notebooks,
 you can just match with `**.ipynb` like any other file.
 
-### Black
+#### Black
 
 For Black, just make sure you use the `id: black-jupyter` hook instead of
 `id: black`; that will also include notebooks.
 
-### NBQA
+#### NBQA
 
 You can adapt other tools to notebooks using
 [nbQA](https://github.com/nbQA-dev/nbQA). However, check to see if the tool
 natively supports notebooks first, several of them do now.
 
-### Stripping output
+#### Stripping output
 
 You also might like the following hook, which cleans Jupyter outputs:
 
@@ -1035,8 +1021,6 @@ You also might like the following hook, which cleans Jupyter outputs:
     - id: nbstripout
 ```
 
-<!-- prettier-ignore-start -->
-
 [flake8]: https://github.com/pycqa/flake8
 [pycln]: https://hadialqattan.github.io/pycln
 [validate-pyproject]: https://validate-pyproject.readthedocs.io
@@ -1047,7 +1031,3 @@ You also might like the following hook, which cleans Jupyter outputs:
 [typos-ref]: https://github.com/crate-ci/typos/blob/master/docs/reference.md
 [pre-commit]: https://pre-commit.com
 [prek]: https://prek.j178.dev
-
-<!-- prettier-ignore-end -->
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/guides/tasks.md b/docs/pages/guides/tasks.md
index 79eeaaac..482b6c20 100644
--- a/docs/pages/guides/tasks.md
+++ b/docs/pages/guides/tasks.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Task runners
-permalink: /guides/tasks/
-nav_order: 30
-parent: Topical Guides
 ---
 
-{% include toc.html %}
-
-# Task runners
+## Task runners
 
 <!-- [[[cog
 from cog_helpers import  code_fence, render_cookie, PyMatcher
@@ -45,7 +39,7 @@ temporary environment each time. And, if you pass `-R` when rerunning it, you
 can skip the setup and install steps, making it nearly as fast as directly
 running the commands!
 
-{% rr PY007 %} You _should_ use a task runner to make it easy and simple for new
+{rr}`PY007` You _should_ use a task runner to make it easy and simple for new
 contributors to run things. You _should_ use a task runner to make specialized
 developer tasks easy. You _should_ use a task runner to avoid making single-use
 virtual environments for docs and other rarely run tasks. Nox is recommended,
@@ -61,9 +55,9 @@ be best left to just specialized tasks.
 [rake]: https://ruby.github.io/rake/
 [make]: https://www.gnu.org/software/make/
 
-## Nox
+### Nox
 
-### Installing
+#### Installing
 
 Installing nox should be handled like any other Python _application_. You should
 either use a good package manager, like brew on macOS, or you should use pipx;
@@ -89,7 +83,7 @@ customize the versions of Python prepared for you, then use input like this:
     python-versions: "3.10, 3.11, 3.12, 3.13, 3.13t, 3.14, 3.14t, pypy-3.11"
 ```
 
-### Introduction
+#### Introduction
 
 Nox is a tool for running tasks, called "sessions", inside temporary virtual
 environments. It is configured through Python and is designed to resemble
@@ -122,16 +116,16 @@ as well.
 You can run this using:
 
 ```console
-$ nox -s tests
+nox -s tests
 ```
 
 You can see all defined sessions (along with the docstrings) using:
 
 ```console
-$ nox -l
+nox -l
 ```
 
-### Parametrizing
+#### Parametrizing
 
 You can parametrize sessions. either on Python or on any other item.
 
@@ -155,20 +149,20 @@ skipped. You can use a Docker container to run in an environment where all
 Python's (3.6+) are available:
 
 ```console
-$ docker run --rm -itv $PWD:/src -w /src quay.io/pypa/manylinux_2_28_x86_64:latest pipx run nox
+docker run --rm -itv $PWD:/src -w /src quay.io/pypa/manylinux_2_28_x86_64:latest pipx run nox
 ```
 
 Another container you can use is `thekevjames/nox:latest`; this has nox
 pre-installed (no pipx) and Python 2.7 and 3.5 as well.
 
-### Useful sessions
+#### Useful sessions
 
 Things like bumping the versions can be made sessions - since nox handles the
 environment for you, you can use any Python dependencies you like, and not have
 to worry about installing anything. Here are some commonly useful sessions that
 will likely look similar across different projects:
 
-#### Lint
+##### Lint
 
 Ideally, all developers should be using pre-commit or prek directly, but this
 helps new users.
@@ -177,7 +171,7 @@ helps new users.
 with code_fence("python"):
     print(noxfile.get_source("lint"))
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 @nox.session
 def lint(session: nox.Session) -> None:
@@ -189,16 +183,16 @@ def lint(session: nox.Session) -> None:
         "prek", "run", "--all-files", "--show-diff-on-failure", *session.posargs
     )
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
-#### Tests
+##### Tests
 
 <!-- [[[cog
 with code_fence("python"):
     print(noxfile.get_source("tests"))
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 @nox.session
 def tests(session: nox.Session) -> None:
@@ -209,16 +203,16 @@ def tests(session: nox.Session) -> None:
     session.install("-e.", *test_deps)
     session.run("pytest", *session.posargs)
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
-#### Docs
+##### Docs
 
 <!-- [[[cog
 with code_fence("python"):
     print(noxfile.get_source("docs"))
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 @nox.session(reuse_venv=True, default=False)
 def docs(session: nox.Session) -> None:
@@ -251,19 +245,19 @@ def docs(session: nox.Session) -> None:
     else:
         session.run("sphinx-build", "--keep-going", *shared_args)
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 This supports setting up a quick server as well, run like this:
 
 ```console
-$ nox -s docs -- --serve
+nox -s docs -- --serve
 ```
 
 Notice that we set `default=False` so that docs are not built every time nox is
-run without arguments. {% rr NOX103 %}
+run without arguments. {rr}`NOX103`
 
-#### Build (pure Python)
+##### Build (pure Python)
 
 For pure Python packages, this could be useful:
 
@@ -277,7 +271,7 @@ with code_fence("python"):
     print()
     print(noxfile.get_source("build"))
 ]]] -->
-<!-- prettier-ignore-start -->
+<!-- rumdl-disable MD013 -->
 ```python
 import shutil
 from pathlib import Path
@@ -298,17 +292,17 @@ def build(session: nox.Session) -> None:
     session.install("build")
     session.run("python", "-m", "build")
 ```
-<!-- prettier-ignore-end -->
+<!-- rumdl-enable MD013 -->
 <!-- [[[end]]] -->
 
 (Removing the build directory is helpful for setuptools)
 
-### Faster with uv
+#### Faster with uv
 
 The [uv](https://github.com/astral-sh/uv) project is a Rust reimplementation of
 pip, pip-tools, and venv that is very, very fast. You can tell nox to use `uv`
 if it is on your system by adding the following to your `noxfile.py`
-{% rr NOX102 %}:
+{rr}`NOX102`:
 
 ```python
 nox.needs_version = ">=2024.3.2"
@@ -326,9 +320,9 @@ Check your jobs with `uv`; most things do not need to change. The main
 difference is `uv` doesn't install `pip` unless you ask it to. If you want to
 interact with uv, nox might be getting uv from it's environment instead of the
 system environment, so you can install `uv` if `shutil.which("uv")` returns
-`None`. You should also set a minimum version of nox. {% rr NOX101 %}
+`None`. You should also set a minimum version of nox. {rr}`NOX101`
 
-### Running without nox or requiring dependencies
+#### Running without nox or requiring dependencies
 
 Nox also allows you to use the script block, both for running with runners (like
 `uv run` and `pipx run`), and for specifying dependencies to install or a
@@ -350,17 +344,17 @@ if __name__ == "__main__":
     nox.main()
 ```
 
-The script block then specifies that nox is required {% rr NOX201 %}. If you
+The script block then specifies that nox is required {rr}`NOX201`. If you
 want other dependencies here, those will also be installed before the file is
 run. Older versions of nox still need the `nox.needs_version` line to keep nice
 error messages.
 
-The first line is a shebang line {% rr NOX202 %}, which allows this file to be
+The first line is a shebang line {rr}`NOX202`, which allows this file to be
 run directly if it is made executable. You can put any runner here; uv is shown.
-You also need a main block {% rr NOX203 %} to allow nox to be run when this file
+You also need a main block {rr}`NOX203` to allow nox to be run when this file
 is executed directly.
 
-### Examples
+#### Examples
 
 A standard
 [powered by nox](https://github.com/scikit-hep/hist/blob/main/noxfile.py)
diff --git a/docs/pages/index.md b/docs/pages/index.md
index 7d9155ea..ad562dcb 100644
--- a/docs/pages/index.md
+++ b/docs/pages/index.md
@@ -1,11 +1,10 @@
 ---
-layout: home
 title: Home
-permalink: /
-nav_order: 0
+site:
+  hide_outline: true
 ---
 
-# Scientific Python Library Development Guide
+## Scientific Python Library Development Guide
 
 This guide is maintained by the scientific Python community for the benefit of
 fellow scientists and research software engineers.
@@ -14,42 +13,38 @@ fellow scientists and research software engineers.
 Jupyter notebooks that are becoming unwieldy? Are changes to some parts of your
 code accidentally breaking other parts of your code? Do you want to more
 maintainable, reusable, and shareable form? Start at the
-[tutorial]({% link pages/tutorials/index.md %}).
+[tutorial](pages/tutorials/index).
 
-**Learn recommended tools and best practices.** [Topical guides]({% link
-pages/guides/index.md %}) provide task-based instruction on topics that
-scientists and research software engineers may encounter as their projects
+**Learn recommended tools and best practices.**
+[Topical guides](pages/guides/index) provide task-based instruction on topics
+that scientists and research software engineers may encounter as their projects
 evolve and grow. This covers modern packaging ([simple][] or [compiled][]),
 [style checking][], [testing][], [documentation][], [static typing][], [CI][],
 and much more!
 
-{: .highlight-title }
+:::{tip} New project template
+This guide comes with a [copier][]/[cookiecutter][]/[cruft][] template for
+making new repos, [scientific-python/cookie][]. Nine build backends including
+compiled backends, generation tested in Nox, and kept in-sync with the guide.
+:::
 
-> New project template
->
-> This guide comes with a [copier][]/[cookiecutter][]/[cruft][] template for
-> making new repos, [scientific-python/cookie][]. Nine build backends including
-> compiled backends, generation tested in Nox, and kept in-sync with the guide.
-
-{: .important-title }
-
-> Checking an existing project
->
-> We provide [sp-repo-review][], a set of [repo-review][] checks for comparing
-> your repository with the guidelines, runnable [right in the guide][] via
-> WebAssembly! All checks point to a linked badge in the guide.
+:::{important} Checking an existing project
+We provide [sp-repo-review][], a set of [repo-review][] checks for comparing
+your repository with the guidelines, runnable [right in the guide][] via
+WebAssembly! All checks point to a linked badge in the guide.
+:::
 
 **Learn to write better research code.** A high-level document on
-[principles]({% link pages/principles/index.md %}) provides advice based on the
+[principles](pages/principles/index) provides advice based on the
 community's collective experience building code that is easier for researchers
 to use successfully and easier to maintain over time.
 
 **Use our solutions for common tasks.** A growing collection of
-[patterns]({% link pages/patterns/index.md %}) provides tested approaches for
+[patterns](pages/patterns/index) provides tested approaches for
 tasks and can be tricky to get exactly right, such as including data files with
 Python packages.
 
-## Related Resources
+### Related Resources
 
 This guide does _not_ cover the basics of Python itself or the scientific Python
 libraries; it focuses on making or maintaining a package. We recommend the
@@ -72,25 +67,22 @@ Other similar resources that cover Python packaging include:
 - [Intersect training: Packaging](https://intersect-training.org/packaging): A
   tutorial introducing Python packaging.
 
-{: .note-title }
-
-> History
->
-> This guide (along with cookie & repo-review) started in [Scikit-HEP][]
-> in 2020. It was merged with the [NSLS-II][] guidelines and moved to Scientific
-> Python at the [2023 Scientific Python Developer Summit][2023 spdev], along
-> with many updates. Improved support for compiled components supported in part
-> by NSF grant [OAC-2209877][].
-
-<!-- prettier-ignore-start -->
-[simple]:                   {% link pages/guides/packaging_simple.md %}
-[compiled]:                 {% link pages/guides/packaging_compiled.md %}
-[style checking]:           {% link pages/guides/style.md %}
-[testing]:                  {% link pages/guides/pytest.md %}
-[documentation]:            {% link pages/guides/docs.md %}
-[static typing]:            {% link pages/guides/mypy.md %}
-[ci]:                       {% link pages/guides/gha_pure.md %}
-[right in the guide]:       {% link pages/guides/repo_review.md %}
+:::{note} History
+This guide (along with cookie & repo-review) started in [Scikit-HEP][]
+in 2020. It was merged with the [NSLS-II][] guidelines and moved to Scientific
+Python at the [2023 Scientific Python Developer Summit][2023 spdev], along
+with many updates. Improved support for compiled components supported in part
+by NSF grant [OAC-2209877][].
+:::
+
+[simple]:                   pages/guides/packaging_simple
+[compiled]:                 pages/guides/packaging_compiled
+[style checking]:           pages/guides/style
+[testing]:                  pages/guides/pytest
+[documentation]:            pages/guides/docs
+[static typing]:            pages/guides/mypy
+[ci]:                       pages/guides/gha_pure
+[right in the guide]:       pages/guides/repo_review
 
 [scientific-python/cookie]: https://github.com/scientific-python/cookie
 [repo-review]:              https://repo-review.readthedocs.io
@@ -102,4 +94,3 @@ Other similar resources that cover Python packaging include:
 [OAC-2209877]:              https://www.nsf.gov/awardsearch/showAward?AWD_ID=2209877
 [nsls-ii]:                  https://nsls-ii.github.io
 [sp-repo-review]:           https://pypi.org/project/sp-repo-review
-<!-- prettier-ignore-end -->
diff --git a/docs/pages/patterns/backports.md b/docs/pages/patterns/backports.md
index e933c2e1..4630ded8 100644
--- a/docs/pages/patterns/backports.md
+++ b/docs/pages/patterns/backports.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Backports
-permalink: /patterns/backports/
-nav_order: 2
-parent: Patterns
 ---
 
-{% include toc.html %}
-
-# Backports
+## Backports
 
 A lot of additions to Python come with backports for older Pythons. Here are a
 few tips for using backports:
@@ -24,11 +18,11 @@ few tips for using backports:
 
 The rules for using a backport are as follows:
 
-## Conditional requirement
+### Conditional requirement
 
 Add it conditionally to your requirements. This looks something like this:
 
-```toml
+```ini
 [project]
 dependencies = [
     "importlib_metadata>=4.6; python_version<'3.10'",
@@ -37,7 +31,7 @@ dependencies = [
 ]
 ```
 
-## Conditional usage
+### Conditional usage
 
 Always use the backport conditionally, with the following idiom:
 
@@ -67,7 +61,7 @@ advantages:
   important fixes landed in 3.10.
 - It matches your conditional requirements.
 
-## Placement in a file
+### Placement in a file
 
 Placing all conditional backports in a common location is a nice practice.
 Here's a suggestion: Place all imports inside `src/<package>/_compat`, in the
@@ -103,7 +97,7 @@ Ruff needs to know if you are re-exporting `typing`/`typing_extensions`, so make
 sure you add `typing-modules = ["<package>._compat.typing"]` to Ruff's config in
 `pyproject.toml`.
 
-## Typing dependencies
+### Typing dependencies
 
 While it's not usually necessary, you can avoid the `typing_extensions` backport
 at runtime by protecting the imports with `typing.TYPE_CHECKING`.
@@ -112,7 +106,7 @@ there's a good chance one of your dependencies is already pulling it. But if you
 really, really want to keep dependencies minimal, you can do this in your typing
 backport re-export file.
 
-## Common backport packages
+### Common backport packages
 
 - `typing_extensions`: New features in `typing` are added here first.
 - `importlib_metadata`: Added as `importlib.metadata` in 3.8, important updates
diff --git a/docs/pages/patterns/data_files.md b/docs/pages/patterns/data_files.md
index 7db7ebfa..ddbff309 100644
--- a/docs/pages/patterns/data_files.md
+++ b/docs/pages/patterns/data_files.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Including data files
-permalink: /patterns/data-files/
-nav_order: 3
-parent: Patterns
 ---
 
-{% include toc.html %}
-
-# Including data files
+## Including data files
 
 In this section you will:
 
@@ -16,7 +10,7 @@ In this section you will:
 - Learn some alternative approaches.
 - Learn how to include small data files in your package.
 
-## Consider Alternatives
+### Consider Alternatives
 
 **Never include large binary files in your Python package or git repository.**
 Once committed, the file lives in git history forever. Git will become sluggish,
@@ -48,7 +42,7 @@ If the file in question is a text file and not very large (\< 100 kB) than it's
 reasonable to just bundle it with the package. If not, see the recommendation at
 the end.
 
-## How to Package Data Files
+### How to Package Data Files
 
 What's the problem we are solving here? If your Python program needs to access a
 data file, the naïve solution is just to hard-code the path to that file.
@@ -98,8 +92,7 @@ You'll want to make sure your Python building backend is placing these files in
 the SDist and wheel. If you are using anything other than setuptools, this
 should be automatic.
 
-{% details Setuptools-specific instructions %}
-
+:::{dropdown} Setuptools-specific instructions
 There are two ways to include data files in setuptools. You can either list the
 package data explicitly:
 
@@ -126,7 +119,7 @@ But then you'll need to _also_ make sure the files are in the SDist, too:
 include src/package/peak_spacings/*.txt
 ```
 
-{% enddetails %}
+:::
 
 Finally, wherever we actually use the files in our scientific code, we can
 access them using `importlib_resources`. For users with Python >= 3.9 the
@@ -149,7 +142,7 @@ with resources.as_file(ref) as path:
         spacings_txt = f.read()
 ```
 
-### Using the init
+#### Using the init
 
 Instead of having an empty init, you can instead move the `files(...)` into the
 `__init__.py`. That would look like this:
@@ -165,7 +158,7 @@ LaB6 = files / "LaB6.txt"
 Now, a user can simply import and use `package.peakspacing.LaB6` and such
 directly.
 
-## Downloading larger files on demand
+### Downloading larger files on demand
 
 A common use case is that a project may have example notebooks or demo scripts
 which require data not distributed with the project itself. One approach in
@@ -202,11 +195,8 @@ file_path = pooch.retrieve(
 On repeated runs of this command, the locally cached filename would be used
 instead of downloading the data again.
 
-<!-- prettier-ignore-start -->
-[importlib_resources]: https://importlib-resources.readthedocs.io/en/latest/
 [osf.io]: https://osf.io/
 [pooch]: https://www.fatiando.org/pooch/latest/
 [zenodo]: https://zenodo.org/
 [copier]: https://copier.readthedocs.io
 [cookiecutter]: https://cookiecutter.readthedocs.io
-<!-- prettier-ignore-end -->
diff --git a/docs/pages/patterns/exports.md b/docs/pages/patterns/exports.md
index 46bfbebd..3dc93717 100644
--- a/docs/pages/patterns/exports.md
+++ b/docs/pages/patterns/exports.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Exports
-permalink: /patterns/exports/
-nav_order: 1
-parent: Patterns
 ---
 
-{% include toc.html %}
-
-# Exports
+## Exports
 
 What objects in a module can you use? One common convention is that starting a
 name with a single underscore makes it "private" (though really "hidden" might
@@ -31,7 +25,7 @@ can cause surprising problems in some cases, though, due to Python's late
 binding. It's also easy to forget to delete something like an import, due to the
 fact the `del` statements are at the end of the module, far away from the usage.
 
-## Setting all
+### Setting all
 
 The solution to this is the `__all__` attribute. This is a public declaration of
 your exported API. It looks like this:
@@ -61,8 +55,7 @@ def __dir__() -> list[str]:
 This causes tab completion to only show your public API! You can still access
 everything in the module, it just won't be shown to the user.
 
-{: .warning }
-
+:::{warning}
 This `__dir__()` trick doesn't work very well on `__init__.py` modules, since
 ideally you want submodules to be shown if they have been imported. It's best to
 keep `__init__.py` modules minimal. It's tempting to import contents from your
@@ -70,7 +63,7 @@ submodules in `__init__.py`, but keep in mind importing any submodule always
 runs all parent `__init__.py`s, so you'll likely take an import performance hit
 and might have to deal with circular import issues in order to save a user a few
 keystrokes.
-
+:::
 There are some dynamic solutions to building your `__all__` variable without
 having to list all the items in a list near the top of your file. However, you
 lose several features doing so, such as the human readable list of module
diff --git a/docs/pages/patterns/index.md b/docs/pages/patterns/index.md
index 0c58e6f9..98a40cea 100644
--- a/docs/pages/patterns/index.md
+++ b/docs/pages/patterns/index.md
@@ -1,12 +1,8 @@
 ---
-layout: page
 title: Patterns
-permalink: /patterns/
-nav_order: 4
-has_children: true
 ---
 
-# Patterns
+## Patterns
 
 Patterns is a collection of common patterns in scientific software that are
 worth learning. These try to highlight best practices for specific situations,
@@ -18,8 +14,9 @@ If you would like to use backport packages, see [Backports][].
 
 If you are wondering about public API, see [Exports][].
 
-<!-- prettier-ignore-start -->
-[including data files]: {% link pages/patterns/data_files.md %}
-[backports]: {% link pages/patterns/backports.md %}
-[exports]: {% link pages/patterns/exports.md %}
-<!-- prettier-ignore-end -->
+[including data files]: pages/patterns/data_files
+[backports]: pages/patterns/backports
+[exports]: pages/patterns/exports
+
+```text {tableofcontents}
+```
diff --git a/docs/pages/principles/design.md b/docs/pages/principles/design.md
index 4ed51113..7b918b84 100644
--- a/docs/pages/principles/design.md
+++ b/docs/pages/principles/design.md
@@ -1,16 +1,10 @@
 ---
-layout: page
 title: Design recommendations
-permalink: /principles/design/
-nav_order: 2
-parent: Principles
 ---
 
-{% include toc.html %}
+## Design recommendations
 
-# Design recommendations
-
-## Keep I/O separate
+### Keep I/O separate
 
 One of the biggest impediments to reuse of scientific code is when I/O
 code---assuming certain file locations, names, formats, or layouts---is
@@ -22,7 +16,7 @@ The valuable scientific logic should be encoded in functions that take in
 standard data types and return standard data types. This makes them easier to
 test, maintain when data formats change, or reuse for unforeseen applications.
 
-## Duck typing is a good idea
+### Duck typing is a good idea
 
 [Duck typing][] treats objects based on what they can _do_, not based on what
 type they _are_. "If it walks like a duck and it quacks like a duck, then it
@@ -37,27 +31,27 @@ provides the right methods (interfaces). Where possible, avoid `isinstance`
 checks in your code, and try to make your functions work on the broadest
 possible range of input types.
 
-## Consider: can this just be a function?
+### Consider: can this just be a function?
 
 Not everything needs to be object-oriented. Object-oriented design needs to
 follow the same principles as other code, like modularity, and be well tested.
 If you can get away with writing functions processing existing datatypes like a
 DataFrame, do so.
 
-{: .highlight }
+:::{tip}
+It is better to have 100 functions operate on one data structure than 10
+functions on 10 data structures.
 
-> It is better to have 100 functions operate on one data structure than 10
-> functions on 10 data structures.
->
-> -- From ACM's SIGPLAN publication, (September, 1982), Article "Epigrams in
-> Programming", by Alan J. Perlis of Yale University.
+-- From ACM's SIGPLAN publication, (September, 1982), Article "Epigrams in
+Programming", by Alan J. Perlis of Yale University.
+:::
 
 A popular talk, ["Stop Writing Classes"][], illustrates how some situations that
 _seem_ to lend themselves to object-oriented programming are much more simply
 handled using functions. The biggest danger of reaching for OO design when it's
 not needed is the following: changing states.
 
-## Avoid changing state
+### Avoid changing state
 
 It is often tempting to invent a custom class to express a workflow, along these
 lines.
@@ -101,7 +95,7 @@ state that makes subsets of available operations (i.e. methods) invalid. Note
 that tab completion in this case would show exactly the allowed set of
 operations each time.
 
-## Consider: do I really want a custom class?
+### Consider: do I really want a custom class?
 
 Using built-in Python types (`int`, `float`, `str`) and standard scientific
 Python types like NumPy array and Pandas DataFrame makes code interoperable. It
@@ -130,7 +124,7 @@ class Data:
     count: int
 ```
 
-## Static typing is verbose, but makes code more readable
+### Static typing is verbose, but makes code more readable
 
 Code with static types has a lot of extra characters, but it provides more
 _information_ to the reader; `timestamp: int` or `timestamp: float` provides
@@ -148,7 +142,7 @@ When using static typing, duck typing is expressed via Protocols. These should
 be strongly preferred over older solutions like inheritance or ABCs if possible,
 as they trade a little extra code to remove dependencies between objects.
 
-## Permissiveness isn't always convenient
+### Permissiveness isn't always convenient
 
 Overly permissive code can lead to very confusing bugs. If you need a flexible
 user-facing interface that tries to "do the right thing" by guessing what the
@@ -168,20 +162,20 @@ what to do about it. _Application_ code (e.g. GUIs) should catch and handle
 errors to avoid crashing, but _library_ code should generally raise errors
 unless it is sure how the user or the caller wants to handle them.
 
-## Write useful error messages
+### Write useful error messages
 
 Be specific. Include what the wrong value was, what was wrong with it, and
 perhaps how it might be fixed. For example, if the code fails to locate a file
 it needs, it should say what it was looking for and where it looked.
 
-## Write for readability
+### Write for readability
 
 Unless you are writing a script that you plan to delete tomorrow or next week,
 your code will probably be read many more times than it is written. And today's
 "temporary solution" often becomes tomorrow's critical code. Therefore, optimize
 for clarity over brevity, using descriptive and consistent names.
 
-## Complexity is always conserved
+### Complexity is always conserved
 
 Complexity is always conserved and is strictly greater than the system the code
 is modeling. Attempts to hide complexity from the user frequently backfire.
@@ -263,10 +257,6 @@ Python is incredibly flexible. It accommodates many possible design choices. By
 exercising some restraint and consistency with the scientific Python ecosystem,
 Python can be used to build scientific tools that last and grow well over time.
 
-<!-- prettier-ignore-start -->
-
 [the UNIX philosophy]: https://en.wikipedia.org/wiki/Unix_philosophy
 [Duck typing]: https://en.wikipedia.org/wiki/Duck_typing
 ["Stop Writing Classes"]: https://youtube.com/watch?v=o9pEzgHorH0&t=193s
-
-<!-- prettier-ignore-end -->
diff --git a/docs/pages/principles/index.md b/docs/pages/principles/index.md
index 6fdc2f72..8462e405 100644
--- a/docs/pages/principles/index.md
+++ b/docs/pages/principles/index.md
@@ -1,22 +1,17 @@
 ---
-layout: page
 title: Principles
-permalink: /principles/
-nav_order: 3
-has_children: true
 ---
 
-# Principles
+## Principles
 
 These pages are focused on designing good software, with a focus on end-user
 research code. [Process recommendations][] discusses the process of writing
 software, and [Design recommendations][] covers some tips about writing easy to
 read and maintain code.
 
-<!-- prettier-ignore-start -->
+[Process recommendations]: pages/principles/process
+[Design recommendations]: pages/principles/design
 
-[Process recommendations]: {% link pages/principles/process.md %}
-[Design recommendations]: {% link pages/principles/design.md %}
 
-
-<!-- prettier-ignore-end -->
+```text {tableofcontents}
+```
diff --git a/docs/pages/principles/process.md b/docs/pages/principles/process.md
index f69be34f..be8c321c 100644
--- a/docs/pages/principles/process.md
+++ b/docs/pages/principles/process.md
@@ -1,16 +1,10 @@
 ---
-layout: page
 title: Process recommendations
-permalink: /principles/process/
-nav_order: 1
-parent: Principles
 ---
 
-{% include toc.html %}
+## Process recommendations
 
-# Process recommendations
-
-## Collaborate
+### Collaborate
 
 Software developed by several people is preferable to software developed by one.
 By adopting the conventions and tooling used by many other scientific software
@@ -33,7 +27,7 @@ If you can bring together contributors with diverse scientific backgrounds, it
 becomes easier to identify functionality that should be generalized for reuse by
 different fields.
 
-## Don't be afraid to refactor
+### Don't be afraid to refactor
 
 No code is ever right the first (or second) time.
 
@@ -41,7 +35,7 @@ Refactoring the code once you understand the problem and the design trade-offs
 more fully helps keep the code maintainable. Version control, tests, and linting
 are your safety net, empowering you to make changes with confidence.
 
-## Prefer "wide" over "deep"
+### Prefer "wide" over "deep"
 
 It should be possible to reuse pieces of software in a way not anticipated by
 the original author. That is, branching out from the initial use case should
diff --git a/docs/pages/principles/testing.md b/docs/pages/principles/testing.md
index 5f807841..c3e7d238 100644
--- a/docs/pages/principles/testing.md
+++ b/docs/pages/principles/testing.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Testing recommendations
-permalink: /principles/testing/
-nav_order: 2
-parent: Principles
 ---
 
-{% include toc.html %}
-
-# Testing recommendations
+## Testing recommendations
 
 In this guide, we will provide a roadmap and best-practices for creating test
 suites for python projects.
@@ -22,7 +16,7 @@ the Features that your project provides. Then we will cover
 [Project Level Integration tests](#project-level-integration-tests), which test
 that the various parts of your package work together, and work with the other
 packages it depends on. Finally we will cover the venrable
-[Unit Test](#unit-tests), which test the correctness of your code from a
+{ref}`Unit Test <unit-tests>`, which test the correctness of your code from a
 perspective internal to your codebase, tests individual units in isolation, and
 are optimized to run quickly and often.
 
@@ -31,7 +25,7 @@ project to a reliable and maintainable state. We will also discuss some more
 specialized and advanced types of test cases in our
 [Taxonomy of Test Cases](#additional-types-of-test-suites) section.
 
-## Advantages of Testing
+### Advantages of Testing
 
 - Trustworthy code: Well tested code, is code that you can trust to behave as
   expected.
@@ -45,7 +39,7 @@ specialized and advanced types of test cases in our
   their changes do not break existing features, or cause unexpected
   side-effects.
 
-## Any test case is better than none
+### Any test case is better than none
 
 When in doubt, write the test that makes sense at the time.
 
@@ -59,7 +53,7 @@ bogged down in the taxonomy of test types. As you write and use your test suite,
 the reason for classifying and sorting some types of tests into different test
 suites will become apparent.
 
-## As long as that test is correct...
+### As long as that test is correct
 
 It can be surprisingly easy to write a test that passes when it should fail,
 especially when using complicated mocks and fixtures. The best way to avoid this
@@ -73,12 +67,14 @@ the test-case to make sure it fails when the code is broken.
   is better to write many test cases for a single function or class, than one
   giant case.
 
-## Public Interface Tests
+(public-interface-tests)=
+
+### Public Interface Tests
 
 A good place to start writing tests is from the perspective of a user of your
 module or library, as described in the [Test
-Tutorial]({% link pages/tutorials/test.md %}), and [Testing with pytest
-guide]({% link pages/guides/pytest.md %}). These tests follow the "Detroit
+Tutorial](pages/tutorials/test), and [Testing with pytest
+guide](pages/guides/pytest). These tests follow the "Detroit
 School", focusing on behavior, avoiding testing of private attributes,
 minimizing the use of mocks/patches/test-doubles.
 
@@ -90,16 +86,14 @@ minimizing the use of mocks/patches/test-doubles.
   (edge-case and exhaustive input testing will be handled in a separate test
   suite)
 
-{: .highlight-title }
-
-> A note to new test developers:
->
-> This is a good place to pause and go write some tests. The rest of these
-> principles apply to more advanced test development. As you gain experience and
-> your test suite(s) grow, taxonomy of test cases, the and the use/need for
-> different kinds of tests will become more clear.
+:::{tip} A note to new test developers:
+This is a good place to pause and go write some tests. The rest of these
+principles apply to more advanced test development. As you gain experience and
+your test suite(s) grow, taxonomy of test cases, the and the use/need for
+different kinds of tests will become more clear.
+:::
 
-## Test Suites
+### Test Suites
 
 Not all test cases are the same. In the following sections we will discuss many
 kinds of tests, which serve different purposes and provide different benefits.
@@ -107,13 +101,13 @@ Tests should be divided up into different Suites, which can be run independently
 of one another.
 
 Tests which "Fail Fast" save both developer and compute time. Some tests are by
-necessity very slow. [Unit Tests](#unit-tests) should run extremely quickly in
-just a few seconds at most, while [end-to-end](#end-to-end-tests) require time
-to set up and may depend on slow and unreliable external services. By organizing
-tests into suites based on execution time, you can run fast suites first and
-stop if an error is encountered before running slower suites.
+necessity very slow. {ref}`Unit Tests <unit-tests>` should run extremely quickly
+in just a few seconds at most, while [end-to-end](#end-to-end-tests) require
+time to set up and may depend on slow and unreliable external services. By
+organizing tests into suites based on execution time, you can run fast suites
+first and stop if an error is encountered before running slower suites.
 
-### Advantages of Test Suites
+#### Advantages of Test Suites
 
 - Developers can run relevant tests quickly and frequently.
 - Tests can 'Fail Fast', while still reporting all failures within that suite.
@@ -122,7 +116,7 @@ stop if an error is encountered before running slower suites.
 - We can avoid false positives, by not running tests we expect to fail due to
   external factors.
 
-### Guidelines for Test Suites
+#### Guidelines for Test Suites
 
 - Organize test cases into suites based on the type of test and execution time.
 - Set up test-runners (Make, shell scripts, CI/CD) to run fast suites first, and
@@ -130,12 +124,12 @@ stop if an error is encountered before running slower suites.
 - Use markers to enable developers to run the sub-sets of test which are most
   relevant to their work, with minimal time spent waiting.
 
-### Creating Test Suites
+#### Creating Test Suites
 
 The simplest way to start, is separating tests into directories inside of the
 `tests/` directory:
 
-```
+```text
 tests/
     |- unit/
     |- integration/
@@ -152,7 +146,7 @@ conceptually part of a larger suite, and skip them when needed.
 
 First, define a new marker in `pyproject.toml`:
 
-```toml
+```ini
 [tool.pytest]
 markers = [
     "unit: marks unit tests",
@@ -184,7 +178,9 @@ def pytest_collection_modifyitems(session, config, items):
         item.add_marker(pytest.mark.unit)
 ```
 
-## Project Level Integration Tests
+(project-level-integration-tests)=
+
+### Project Level Integration Tests
 
 The term "Integration Test" is unfortunately overloaded, and used to describe
 testing that various components integrate with each other, at many levels of the
@@ -204,7 +200,9 @@ more extensive validation.
 
 The intended audience for these tests is developers working on the project.
 
-## Unit Tests
+(unit-tests)=
+
+### Unit Tests
 
 Unit tests loosely follow the "London School" of testing, where the smallest
 unit of code is tested in isolation.
@@ -217,7 +215,7 @@ function, an attribute of an object, a method or property of a class.
 They test only the code in the project, not code imported from other projects
 (or even other modules within the same project).
 
-### Advantages of unit testing
+#### Advantages of unit testing
 
 Unit tests ensure that the code, as written, is correct, and executes properly.
 They communicate the intention of the creator of the code, how the code is
@@ -239,7 +237,7 @@ better design decisions:
   understand and maintain. Refactoring code to make it easier to test often
   leads us to write better code overall.
 
-### When to write unit tests
+#### When to write unit tests
 
 - When your project matures enough to justify the work! Higher-level testing is
   often sufficient for small projects which are not part of critical
@@ -259,7 +257,7 @@ better design decisions:
 Not all projects need full unit test coverage, some may not need unit tests at
 all.
 
-### Guidelines for unit testing
+#### Guidelines for unit testing
 
 - Unit tests live alongside the code they test, in a /tests folder. They should
   be in a different directory than higher-level tests (integration, e2e,
@@ -288,7 +286,7 @@ all.
   between units, and will correctly tell you which part is failing if one
   breaks.
 
-#### Importing in test files
+##### Importing in test files
 
 Keep things local! Prefer to import only from the file-under-test when possible.
 This helps keep the context of the unit tests focused on the file-under-test.
@@ -391,7 +389,7 @@ from bettermath import superfast_numeric_sum as numeric_sum
 total = numeric_sum(some_numeric_values)
 ```
 
-#### Running unit tests
+##### Running unit tests
 
 We recommend using Pytest for running tests in your development environments. To
 run unit tests in your source folder, from your package root, use
@@ -399,12 +397,12 @@ run unit tests in your source folder, from your package root, use
 your source repository), use `pytest --pyargs {package name}`.
 
 You can set the default test path in `pyproject.toml`, see: [Configuring
-pytest]({% link pages/guides/pytest.md %}#configuring-pytest)
+pytest](pages/guides/pytest#configuring-pytest)
 
 We recommend configuring pytest to run ONLY your fastest, least demanding test
 suite by default.
 
-#### Mocking and Patching to Isolate the code under test
+##### Mocking and Patching to Isolate the code under test
 
 When the unit you are testing touches any external unit (usually something you
 imported, or another unit that has its own tests), the external unit should be
@@ -482,7 +480,7 @@ def test_pytest(mocker):
     dangerous_sideffects()
 ```
 
-## Extensive Input Testing
+### Extensive Input Testing
 
 The range of inputs that test cases validate is an important decision.
 
@@ -503,7 +501,7 @@ readable), and technical (complex, extensive) test files.
 - [Fuzz Tests](#fuzz-tests) are the best place to handle extensive and
   exhaustive input testing.
 
-### In Public Interface Tests
+#### In Public Interface Tests
 
 These are the most appropriate place to test certain invalid inputs and
 dependencies. Public Interface tests act like a contract with users; each
@@ -512,14 +510,14 @@ that it will not change without warning (and probably a major version bump). So
 any input/output and side-effects included in these tests should be considered
 _officially supported behavior_ and given careful consideration.
 
-### In project level integration tests
+#### In project level integration tests
 
 These are a good place to handle more extensive input testing. Integration tests
 already tend to be more verbose, with a lot of setup and teardown, and much more
 behavior to cover than other kinds of tests. These are the kinds of tests that
 should focus on edgecases.
 
-### In Unit Tests
+#### In Unit Tests
 
 Unit Tests should focus on the "happy-path" of execution. In most cases one
 representative example of the _expected_ input is sufficient. The test case
@@ -547,7 +545,9 @@ def bar(x):
     return x + 1
 ```
 
-## Additional Types of Test Suites
+(additional-types-of-test-suites)=
+
+### Additional Types of Test Suites
 
 A non-exhaustive discussion of some common types of tests.
 
@@ -556,7 +556,7 @@ Dont Panic!
 Depending on your project, you may not need many, or most of these kinds of
 tests.
 
-### Behavioral, Feature, or Functional Tests
+#### Behavioral, Feature, or Functional Tests
 
 High-level tests, which ensure a specific feature works. These are placed in a
 location like 'project_root/tests/behavioral/'. Used for testing things like:
@@ -565,7 +565,9 @@ location like 'project_root/tests/behavioral/'. Used for testing things like:
 - Setting a debug flag results in debug messages being printed
 - A configuration option affects the behavior of the code as expected
 
-### Fuzz Tests
+(fuzz-tests)=
+
+#### Fuzz Tests
 
 Fuzz tests attempt to test the full range of possible inputs to a function. They
 are good for finding edge-cases, where what should be valid input causes a
@@ -577,7 +579,7 @@ excellent tool for this, and a lot of fun to use.
   [see: fail fast](https://en.wikipedia.org/wiki/Fail-fast_system)
 - Reserve fuzz testing for the few critical functions, where it really matters.
 
-### Integration Tests
+#### Integration Tests
 
 The word "Integration" is a bit overloaded, and can refer to many levels of
 interaction between your code, its dependencies, and external systems.
@@ -598,7 +600,9 @@ interaction between your code, its dependencies, and external systems.
     - Interactions with other services, on local or cloud-based platforms
     - Micro-service, Database, or API connections and interactions
 
-### End to End Tests
+(end-to-end-tests)=
+
+#### End to End Tests
 
 The slowest, and most brittle, of all tests. Here, you set up an entire
 production-like system, and run tests against it. Some examples are:
@@ -610,7 +614,7 @@ production-like system, and run tests against it. Some examples are:
 - Processing data from a pre-loaded test database
 - Manual QA testing
 
-### Fuzz Tests and other slow tests
+#### Fuzz Tests and other slow tests
 
 Testing random input, using tools like Hypothesis, is similar to testing edge
 cases, but running these tests can take a very long time, and they can often be
@@ -623,7 +627,7 @@ much more complex and difficult to read for new developers.
 - These can take an arbitrarily long time to run, and you will need to set
   reasonable limits for your project.
 
-## Diagnostic Tests
+### Diagnostic Tests
 
 Diagnostic tests are used to verify the installation of a package. They should
 be runnable on production systems, like when we need to ssh into a live server
@@ -642,14 +646,14 @@ a full system check of the package. Good diagnostic tests:
 - Run quickly: select tests that can be run in a few moments
 - Provide meaningful feedback
 
-### Advantages of Diagnostic Tests
+#### Advantages of Diagnostic Tests
 
 - Diagnostic tests allow us to verify an installation of a package.
 - They can be used to verify system-level dependencies like:
   - Compiled binary dependencies
   - Access to specific hardware, like GPUs
 
-### Guidelines for Diagnostic Tests
+#### Guidelines for Diagnostic Tests
 
 - Consider using the stdlib `unittest.TestCase` and other stdlib tools instead
   of pytest. To allow running unit tests for diagnostics in production
@@ -658,7 +662,7 @@ a full system check of the package. Good diagnostic tests:
 - Test files should be named `test_<file under test>.py`, so that stdlib
   unittest can find them easily.
 
-### Mocking and Patching to Isolate the code under test
+#### Mocking and Patching to Isolate the code under test
 
 Test Isolation is less necessary in diagnostic tests than unit tests. We often
 want diagnostic tests to execute compiled code, or run a test on GPU hardware.
@@ -678,7 +682,7 @@ def test_myfunction(t, patchme: Mock):
     t.assertIs(ret, patchme.return_value)
 ```
 
-### Running Diagnostic Tests
+#### Running Diagnostic Tests
 
 stdlib's unittest can be used in environments where pytest is not available:
 
@@ -686,4 +690,5 @@ stdlib's unittest can be used in environments where pytest is not available:
   repository), use `python -m unittest discover -s <module.name>`
 - To use unittest to run tests in your source folder, from your package root,
   use
-  `python -m unittest discover --start-folder <source folder> --top-level-directory .`
+  `python -m unittest discover --start-folder <source folder> \
+  --top-level-directory .`
diff --git a/docs/pages/tutorials/dev-environment.md b/docs/pages/tutorials/dev-environment.md
index 782360e6..e04f3b78 100644
--- a/docs/pages/tutorials/dev-environment.md
+++ b/docs/pages/tutorials/dev-environment.md
@@ -1,21 +1,15 @@
 ---
-layout: page
 title: Intro to development
-permalink: /tutorials/dev-environment/
-nav_order: 1
-parent: Tutorials
 ---
 
-{% include toc.html %}
-
-# Intro to development
+## Intro to development
 
 In this section you will:
 
 - Create an isolated software area ("virtual environment") to work in.
 - Open a code editor.
 
-## Development environment
+### Development environment
 
 If you want to work on Python software, you should _always_ have a virtual
 environment, an area to install the software that is isolated from other
@@ -33,7 +27,7 @@ There are many (arguably _too_ many) ways to do this in Python. Any modern tool
 should be fine, but here we recommend two options popular in the scientific
 Python community. If you already use a different way, that's fine, use that.
 
-### Option 1: Using pip
+#### Option 1: Using pip
 
 The most basic option is to use `venv`, which comes by default with Python.
 
@@ -49,19 +43,22 @@ environment.
 
 To activate the virtual environment, type:
 
-{% tabs %} {% tab unix Linux/macOS %}
+::::{tab-set}
+:::{tab-item} Linux/macOS
 
 ```bash
 . .venv/bin/activate
 ```
 
-{% endtab %} {% tab windows Windows %}
+:::
+:::{tab-item} Windows
 
 ```bat
 .venv\bin\Activate.bat
 ```
 
-{% endtab %} {% endtabs %}
+:::
+::::
 
 You need to do this step every time you open a new shell (i.e. Terminal, Command
 Prompt) to work on your project. The `.` is short for `source`, which runs the
@@ -72,37 +69,31 @@ of text to your prompt so you don't forget that you are in an environment.
 The activation script installs a function `deactivate`; type that at any time to
 leave the environment (or just close your shell).
 
-{: .note-title }
-
-> Optional Alternative
->
-> Alternatively, you can use the `virtualenv` package, which has the same syntax
-> as `venv` and is a little faster. Unlike `venv`, it is not built in to Python;
-> it has to be installed as `pip install virtualenv`.
-
-{: .highlight-title }
+:::{note} Optional Alternative
+Alternatively, you can use the `virtualenv` package, which has the same syntax
+as `venv` and is a little faster. Unlike `venv`, it is not built in to Python;
+it has to be installed as `pip install virtualenv`.
+:::
 
-> For Advanced Users Using Custom Shells
->
-> If you like a different shell, like fish, there are several `activate`
-> scripts; the default one expects a bash-like shell.
+:::{tip} For Advanced Users Using Custom Shells
+If you like a different shell, like fish, there are several `activate`
+scripts; the default one expects a bash-like shell.
+:::
 
-{: .note-title }
+:::{note} Fast alternative
+You can also consider the [uv][] package, which is much, much faster version
+of pip and venv implemented in Rust. Just put `uv` in front of the commands
+you'd normally use; as long as you use venvs, it should be nearly the same.
+You can use `--system` to mimic pip, otherwise it uses the active virtualenv
+or a `.venv` folder. `uv venv` will default to a `.venv` folder.
 
-> Fast alternative
->
-> You can also consider the [uv][] package, which is much, much faster version
-> of pip and venv implemented in Rust. Just put `uv` in front of the commands
-> you'd normally use; as long as you use venvs, it should be nearly the same.
-> You can use `--system` to mimic pip, otherwise it uses the active virtualenv
-> or a `.venv` folder. `uv venv` will default to a `.venv` folder.
->
-> This also supports `--exclude-newer DATE`, which allows you to resolve as if
-> you were at some past point in time.
+This also supports `--exclude-newer DATE`, which allows you to resolve as if
+you were at some past point in time.
+:::
 
 [uv]: https://github.com/astral-sh/uv
 
-### Option 2: Using conda
+#### Option 2: Using conda
 
 You can also develop in conda. This is an especially good option if:
 
@@ -138,7 +129,7 @@ To deactivate, use `conda deactivate`, or leave your shell.
 
 [pixi]: https://pixi.sh
 
-## Choosing an Editor
+### Choosing an Editor
 
 Any plain text editor will serve our purposes for this guide. Bare bones editors
 like Notepad or `nano` will do the job. More feature-rich Integrated Development
@@ -156,5 +147,3 @@ setup time quite quickly when developing.
 [visual studio code]: https://code.visualstudio.com/
 [`vim`]: https://www.vim.org/
 [`emacs`]: https://www.gnu.org/software/emacs/
-
-<script src="{% link assets/js/tabs.js %}"></script>
diff --git a/docs/pages/tutorials/docs.md b/docs/pages/tutorials/docs.md
index e6c78049..b9372095 100644
--- a/docs/pages/tutorials/docs.md
+++ b/docs/pages/tutorials/docs.md
@@ -1,16 +1,10 @@
 ---
-layout: page
 title: Writing documentation
-permalink: /tutorials/docs/
-nav_order: 5
-parent: Tutorials
 ---
 
-{% include toc.html %}
+## Writing documentation
 
-# Writing documentation
-
-## Build the documentation
+### Build the documentation
 
 Scientific Python software documentation can be written in the Markdown syntax,
 which looks like this:
@@ -101,7 +95,7 @@ You should see some log message ending in `build succeeded.` This created the
 directory `docs/build`. Open `docs/build/index.html` in your web browser to view
 the documentation.
 
-## Essential Features of MyST Markdown
+### Essential Features of MyST Markdown
 
 We refer you to the [MyST][] documentation for topics including:
 
@@ -112,7 +106,7 @@ We refer you to the [MyST][] documentation for topics including:
 - Math and equations
 - Including content from other files
 
-## Structure
+### Structure
 
 We began with this structure, having a single documentation page.
 
@@ -142,7 +136,7 @@ We can link them from the front page by using the MyST Markdown `{toctree}`
 directive.
 
 ````markdown
-```{toctree}
+```text {toctree}
 tutorials/installation.md
 tutorials/first-steps.md
 tutorials/real-application.md
@@ -151,7 +145,7 @@ tutorials/real-application.md
 
 For more details see the MyST documentation page on [organizing content][].
 
-## Automatically generate reference documentation
+### Automatically generate reference documentation
 
 Reference documentation provides comprehensive documentation of the API: all the
 inputs and outputs of every public object in the codebase. This should not be
@@ -181,7 +175,7 @@ install.)
 You can document a single object (e.g. function), shown inline on the page
 
 ````markdown
-```{eval-rst}
+```text {eval-rst}
 .. autofunction:: example.refraction.snell
     :noindex:
     :toctree: generated
@@ -191,7 +185,7 @@ You can document a single object (e.g. function), shown inline on the page
 Or you can generate a table that links out to documentation for each object.
 
 ````markdown
-```{eval-rst}
+```text {eval-rst}
 .. autosummary::
     :nosignatures:
     :toctree: generated
@@ -200,16 +194,13 @@ Or you can generate a table that links out to documentation for each object.
 ```
 ````
 
-See the [guide]({% link pages/guides/docs.md %}) for more information on how to
+See the [guide](pages/guides/docs) for more information on how to
 integrate this into a package, and setup for nox.
 
-<!-- prettier-ignore-start -->
-[diátaxis]: https://diataxis.fr/
 [sphinx]: https://www.sphinx-doc.org/
 [myst]: https://myst-parser.readthedocs.io/
 [organizing content]: https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html
 [sphinx-autodoc2]: https://sphinx-autodoc2.readthedocs.io/
 [mkdocs]: https://www.mkdocs.org/
 [mkdocs-material]: https://squidfunk.github.io/mkdocs-material/
-[documentation guide]: {% link pages/guides/docs.md %}
-<!-- prettier-ignore-end -->
+[documentation guide]: pages/guides/docs
diff --git a/docs/pages/tutorials/index.md b/docs/pages/tutorials/index.md
index 408f6a6c..a4da2d7c 100644
--- a/docs/pages/tutorials/index.md
+++ b/docs/pages/tutorials/index.md
@@ -1,12 +1,8 @@
 ---
-layout: page
 title: Tutorials
-permalink: /tutorials/
-nav_order: 1
-has_children: true
 ---
 
-# Tutorials
+## Tutorials
 
 Do you have a pile of scientific Python scripts or Jupyter notebooks that are
 becoming unwieldy? Are changes to some parts of your code accidentally breaking
@@ -20,6 +16,9 @@ start off on the right foot.
 Keeping in mind that too much software infrastructure can be overwhelming to
 those who haven't yet encountered the need for it, we introduce only the core
 essentials in this opinionated tutorial. From there, we recommend looking
-through the section on [principles]({% link pages/principles/index.md %}). As
+through the section on [principles](pages/principles/index). As
 your project grows you may find some good use for the more specific and advanced
-topics covered in the [guides]({% link pages/guides/index.md %}).
+topics covered in the [guides](pages/guides/index).
+
+```text {tableofcontents}
+```
diff --git a/docs/pages/tutorials/module.md b/docs/pages/tutorials/module.md
index ef5df9d4..e9a7fbb1 100644
--- a/docs/pages/tutorials/module.md
+++ b/docs/pages/tutorials/module.md
@@ -1,21 +1,15 @@
 ---
-layout: page
 title: Inline documentation
-permalink: /tutorials/module/
-nav_order: 2
-parent: Tutorials
 ---
 
-{% include toc.html %}
-
-# Inline documentation
+## Inline documentation
 
 In this section you will:
 
 - Place some code in a module.
 - Provide inline documentation (a "docstring").
 
-## Module
+### Module
 
 As a concrete example, let's suppose we have a simple function that encodes
 [Snell's Law][]. Perhaps this function currently lives in a Jupyter notebook or
@@ -74,7 +68,7 @@ automatically generate nice-looking HTML documentation later. Notable features:
 
 - There is a section listing input parameters, with the structure
 
-  ```
+  ```text
   parameter_name : parameter_type
       optional description
   ```
@@ -89,7 +83,7 @@ automatically generate nice-looking HTML documentation later. Notable features:
 - (Optional) There is a section of one or more examples.
 
 We will revisit docstrings in the section on writing
-[documentation]({% link pages/tutorials/docs.md %}).
+[documentation](pages/tutorials/docs).
 
 [snell's law]: https://en.wikipedia.org/wiki/Snell%27s_law
 [numpydoc standard]: https://numpydoc.readthedocs.io/en/latest/format.html
diff --git a/docs/pages/tutorials/packaging.md b/docs/pages/tutorials/packaging.md
index 9b268692..ddd7f1f3 100644
--- a/docs/pages/tutorials/packaging.md
+++ b/docs/pages/tutorials/packaging.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Packaging
-permalink: /tutorials/packaging/
-nav_order: 3
-parent: Tutorials
 ---
 
-{% include toc.html %}
-
-# Packaging
+## Packaging
 
 In the section you will:
 
@@ -18,7 +12,7 @@ In the section you will:
 
 For more about packaging, see our [packaging guide][].
 
-## Create a minimal installable Python package
+### Create a minimal installable Python package
 
 Let’s create a Python package that contains this function.
 
@@ -96,13 +90,13 @@ At this point, your package's file structure will look like
 │       └── refraction.py
 ```
 
-## Install and use your package
+### Install and use your package
 
 Now that your package has the necessary elements, you can install it into your
 virtual environment (which should already be active). From the top level of your
 project’s directory, enter
 
-```
+```bash
 pip install -e .
 ```
 
@@ -134,9 +128,5 @@ In [1]: snell?
 
 For more about packaging, also see our [packaging guide][].
 
-<!-- prettier-ignore-start -->
-
 [version control with git]: https://swcarpentry.github.io/git-novice/
-[packaging guide]: {% link pages/guides/packaging_simple.md %}
-
-<!-- prettier-ignore-end -->
+[packaging guide]: pages/guides/packaging_simple
diff --git a/docs/pages/tutorials/test.md b/docs/pages/tutorials/test.md
index 828b1d86..0f8d287f 100644
--- a/docs/pages/tutorials/test.md
+++ b/docs/pages/tutorials/test.md
@@ -1,14 +1,8 @@
 ---
-layout: page
 title: Test
-permalink: /tutorials/test/
-nav_order: 4
-parent: Tutorials
 ---
 
-{% include toc.html %}
-
-# Test
+## Test
 
 In this section you will:
 
@@ -22,7 +16,7 @@ unintended changes or breakage with not go unnoticed. Writing tests also tends
 to encouraging you to write modular, reusable code, because it is easier to
 test.
 
-## Write some tests
+### Write some tests
 
 Make a directory for tests. We recommend putting it next to the `src` directory.
 
@@ -101,7 +95,7 @@ Things to notice:
   be using below.) This allows you to also write helper functions that are not
   tests.
 
-## Run the tests
+### Run the tests
 
 Scientific Python packages generally use a program called `pytest` to run their
 tests and report successes and failures. Install `pytest`.
@@ -149,9 +143,5 @@ include:
 Consult the [pytest documentation][] for more. For more advanced pytest
 suggestions, see our [pytest guide][].
 
-<!-- prettier-ignore-start -->
-
 [pytest documentation]: https://docs.pytest.org/en/latest/
-[pytest guide]: {% link pages/guides/pytest.md %}
-
-<!-- prettier-ignore-end -->
+[pytest guide]: pages/guides/pytest
diff --git a/docs/rr-role.mjs b/docs/rr-role.mjs
new file mode 100644
index 00000000..3462b9eb
--- /dev/null
+++ b/docs/rr-role.mjs
@@ -0,0 +1,27 @@
+/**
+ * MyST plugin: {rr} inline role
+ *
+ * Renders a repo-review check badge:
+ *   {rr}`PP007`  →  <span class="rr-btn" id="PP007">PP007</span>
+ *
+ * The .rr-btn CSS is in assets/css/site.css.
+ */
+
+const rrRole = {
+  name: "rr",
+  body: {
+    type: String,
+    required: true,
+  },
+  run(data) {
+    const code = data.body;
+    return [
+      {
+        type: "html",
+        value: `<span class="rr-btn">${code}</span>`,
+      },
+    ];
+  },
+};
+
+export default { roles: [rrRole] };
diff --git a/helpers/cog_helpers.py b/helpers/cog_helpers.py
index 765229f1..84caa1d9 100644
--- a/helpers/cog_helpers.py
+++ b/helpers/cog_helpers.py
@@ -84,9 +84,12 @@ def __contains__(self, dotted_name: str, /) -> bool:
 
 @contextlib.contextmanager
 def code_fence(lang: str, /, *, width: int = 3) -> Generator[None, None, None]:
+    # Fixed in https://github.com/jupyter-book/myst-theme/pull/883
+    if lang == "toml":
+        lang = "ini"
     tics = "`" * width
-    print("<!-- prettier-ignore-start -->")  # noqa: T201
+    print("<!-- rumdl-disable MD013 -->")  # noqa: T201
     print(f"{tics}{lang}")  # noqa: T201
     yield
     print(tics)  # noqa: T201
-    print("<!-- prettier-ignore-end -->")  # noqa: T201
+    print("<!-- rumdl-enable MD013 -->")  # noqa: T201
diff --git a/helpers/fetch_repo_review_app.sh b/helpers/fetch_repo_review_app.sh
deleted file mode 100755
index 76ca352a..00000000
--- a/helpers/fetch_repo_review_app.sh
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-version="${1:-v1.0.3}"
-archive_url="https://github.com/scientific-python/repo-review/releases/download/${version}/repo-review-app.zip"
-dest_dir="docs/assets/js"
-tmp_zip="$(mktemp)"
-
-trap 'rm -f "$tmp_zip"' EXIT
-
-mkdir -p "$dest_dir"
-curl -fsSL "$archive_url" -o "$tmp_zip"
-unzip -o -j "$tmp_zip" repo-review-app.min.js repo-review-app.min.js.map -d "$dest_dir" >/dev/null
diff --git a/package.json b/package.json
new file mode 100644
index 00000000..143e6875
--- /dev/null
+++ b/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "scientific-python-cookie-docs",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "cd docs && NODE_OPTIONS='--localstorage-file=_build/.node-localstorage --no-deprecation' myst build --html",
+    "serve": "cd docs && NODE_OPTIONS='--localstorage-file=_build/.node-localstorage --no-deprecation' myst start",
+    "clean": "rm -rf docs/_build"
+  },
+  "dependencies": {
+    "mystmd": "^1.0"
+  }
+}
diff --git a/pyproject.toml b/pyproject.toml
index d2956232..9fd7904a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -209,3 +209,14 @@ RTD103 = "Using Ruby instead of Python for docs"
 nd = "nd"
 sur = "sur"
 CPY = "CPY"
+
+[tool.rumdl]
+global.flavor = "myst"
+global.disable = [
+  "MD031",  # No blank line after fenced code block
+  "MD057",  # Relative links are MyST references, not file paths
+  "MD059",  # Link text should be descriptive
+]
+MD013.reflow = true
+MD013.code-blocks = false
+MD013.tables = false
diff --git a/src/sp_repo_review/checks/mypy.py b/src/sp_repo_review/checks/mypy.py
index e51d0b72..40d87fa2 100644
--- a/src/sp_repo_review/checks/mypy.py
+++ b/src/sp_repo_review/checks/mypy.py
@@ -45,7 +45,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         your settings already, ignore this check or set `strict = false`
         explicitly.
 
-        ```toml
+        ```ini
         [tool.mypy]
         strict = true
         ```
@@ -91,7 +91,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         static checks), so it's okay to set it to false if you need to. But try
         it first - it can catch real bugs too.
 
-        ```toml
+        ```ini
         [tool.mypy]
         warn_unreachable = true
         ```
@@ -117,7 +117,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         will force all skips in your project to include the error code, which
         makes them more readable, and avoids skipping something unintended.
 
-        ```toml
+        ```ini
         [tool.mypy]
         enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
         ```
@@ -142,7 +142,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         Must have `"redundant-expr"` in `enable_error_code = [...]`. This helps
         catch useless lines of code, like checking the same condition twice.
 
-        ```toml
+        ```ini
         [tool.mypy]
         enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
         ```
@@ -167,7 +167,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         Must have `"truthy-bool"` in `enable_error_code = []`. This catches
         mistakes in using a value as truthy if it cannot be falsy.
 
-        ```toml
+        ```ini
         [tool.mypy]
         enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
         ```
diff --git a/src/sp_repo_review/checks/noxfile.py b/src/sp_repo_review/checks/noxfile.py
index 011a50ee..23b541d8 100644
--- a/src/sp_repo_review/checks/noxfile.py
+++ b/src/sp_repo_review/checks/noxfile.py
@@ -179,7 +179,7 @@ def check(noxfile: Noxfile | None) -> bool | None:
         """
         You should have a script block with nox in it, for example:
 
-        ```toml
+        ```ini
         # /// script
         # dependencies = ["nox"]
         # ///
diff --git a/src/sp_repo_review/checks/pyproject.py b/src/sp_repo_review/checks/pyproject.py
index 92182039..5f9ecc79 100644
--- a/src/sp_repo_review/checks/pyproject.py
+++ b/src/sp_repo_review/checks/pyproject.py
@@ -170,7 +170,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         These are better than the old `extras` system for tests, docs, and other
         dependencies that are not needed for PyPI installs.
 
-        ```toml
+        ```ini
         [dependency-groups]
         dev = [ {{ include-group = "test" }} ]
         test = [ "pytest" ]
@@ -215,7 +215,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         support `pyproject.toml` ini configuration) or 9 (first version to
         support native configuration and toml config files).
 
-        ```toml
+        ```ini
         # Old pytest
         [tool.pytest.ini_options]
         minversion = "6"
@@ -244,7 +244,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         """
         The `testpaths` setting should be set to a reasonable default.
 
-        ```toml
+        ```ini
         # Old pytest
         [tool.pytest.ini_options]
         testpaths = ["tests"]
@@ -270,7 +270,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `log_level` should be set. This will allow logs to be displayed on
         failures.
 
-        ```toml
+        ```ini
         # Old pytest
         [tool.pytest.ini_options]
         log_level = "INFO"
@@ -297,7 +297,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         be set. You can manually specify if a check should be strict when
         setting each xfail.
 
-        ```toml
+        ```ini
         [tool.pytest.ini_options]
         xfail_strict = true
 
@@ -326,7 +326,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `strict_config` or `strict` should be set. This forces an error if a
         config setting is misspelled.
 
-        ```toml
+        ```ini
         # Old pytest
         [tool.pytest.ini_options]
         addopts = ["-ra", "--strict-config", "--strict-markers"]
@@ -357,7 +357,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `strict_markers` or `strict` should be set. This forces test markers to
         be specified in config, avoiding misspellings.
 
-        ```toml
+        ```ini
         # Old pytest
         [tool.pytest.ini_options]
         addopts = ["-ra", "--strict-config", "--strict-markers"]
@@ -387,7 +387,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         An explicit summary flag like `-ra` should be in `addopts = [...]`
         (print summary of all fails/errors).
 
-        ```toml
+        ```ini
         # Old pytest
         [tool.pytest.ini_options]
         addopts = ["-ra", "--strict-config", "--strict-markers"]
@@ -416,7 +416,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `filterwarnings` must be set (probably to at least `["error"]`). Python
         will hide important warnings otherwise, like deprecations.
 
-        ```toml
+        ```ini
         # Old pytest
         [tool.pytest.ini_options]
         filterwarnings = ["error"]
diff --git a/src/sp_repo_review/checks/ruff.py b/src/sp_repo_review/checks/ruff.py
index 69eb71ec..65c2bfa4 100644
--- a/src/sp_repo_review/checks/ruff.py
+++ b/src/sp_repo_review/checks/ruff.py
@@ -139,7 +139,7 @@ def check(cls: type[RF1xxMixin], ruff: dict[str, Any]) -> bool:
         """
         Must select the {self.name} `{self.code}` checks. Recommended:
 
-        ```toml
+        ```ini
         [tool.ruff.lint]
         extend-select = [
           "{self.code}",  # {self.name}
diff --git a/{{cookiecutter.project_name}}/README.md b/{{cookiecutter.project_name}}/README.md
index f833ba96..473943dc 100644
--- a/{{cookiecutter.project_name}}/README.md
+++ b/{{cookiecutter.project_name}}/README.md
@@ -18,7 +18,6 @@
 <!-- SPHINX-START -->
 {%- endif %}
 
-<!-- prettier-ignore-start -->
 [actions-badge]:            {{cookiecutter.url}}/actions/workflows/ci.yml/badge.svg
 [actions-link]:             {{cookiecutter.url}}/actions
 [conda-badge]:              https://img.shields.io/conda/vn/conda-forge/{{cookiecutter.project_name}}
@@ -36,4 +35,3 @@
 [coverage-badge]:           https://codecov.io/{{cookiecutter.__ci}}/{{cookiecutter.org}}/{{cookiecutter.project_name}}/branch/main/graph/badge.svg
 [coverage-link]:            https://codecov.io/{{cookiecutter.__ci}}/{{cookiecutter.org}}/{{cookiecutter.project_name}}
 
-<!-- prettier-ignore-end -->