flying-sheep · Nov 12, 2026 · Nov 12, 2026 · Nov 12, 2026 · Nov 12, 2026
diff --git a/.panache.toml b/.panache.toml
@@ -0,0 +1,14 @@
+#:schema https://panache.bz/panache.schema.json
+flavor = "myst"
+
+[format]
+wrap = "preserve"
+smart-punctuation = "unicode"
+tab-stops = "preserve"
+
+# MyST syntax extensions from `scverse_doc.config.MYST_ENABLE_EXTENSIONS`
+[extensions]
+myst-colon-fence = true  # colon_fence
+definition-lists = true  # deflist
+tex-math-dollars = true  # dollarmath, amsmath
+raw-html = true          # html_image, html_admonition
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -14,6 +14,11 @@ repos:
         groups: [format]
       - id: biome-lint
         args: [--error-on-warnings]
+  - repo: https://github.com/jolars/panache-pre-commit
+    rev: v3.18.0
+    hooks:
+      - id: panache-format
+        groups: [format]
   - repo: https://github.com/tox-dev/pyproject-fmt
     rev: v2.30.3
     hooks:

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -14,5 +14,6 @@
         "editorconfig.editorconfig",
         "charliermarsh.ruff",
         "biomejs.biome",
+        "jolars.panache",
     ],
 }
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,5 +1,5 @@
 {
-    "[python][json][jsonc]": {
+    "[python][json][jsonc][yaml][markdown]": {
         "editor.formatOnSave": true,
     },
     "[python]": {
@@ -9,9 +9,12 @@
             "source.organizeImports.ruff": "always",
         },
     },
-    "[json][jsonc]": {
+    "[json][jsonc][yaml]": {
         "editor.defaultFormatter": "biomejs.biome",
     },
+    "[markdown]": {
+        "editor.defaultFormatter": "jolars.panache",
+    },
     "python.testing.pytestEnabled": true,
     "python.testing.pytestArgs": ["-vv", "--color=yes"],
     "python-envs.defaultEnvManager": "pypa.hatch:hatch",

diff --git a/README.md b/README.md
@@ -18,15 +18,15 @@
 
 The shared Sphinx theme and documentation configuration for scverse packages.
 
-Install it, and a package's `conf.py` becomes:
+Install it, and a package’s `conf.py` becomes:
 
 ```python
 extensions = ["scverse_doc"]
 
 source_repository = "https://github.com/scverse/pertpy"
 ```
 
-That gets you the scverse brand and dark mode, the shared sidebar layout, footer, and announcement banner, a "scverse packages" dropdown generated from the package registry, cross-links to every core package, the repository links ("edit this page" and the header icon), and the standard extension stack.
+That gets you the scverse brand and dark mode, the shared sidebar layout, footer, and announcement banner, a “scverse packages” dropdown generated from the package registry, cross-links to every core package, the repository links (“edit this page” and the header icon), and the standard extension stack.
 
 Every piece also works on its own. For the theme without the extension stack or the shared defaults, select it and leave `extensions` alone – it is a registered Sphinx theme, so installing the package is enough:
 
@@ -45,7 +45,7 @@ The [kitchen sink][] shows every construct the theme styles, in both colour sche
 ## Installation
 
 You need to have Python 3.12 or newer installed on your system.
-If you don't have Python installed, we recommend installing [uv][].
+If you don’t have Python installed, we recommend installing [uv][].
 
 We recommend managing dependencies in project-specific virtual environments to avoid dependency conflicts.
 This is most convenient using package managers such as [uv][].

diff --git a/biome.jsonc b/biome.jsonc
@@ -12,6 +12,7 @@
         ],
     },
     "formatter": { "useEditorconfig": true },
