style: switch to panache markdown formatting

.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

.pre-commit-config.yaml

@@ -11,6 +11,10 @@ repos:
     hooks:
       - id: biome-format
         exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually.
+  - repo: https://github.com/jolars/panache-pre-commit
+    rev: v3.18.0
+    hooks:
+      - id: panache-format
   - repo: https://github.com/tox-dev/pyproject-fmt
     rev: v2.25.3
     hooks:

README.md

@@ -36,7 +36,7 @@ For more information on the `spatialdata-plot` library, please refer to the [doc
 
 ## Installation
 
-You need to have Python 3.12 or newer installed on your system. If you don't have
+You need to have Python 3.12 or newer installed on your system. If you don’t have
 Python installed, we recommend installing [Mambaforge](https://github.com/conda-forge/miniforge#mambaforge).
 
 There are several alternative options to install spatialdata-plot:
@@ -79,6 +79,6 @@ If you like scverse® and want to support our mission, please consider making a
   <img
     src="https://raw.githubusercontent.com/numfocus/templates/master/images/numfocus-logo.png"
     width="200"
-  >
+>
 </a>
 </div>

docs/api.md

@@ -5,5 +5,4 @@
 :caption: API
 
 plotting.rst
-
 ```

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 . --group dev --group test --group doc
 ```
 
 The `.venv` directory is typically automatically discovered by IDEs such as VS Code.
-
 ::::
 :::::
 
@@ -173,7 +167,7 @@ git pull --rebase
 to integrate the changes into yours.
 While the [pre-commit.ci][] is useful, 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].
 
 [pre-commit]: https://pre-commit.com/
@@ -204,7 +198,6 @@ hatch test  # test with the highest supported Python version
 # or
 hatch test --all  # test with all supported Python versions
 ```
-
 ::::
 
 ::::{tab-item} uv
@@ -213,7 +206,6 @@ hatch test --all  # test with all supported Python versions
 ```bash
 uv run pytest
 ```
-
 ::::
 
 ::::{tab-item} Pip
@@ -223,7 +215,6 @@ uv run pytest
 source .venv/bin/activate
 pytest
 ```
-
 ::::
 :::::
 
@@ -260,7 +251,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][].
@@ -319,7 +310,6 @@ please check out [this feature request][issue-render-notebooks] in the `cookiecu
 hatch run docs:build
 hatch run docs:open
 ```
-
 ::::
 
 ::::{tab-item} uv
@@ -330,7 +320,6 @@ cd docs
 uv run sphinx-build -M html . _build -W
 (xdg-)open _build/html/index.html
 ```
-
 ::::
 
 ::::{tab-item} Pip
@@ -342,6 +331,5 @@ cd docs
 sphinx-build -M html . _build -W
 (xdg-)open _build/html/index.html
 ```
-
 ::::
 :::::

docs/gallery.md

@@ -19,7 +19,7 @@ Learn the API on synthetic data. Start with *Getting started*.
 
 ## Examples
 
-Apply the API to real datasets you'd actually analyse.
+Apply the API to real datasets you’d actually analyse.
 
 :::{include} notebooks/examples/index.md
 :start-after: <!-- gallery-cards-start -->

docs/index.md

@@ -1,5 +1,4 @@
 ```{include} ../README.md
-
 ```
 
 ```{toctree}

plans/issue-749.md

@@ -3,7 +3,7 @@
 ## Root cause
 
 When a SpatialElement carries transformations to **multiple coordinate systems**
-(e.g. visium's `"<cs>"` and `"<cs>_downscaled_lowres"` pair), `filter_by_coordinate_system`
+(e.g. visium’s `"<cs>"` and `"<cs>_downscaled_lowres"` pair), `filter_by_coordinate_system`
 cannot strip the extra transformation (upstream spatialdata #176). `show()` then
 auto-detects **more coordinate systems than the user intended**. When the user
 passes a single `ax`, `_plan_panels` raises:
@@ -31,10 +31,10 @@ dropped (redundant) coordinate systems and pointing to `coordinate_systems=`.
 If the sets are genuinely distinct (count still `> n_ax`), fall through to the
 existing, correct `ValueError`.
 
-| File | Change | Rationale |
-|------|--------|-----------|
-| `src/spatialdata_plot/pl/basic.py` (`_resolve_coordinate_systems`) | After `strict_cs`, dedup redundant CS by element set when `ax` given + auto-detected; warn | Fixes the mismatch only on the path that currently errors → strictly backward compatible |
-| `tests/pl/test_show.py` | Regression test: multi-CS element + single `ax` no longer raises; distinct-CS case still raises | Lock behavior |
+  | File                                                               | Change                                                                                          | Rationale                                                                                |
+  | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+  | `src/spatialdata_plot/pl/basic.py` (`_resolve_coordinate_systems`) | After `strict_cs`, dedup redundant CS by element set when `ax` given + auto-detected; warn      | Fixes the mismatch only on the path that currently errors → strictly backward compatible |
+  | `tests/pl/test_show.py`                                            | Regression test: multi-CS element + single `ax` no longer raises; distinct-CS case still raises | Lock behavior                                                                            |
 
 Why scope to the `ax`-provided path only: the no-`ax` case currently produces
 one panel per coordinate system (redundant but not an error). Collapsing that
@@ -43,6 +43,7 @@ break the reporter explicitly asked to avoid. The `ax` path currently *errors*,
 so fixing it breaks nothing that worked before.
 
 ## Edge cases
+
 - [ ] 2 CS, same element set, single `ax` → collapse to 1, warn, render (main fix).
 - [ ] 2 CS, **different** element sets, single `ax` → still raise ValueError (correct; genuinely 2 panels).
 - [ ] N CS redundant, `ax` is a list of N → counts already match, no change.
@@ -52,23 +53,27 @@ so fixing it breaks nothing that worked before.
 - [ ] Multi-panel `color=[...]` → single CS required already; unaffected.
 
 ## Downstream impact
+
 - Public API unchanged (no new/changed kwargs).
 - Only converts a previously-raised `ValueError` into a successful render + warning.
 - No baseline image changes expected (new path only exercised by the regression test, which is non-visual).
 
 ## Test plan
+
 - [ ] Regression test (non-visual): multi-CS element, `filter_by_coordinate_system`, `render_shapes().show(ax=ax)` → no raise; assert 1 axis used.
 - [ ] Negative test: 2 CS with different elements + single `ax` → still raises `ValueError`.
 - [ ] Assert a `UserWarning` is emitted mentioning the dropped CS.
 
 ## Risks
+
 - Representative choice is "first in coordinate-system order", which may be the
   `_downscaled_lowres` variant. Visually identical for a standalone plot (axes
   autoscale), but a user overlaying multiple `show()` calls on one `ax` should
   still pass `coordinate_systems=`. The warning makes the choice explicit.
 - Low risk overall: new code runs only where the code previously raised.
 
 ## Alternative (Approach 2 — not recommended)
+
 Deduplicate redundant coordinate systems in auto-detect for **both** `ax` and
 no-`ax` paths. More internally consistent, but changes existing no-`ax`
 multi-panel output and possibly visual baselines → backward-incompatible.