feat: move to mystmd

.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

.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]

.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

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.