+    "markdown": { "formatter": { "enabled": false } }, // handled by panache
     "javascript": {
         "formatter": {
             "semicolons": "asNeeded",

diff --git a/docs/api/source.md b/docs/api/source.md
@@ -52,12 +52,12 @@ An unknown forge still gets the icon link, just no per-page links.
 
 ## What each theme gets
 
-| Theme                                             | Reads                                                                                                                                                                  |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pydata-sphinx-theme`, and so {doc}`ours <theme>` | `html_context`’s `{provider}_user`/`_repo`/`_version`/`_url` and `doc_path`, plus `use_edit_page_button`                                                               |
-| `sphinx_rtd_theme`                                | the same, plus `display_{provider}`, `{provider}_host` and `conf_py_path`                                                                                              |
-| `furo`, and anything else on `sphinx-basic-ng`    | the `source_repository`/`source_branch`/`source_directory` theme options, plus `display_{provider}` for its footer icon – which it shows on Read the Docs only         |
-| `sphinx-book-theme`                               | the `repository_url`/`repository_branch`/`repository_provider`/`path_to_docs` theme options, plus `use_repository_button`, `use_source_button` and `use_issues_button` |
+  | Theme                                             | Reads                                                                                                                                                                  |
+  | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `pydata-sphinx-theme`, and so {doc}`ours <theme>` | `html_context`’s `{provider}_user`/`_repo`/`_version`/`_url` and `doc_path`, plus `use_edit_page_button`                                                               |
+  | `sphinx_rtd_theme`                                | the same, plus `display_{provider}`, `{provider}_host` and `conf_py_path`                                                                                              |
+  | `furo`, and anything else on `sphinx-basic-ng`    | the `source_repository`/`source_branch`/`source_directory` theme options, plus `display_{provider}` for its footer icon – which it shows on Read the Docs only         |
+  | `sphinx-book-theme`                               | the `repository_url`/`repository_branch`/`repository_provider`/`path_to_docs` theme options, plus `use_repository_button`, `use_source_button` and `use_issues_button` |
 
 Only the options a theme declares are written; a theme that declares none of them –
 `alabaster`, say – is left alone. Anything `conf.py` set itself wins.

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,3 +1,2 @@
 ```{include} ../CHANGELOG.md
-
 ```
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -12,7 +12,6 @@ the [scientific Python tutorials][], or the [scanpy developer guide][].
 [scanpy developer guide]: https://scanpy.scverse.org/page/dev/
 
 :::{tip} The _hatch_ project manager
-
 We highly recommend to familiarize yourself with [`hatch`][hatch].
 Hatch is a Python project manager that
 
@@ -23,14 +22,13 @@ Hatch is a Python project manager that
 
 While the project is setup with `hatch` in mind,
 it is still possible to use different tools to manage dependencies, such as `uv` or `pip`.
-
 :::
 
 [hatch]: https://hatch.pypa.io/latest/
 
 ## Installing dev dependencies
 
-In addition to the packages needed to _use_ this package,
+In addition to the packages needed to *use* this package,
 you need additional python packages to [run tests](#writing-tests) and [build the documentation](#docs-building).
 
 :::::{tab-set}
@@ -52,9 +50,9 @@ If you are using VS code, install the [hatch-code][] extension.
 Additionally, make sure that the `vscode-python-environments` extension is installed (should be by default)
 and `"python.useEnvironmentsExtension": true` is activated in your `settings.json`.
 
-Next, open the "Python Environment Managers" sidebar.
+Next, open the “Python Environment Managers” sidebar.
 You can do so by opening the command palette (Ctrl+Shift+P) and searching for `Python: Focus on Environment Managers View`.
-It will show a collapsible list where you can expand "Hatch"
+It will show a collapsible list where you can expand “Hatch”
 and activate an environment by clicking on the checkmark next to it.
 As the main development environment, we recommend to use `hatch-test` with the latest supported Python version.
 
@@ -100,8 +98,6 @@ hatch env find hatch-test.py3.14-stable
 ```
 
 and manually point it to the python binary.
-
-
 ::::
 
 ::::{tab-item} uv
@@ -121,7 +117,6 @@ uv sync --all-extras
 ```
 
 The `.venv` directory is typically automatically discovered by IDEs such as VS Code.
-
 ::::
 
 ::::{tab-item} Pip
@@ -138,7 +133,6 @@ pip install -e ".[dev,test,doc]"
 ```
 
 The `.venv` directory is typically automatically discovered by IDEs such as VS Code.
-
 ::::
 :::::
 
@@ -167,7 +161,7 @@ If you didn’t run the checks locally, the `Pre-commit checks` job of the GitHu
 pushes the automatic fixes back to your branch, and reports any remaining failures.
 We strongly encourage installing and running the checks locally first to understand their usage.
 
-Finally, most editors have an _autoformat on save_ feature.
+Finally, most editors have an *autoformat on save* feature.
 Consider enabling this option for [ruff][ruff-editors] and [biome][biome-editors].
 
 [prek]: https://prek.j178.dev/
@@ -196,7 +190,6 @@ hatch test  # test with the highest supported Python version
 # or
 hatch test --all  # test with all supported Python versions
 ```
-
 ::::
 
 ::::{tab-item} uv
@@ -205,7 +198,6 @@ hatch test --all  # test with all supported Python versions
 ```bash
 uv run pytest
 ```
-
 ::::
 
 ::::{tab-item} Pip
@@ -215,7 +207,6 @@ uv run pytest
 source .venv/bin/activate
 pytest
 ```
-
 ::::
 :::::
 
@@ -252,7 +243,7 @@ Please adhere to [Semantic Versioning][semver], in brief
 >
 > Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
 
-Once you are done, commit and push your changes and navigate to the "Releases" page of this project on GitHub.
+Once you are done, commit and push your changes and navigate to the “Releases” page of this project on GitHub.
 Specify `vX.X.X` as a tag name and create a release.
 For more information, see [managing GitHub releases][].
 This will automatically create a git tag and trigger a Github workflow that creates a release on [PyPI][].
@@ -312,7 +303,6 @@ please check out [this feature request][issue-render-notebooks] in the `cookiecu
 hatch run docs:build
 hatch run docs:open
 ```
-
 ::::
 
 ::::{tab-item} uv
@@ -323,7 +313,6 @@ cd docs
 uv run sphinx-build -M html . _build -W
 (xdg-)open _build/html/index.html
 ```
-
 ::::
 
 ::::{tab-item} Pip
@@ -335,7 +324,6 @@ cd docs
 sphinx-build -M html . _build -W
 (xdg-)open _build/html/index.html
 ```
-
 ::::
 :::::
 

diff --git a/docs/kitchen-sink.md b/docs/kitchen-sink.md
@@ -7,7 +7,7 @@ like on any other – switch the theme with the toggle in the page header.
 
 ## Text
 
-Body copy with **bold**, _italic_, `inline literal` (the default role), an
+Body copy with **bold**, *italic*, `inline literal` (the default role), an
 [external link](https://scverse.org), an [internal one](api.md), a footnote[^fn] and a
 cross-reference to {func}`~scverse_doc.registry.intersphinx`.
 
@@ -40,10 +40,11 @@ custom property; H{sub}`2`O and x{sup}`2` also render.
 2. Numbered
 
 Definition list
-: Enabled through the `deflist` MyST extension.
+:   Enabled through the `deflist` MyST extension.
 
 Field and option lists and `hlist` are docutils-only, so they need `eval-rst`:
 
+<!-- panache-ignore-format-start -->
 ```{eval-rst}
 :Field: A field list entry.
 :Another: A second one.
@@ -62,11 +63,12 @@ Field and option lists and `hlist` are docutils-only, so they need `eval-rst`:
    * scvi-tools
    * squidpy
 ```
+<!-- panache-ignore-format-end -->
 
 ## Admonitions
 
 ```{note}
-A note, in the theme's border and surface tokens.
+A note, in the theme’s border and surface tokens.
 ```
 
 ```{warning}
@@ -188,11 +190,11 @@ third = "plain"
 
 ## Table
 
-| Token                               | Role                             |
-| ----------------------------------- | -------------------------------- |
-| `--scverse-color-accent-text`       | Links and text, contrast-checked |
-| `--scverse-color-accent-decorative` | Underlines and surfaces          |
-| `--scverse-radius`                  | Shared component geometry        |
+  | Token                               | Role                             |
+  | ----------------------------------- | -------------------------------- |
+  | `--scverse-color-accent-text`       | Links and text, contrast-checked |
+  | `--scverse-color-accent-decorative` | Underlines and surfaces          |
+  | `--scverse-radius`                  | Shared component geometry        |
 
 ## Cards
 
@@ -231,6 +233,7 @@ $ hatch run docs:build -D html_theme_options.accent=#de367b
 
 ```{button-link} https://scverse.org
 :color: primary
+
 A button
 ```
 

diff --git a/tests/roots/minimal/index.md b/tests/roots/minimal/index.md
@@ -1,6 +1,6 @@
 # Minimal fixture
 
-A fixture documentation tree used by the theme's own tests.
+A fixture documentation tree used by the theme’s own tests.
 
 ```{toctree}
 :hidden:

diff --git a/tests/roots/override/index.md b/tests/roots/override/index.md
@@ -1,3 +1,3 @@
 # Minimal fixture
 
-A fixture documentation tree used by the theme's own tests.
+A fixture documentation tree used by the theme’s own tests.