diff --git a/docs/conf.py b/docs/conf.py
index 30dde06a45..83e568ce5a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -2,10 +2,12 @@
 
 import sys
 from datetime import datetime
+from functools import partial
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import matplotlib  # noqa
+from docutils import nodes
 from packaging.version import Version
 
 # Don’t use tkinter agg when importing scanpy → … → matplotlib
@@ -50,7 +52,14 @@
 templates_path = ["_templates"]
 master_doc = "index"
 default_role = "literal"
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "**.ipynb_checkpoints",
+    # exclude all 0.x.y.md files, but not index.md
+    "release-notes/[!i]*.md",
+]
 
 extensions = [
     "myst_nb",
@@ -96,6 +105,7 @@
     "html_admonition",
 ]
 myst_url_schemes = ("http", "https", "mailto", "ftp")
+myst_heading_anchors = 3
 nb_output_stderr = "remove"
 nb_execution_mode = "off"
 nb_merge_streams = True
@@ -151,6 +161,8 @@
 
 def setup(app: Sphinx):
     """App setup hook."""
+    app.add_generic_role("small", partial(nodes.inline, classes=["small"]))
+    app.add_generic_role("smaller", partial(nodes.inline, classes=["smaller"]))
     app.add_config_value(
         "recommonmark_config",
         {
diff --git a/docs/ecosystem.md b/docs/ecosystem.md
index d78a5bd930..2c7aba9f9b 100644
--- a/docs/ecosystem.md
+++ b/docs/ecosystem.md
@@ -1,13 +1,5 @@
 # Ecosystem
 
-```{eval-rst}
-.. role:: small
-```
-
-```{eval-rst}
-.. role:: smaller
-```
-
 ```{warning}
 We are no longer accepting new tools on this page.
 Instead, please submit your tool to the [scverse ecosystem package listing](https://scverse.org/packages/#ecosystem).
diff --git a/docs/index.md b/docs/index.md
index a8b49c72a4..4d648e8d39 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,14 +2,6 @@
 :end-before: '## Citation'
 ```
 
-```{eval-rst}
-.. role:: small
-```
-
-```{eval-rst}
-.. role:: smaller
-```
-
 ::::{grid} 1 2 3 3
 :gutter: 2
 
diff --git a/docs/news.md b/docs/news.md
index 5ff7f0b6d5..ac3bcd2856 100644
--- a/docs/news.md
+++ b/docs/news.md
@@ -1,12 +1,6 @@
 (News)=
-
 ## News
 
-```{eval-rst}
-.. role:: small
-
-```
-
 <!-- marker: after prelude -->
 
 ### `rapids-singlecell` brings scanpy to the GPU! {small}`2024-03-18`
diff --git a/docs/release-notes/0.1.0.md b/docs/release-notes/0.1.0.md
index 181907de1a..c2b568ac69 100644
--- a/docs/release-notes/0.1.0.md
+++ b/docs/release-notes/0.1.0.md
@@ -1,3 +1,4 @@
+(v0.1.0)=
 ### 0.1.0 {small}`2017-05-17`
 
 Scanpy computationally outperforms and allows reproducing both the [Cell Ranger
diff --git a/docs/release-notes/0.2.1.md b/docs/release-notes/0.2.1.md
index 394a561398..c49fe1f264 100644
--- a/docs/release-notes/0.2.1.md
+++ b/docs/release-notes/0.2.1.md
@@ -1,3 +1,4 @@
+(v0.2.1)=
 ### 0.2.1 {small}`2017-07-24`
 
 Scanpy includes preprocessing, visualization, clustering, pseudotime and
diff --git a/docs/release-notes/0.2.9.md b/docs/release-notes/0.2.9.md
index 3d288c6a23..3ac14e9506 100644
--- a/docs/release-notes/0.2.9.md
+++ b/docs/release-notes/0.2.9.md
@@ -1,7 +1,7 @@
+(v0.2.9)=
 ### 0.2.9 {small}`2017-10-25`
 
-```{rubric} Initial release of the new trajectory inference method [PAGA](https://github.com/theislab/paga)
-```
+#### Initial release of the new trajectory inference method [PAGA](https://github.com/theislab/paga)
 
 - {func}`~scanpy.tl.paga` computes an abstracted, coarse-grained (PAGA) graph of the neighborhood graph {smaller}`A Wolf`
 - {func}`~scanpy.pl.paga_compare` plot this graph next an embedding {smaller}`A Wolf`
diff --git a/docs/release-notes/0.3.0.md b/docs/release-notes/0.3.0.md
index 9736c1bab0..7b3f48cc44 100644
--- a/docs/release-notes/0.3.0.md
+++ b/docs/release-notes/0.3.0.md
@@ -1,3 +1,4 @@
+(v0.3.0)=
 ### 0.3.0 {small}`2017-11-16`
 
 - {class}`~anndata.AnnData` gains method {meth}`~anndata.AnnData.concatenate` {smaller}`A Wolf`
diff --git a/docs/release-notes/0.3.2.md b/docs/release-notes/0.3.2.md
index bcdd791e22..deaa2c2d6f 100644
--- a/docs/release-notes/0.3.2.md
+++ b/docs/release-notes/0.3.2.md
@@ -1,3 +1,4 @@
+(v0.3.2)=
 ### 0.3.2 {small}`2017-11-29`
 
 - finding marker genes via {func}`~scanpy.pl.rank_genes_groups_violin` improved,
diff --git a/docs/release-notes/0.4.0.md b/docs/release-notes/0.4.0.md
index 4b5d789da8..870db9457e 100644
--- a/docs/release-notes/0.4.0.md
+++ b/docs/release-notes/0.4.0.md
@@ -1,3 +1,4 @@
+(v0.4.0)=
 ### 0.4.0 {small}`2017-12-23`
 
 - export to [SPRING] {cite:p}`Weinreb2017` for interactive visualization of data:
diff --git a/docs/release-notes/0.4.2.md b/docs/release-notes/0.4.2.md
index 2271f01bfb..7b832e6c9b 100644
--- a/docs/release-notes/0.4.2.md
+++ b/docs/release-notes/0.4.2.md
@@ -1,3 +1,4 @@
+(v0.4.2)=
 ### 0.4.2 {small}`2018-01-07`
 
 - amendments in [PAGA](https://github.com/theislab/paga) and its plotting functions {smaller}`A Wolf`
diff --git a/docs/release-notes/0.4.3.md b/docs/release-notes/0.4.3.md
index 2a5aedad78..1bff0701d1 100644
--- a/docs/release-notes/0.4.3.md
+++ b/docs/release-notes/0.4.3.md
@@ -1,3 +1,4 @@
+(v0.4.3)=
 ### 0.4.3 {small}`2018-02-09`
 
 - {func}`~scanpy.pl.clustermap`: heatmap from hierarchical clustering,
diff --git a/docs/release-notes/0.4.4.md b/docs/release-notes/0.4.4.md
index e69de29bb2..4ebe8392f6 100644
--- a/docs/release-notes/0.4.4.md
+++ b/docs/release-notes/0.4.4.md
@@ -0,0 +1,6 @@
+(v0.4.4)=
+### 0.4.4 {small}`2018-02-26`
+
+- embed cells using {func}`~scanpy.tl.umap` {cite:p}`McInnes2018` {pr}`92` {smaller}`G Eraslan`
+- score sets of genes, e.g. for cell cycle, using {func}`~scanpy.tl.score_genes` {cite:p}`Satija2015`:
+  [notebook](https://nbviewer.jupyter.org/github/theislab/scanpy_usage/blob/master/180209_cell_cycle/cell_cycle.ipynb)
diff --git a/docs/release-notes/1.0.0.md b/docs/release-notes/1.0.0.md
index 74ac0ea561..00fa8b43db 100644
--- a/docs/release-notes/1.0.0.md
+++ b/docs/release-notes/1.0.0.md
@@ -1,7 +1,7 @@
+(v1.0.0)=
 ### 1.0.0 {small}`2018-03-30`
 
-```{rubric} Major updates
-```
+#### Major updates
 
 - Scanpy is much faster and more memory efficient: preprocess, cluster and
   visualize 1.3M cells in [6h], 130K cells in [14min], and 68K cells in [3min] {smaller}`A Wolf`
@@ -10,8 +10,7 @@
   delegated {smaller}`A Wolf`
 
 ```{warning}
-```{rubric} Upgrading to 1.0 isn’t fully backwards compatible in the following changes
-```
+#### Upgrading to 1.0 isn’t fully backwards compatible in the following changes
 
 - the graph-based tools {func}`~scanpy.tl.louvain`
   {func}`~scanpy.tl.dpt` {func}`~scanpy.tl.draw_graph`
@@ -35,8 +34,7 @@
   some results might therefore look slightly different
 ```
 
-```{rubric} Further updates
-```
+#### Further updates
 
 - UMAP {cite:p}`McInnes2018` can serve as a first visualization of the data just as tSNE,
   in contrast to tSNE, UMAP directly embeds the single-cell graph and is faster;
diff --git a/docs/release-notes/1.1.0.md b/docs/release-notes/1.1.0.md
index 85f22988c3..1d7cfb8a71 100644
--- a/docs/release-notes/1.1.0.md
+++ b/docs/release-notes/1.1.0.md
@@ -1,3 +1,4 @@
+(v1.1.0)=
 ### 1.1.0 {small}`2018-06-01`
 
 - {func}`~scanpy.set_figure_params` by default passes `vector_friendly=True` and allows you to produce reasonablly sized pdfs by rasterizing large scatter plots {smaller}`A Wolf`
diff --git a/docs/release-notes/1.10.0.md b/docs/release-notes/1.10.0.md
index a42d409f9f..0448d9fc5f 100644
--- a/docs/release-notes/1.10.0.md
+++ b/docs/release-notes/1.10.0.md
@@ -1,3 +1,4 @@
+(v1.10.0)=
 ### 1.10.0 {small}`2024-03-26`
 
 `scanpy` 1.10 brings a large amount of new features, performance improvements, and improved documentation.
@@ -10,8 +11,7 @@ Some highlights:
 * Ability to `mask` observations or variables from a number of methods (see {doc}`/tutorials/plotting/advanced` for an example with plotting embeddings)
 * A new function {func}`~scanpy.get.aggregate` for computing aggregations of your data, very useful for pseudo bulking!
 
-```{rubric} Features
-```
+#### Features
 
 * {func}`~scanpy.pp.scrublet` and {func}`~scanpy.pp.scrublet_simulate_doublets` were moved from {mod}`scanpy.external.pp` to {mod}`scanpy.pp`. The `scrublet` implementation is now maintained as part of scanpy {pr}`2703` {smaller}`P Angerer`
 * {func}`scanpy.pp.pca`, {func}`scanpy.pp.scale`, {func}`scanpy.pl.embedding`, and {func}`scanpy.experimental.pp.normalize_pearson_residuals_pca` now support a `mask` parameter {pr}`2272` {smaller}`C Bright, T Marcella, & P Angerer`
@@ -32,8 +32,7 @@ Some highlights:
 * {func}`scanpy.pp.scale` now clips `np.ndarray` also at `- max_value` for zero-centering {pr}`2913` {smaller}`S Dicks`
 * Support sparse chunks in dask {func}`~scanpy.pp.scale`, {func}`~scanpy.pp.normalize_total` and {func}`~scanpy.pp.highly_variable_genes` (`seurat` and `cell-ranger` tested) {pr}`2856` {smaller}`ilan-gold`
 
-```{rubric} Docs
-```
+#### Docs
 
 * Doc style overhaul {pr}`2220` {smaller}`A Gayoso`
 * Re-add search-as-you-type, this time via `readthedocs-sphinx-search` {pr}`2805` {smaller}`P Angerer`
@@ -44,8 +43,7 @@ Some highlights:
 * Overhauled {doc}`/tutorials/index` page, and added new {doc}`/how-to/index` section to docs {pr}`2901` {smaller}`I Virshup`
 * Added a new tutorial on working with dask ({doc}`/tutorials/experimental/dask`) {pr}`2901` {smaller}`I Gold` {smaller}`I Virshup`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Updated {func}`~scanpy.read_visium` such that it can read spaceranger 2.0 files {smaller}`L Lehner`
 * Fix {func}`~scanpy.pp.normalize_total` for dask {pr}`2466` {smaller}`P Angerer`
@@ -61,14 +59,12 @@ Some highlights:
 * Fix pytest deprecation warning {pr}`2879` {smaller}`P Angerer`
 
 
-```{rubric} Development
-```
+#### Development
 
 * Scanpy is now tested against python 3.12 {pr}`2863` {smaller}`ivirshup`
 * Fix testing package build {pr}`2468` {smaller}`P Angerer`
 
-```{rubric} Deprecations
-```
+#### Deprecations
 
 * Dropped support for Python 3.8. [More details here](https://numpy.org/neps/nep-0029-deprecation_policy.html). {pr}`2695` {smaller}`P Angerer`
 * Deprecated specifying large numbers of function parameters by position as opposed to by name/keyword in all public APIs.
diff --git a/docs/release-notes/1.10.1.md b/docs/release-notes/1.10.1.md
index 6e9414c9bf..35f631bdc0 100644
--- a/docs/release-notes/1.10.1.md
+++ b/docs/release-notes/1.10.1.md
@@ -1,16 +1,14 @@
+(v1.10.1)=
 ### 1.10.1 {small}`2024-04-09`
 
-```{rubric} Docs
-```
+#### Docs
 
 * Added {doc}`how-to example </how-to/plotting-with-marsilea>` on plotting with [Marsilea](https://marsilea.readthedocs.io) {pr}`2974` {smaller}`Y Zheng`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Fix `aggregate` when aggregating by more than two groups {pr}`2965` {smaller}`I Virshup`
 
 
-```{rubric} Performance
-```
+#### Performance
 * {func}`~scanpy.pp.scale` now uses numba kernels for `sparse.csr_matrix` and `sparse.csc_matrix` when `zero_center==False` and `mask_obs` is provided. This greatly speed up execution {pr}`2942` {smaller}`S Dicks`
diff --git a/docs/release-notes/1.10.2.md b/docs/release-notes/1.10.2.md
index 586cde1d55..8e0342054b 100644
--- a/docs/release-notes/1.10.2.md
+++ b/docs/release-notes/1.10.2.md
@@ -1,12 +1,11 @@
+(v1.10.2)=
 ### 1.10.2 {small}`2024-06-25`
 
-```{rubric} Development features
-```
+#### Development features
 
 * Add performance benchmarking {pr}`2977` {smaller}`R Shrestha`, {smaller}`P Angerer`
 
-```{rubric} Docs
-```
+#### Docs
 
 * Document several missing parameters in docstring {pr}`2888` {smaller}`S Cheney`
 * Fixed incorrect instructions in "testing" dev docs {pr}`2994` {smaller}`I Virshup`
@@ -14,8 +13,7 @@
 * Fixed citations {pr}`3032` {smaller}`P Angerer`
 * Improve dataset documentation {pr}`3060` {smaller}`P Angerer`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Compatibility with `matplotlib` 3.9 {pr}`2999` {smaller}`I Virshup`
 * Add clear errors where `backed` mode-like matrices (i.e., from `sparse_dataset`) are not supported {pr}`3048` {smaller}`I gold`
@@ -24,8 +22,7 @@
 * Fix zappy support {pr}`3089` {smaller}`P Angerer`
 * Fix dotplot group order with {mod}`pandas` 1.x {pr}`3101` {smaller}`P Angerer`
 
-```{rubric} Performance
-```
+#### Performance
 
 * `sparse_mean_variance_axis` now uses all cores for the calculations {pr}`3015` {smaller}`S Dicks`
 * `pp.highly_variable_genes` with `flavor=seurat_v3` now uses a numba kernel {pr}`3017` {smaller}`S Dicks`
diff --git a/docs/release-notes/1.10.3.md b/docs/release-notes/1.10.3.md
index 29ff234af5..bbb8edbc8c 100644
--- a/docs/release-notes/1.10.3.md
+++ b/docs/release-notes/1.10.3.md
@@ -1,18 +1,15 @@
+(v1.10.3)=
 ### 1.10.3 {small}`the future`
 
-```{rubric} Development features
-```
+#### Development features
 
-```{rubric} Docs
-```
+#### Docs
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Prevent empty control gene set in {func}`~scanpy.tl.score_genes` {pr}`2875` {smaller}`M Müller`
 * Fix `subset=True` of {func}`~scanpy.pp.highly_variable_genes` when `flavor` is `seurat` or `cell_ranger`, and `batch_key!=None` {pr}`3042` {smaller}`E Roellin`
 * Add compatibility with {mod}`numpy` 2.0 {pr}`3065` and {pr}`3115` {smaller}`P Angerer`
 * Fix `legend_loc` argument in {func}`scanpy.pl.embedding` not accepting matplotlib parameters {pr}`3163` {smaller}`P Angerer`
 
-```{rubric} Performance
-```
+#### Performance
diff --git a/docs/release-notes/1.11.0.md b/docs/release-notes/1.11.0.md
index 6baccacc16..fee2d0b1a9 100644
--- a/docs/release-notes/1.11.0.md
+++ b/docs/release-notes/1.11.0.md
@@ -1,16 +1,13 @@
+(v1.11.0)=
 ### 1.11.0 {small}`the future`
 
-```{rubric} Features
-```
+#### Features
 
 * Add layer argument to {func}`scanpy.tl.score_genes` and {func}`scanpy.tl.score_genes_cell_cycle` {pr}`2921` {smaller}`L Zappia`
 * Prevent `raw` conflict with `layer` in {func}`~scanpy.tl.score_genes` {pr}`3155` {smaller}`S Dicks`
 
-```{rubric} Docs
-```
+#### Docs
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
-```{rubric} Deprecations
-```
+#### Deprecations
diff --git a/docs/release-notes/1.2.0.md b/docs/release-notes/1.2.0.md
index 5bd2ed451e..973b59775c 100644
--- a/docs/release-notes/1.2.0.md
+++ b/docs/release-notes/1.2.0.md
@@ -1,3 +1,4 @@
+(v1.2.0)=
 ### 1.2.0 {small}`2018-06-08`
 
 - {func}`~scanpy.tl.paga` improved, see [PAGA](https://github.com/theislab/paga); the default model changed, restore the previous default model by passing `model='v1.0'`
diff --git a/docs/release-notes/1.2.1.md b/docs/release-notes/1.2.1.md
index 3110537aa8..5979029098 100644
--- a/docs/release-notes/1.2.1.md
+++ b/docs/release-notes/1.2.1.md
@@ -1,6 +1,6 @@
+(v1.2.1)=
 ### 1.2.1 {small}`2018-06-08`
 
-~~~{rubric} Plotting of {ref}`pl-generic` marker genes and quality control.
-~~~
+#### Plotting of {ref}`pl-generic` marker genes and quality control.
 
 - {func}`~scanpy.pl.highest_expr_genes` for quality control; plot genes with highest mean fraction of cells, similar to `plotQC` of *Scater* {cite:p}`McCarthy2017` {pr}`169` {smaller}`F Ramirez`
diff --git a/docs/release-notes/1.3.1.md b/docs/release-notes/1.3.1.md
index 8492d6b9e6..829e56ec26 100644
--- a/docs/release-notes/1.3.1.md
+++ b/docs/release-notes/1.3.1.md
@@ -1,20 +1,18 @@
+(v1.3.1)=
 ### 1.3.1 {small}`2018-09-03`
 
-```{rubric} RNA velocity in single cells {cite:p}`LaManno2018`
-```
+#### RNA velocity in single cells {cite:p}`LaManno2018`
 
 - Scanpy and AnnData support loom’s layers so that computations for single-cell RNA velocity {cite:p}`LaManno2018` become feasible {smaller}`S Rybakov and V Bergen`
 - [scvelo] harmonizes with Scanpy and is able to process loom files with splicing information produced by Velocyto {cite:p}`LaManno2018`, it runs a lot faster than the count matrix analysis of Velocyto and provides several conceptual developments
 
-~~~{rubric} Plotting ({ref}`pl-generic`)
-~~~
+#### Plotting ({ref}`pl-generic`)
 
 - {func}`~scanpy.pl.dotplot` for visualizing genes across conditions and clusters, see [here](https://gist.github.com/fidelram/2289b7a8d6da055fb058ac9a79ed485c) {pr}`199` {smaller}`F Ramirez`
 - {func}`~scanpy.pl.heatmap` for pretty heatmaps {pr}`175` {smaller}`F Ramirez`
 - {func}`~scanpy.pl.violin` produces very compact overview figures with many panels {pr}`175` {smaller}`F Ramirez`
 
-~~~{rubric} There now is a section on imputation in {doc}`external <../external/index>`:
-~~~
+#### There now is a section on imputation in {doc}`external <../external/index>`:
 
 - {func}`~scanpy.external.pp.magic` for imputation using data diffusion {cite:p}`vanDijk2018` {pr}`187` {smaller}`S Gigante`
 - {func}`~scanpy.external.pp.dca` for imputation and latent space construction using an autoencoder {cite:p}`Eraslan2019` {pr}`186` {smaller}`G Eraslan`
diff --git a/docs/release-notes/1.3.3.md b/docs/release-notes/1.3.3.md
index f94e3c5dec..fd898ec4eb 100644
--- a/docs/release-notes/1.3.3.md
+++ b/docs/release-notes/1.3.3.md
@@ -1,18 +1,16 @@
+(v1.3.3)=
 ### 1.3.3 {small}`2018-11-05`
 
-```{rubric} Major updates
-```
+#### Major updates
 
 - a fully distributed preprocessing backend {smaller}`T White and the Laserson Lab`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {func}`~scanpy.read_10x_h5` and {func}`~scanpy.read_10x_mtx` read Cell Ranger 3.0 outputs {pr}`334` {smaller}`Q Gong`
 
 ```{note}
-```{rubric} Also see changes in anndata 0.6.
-```
+#### Also see changes in anndata 0.6.
 
 - changed default compression to `None` in {meth}`~anndata.AnnData.write_h5ad` to speed up read and write, disk space use is usually less critical
 - performance gains in {meth}`~anndata.AnnData.write_h5ad` due to better handling of strings and categories {smaller}`S Rybakov`
diff --git a/docs/release-notes/1.3.4.md b/docs/release-notes/1.3.4.md
index ab4a9b599b..9381bc4647 100644
--- a/docs/release-notes/1.3.4.md
+++ b/docs/release-notes/1.3.4.md
@@ -1,3 +1,4 @@
+(v1.3.4)=
 ### 1.3.4 {small}`2018-11-24`
 
 - {func}`~scanpy.tl.leiden` wraps the recent graph clustering package by {cite:t}`Traag2019` {smaller}`K Polanski`
diff --git a/docs/release-notes/1.3.5.md b/docs/release-notes/1.3.5.md
index 198b5e9994..20706e9fca 100644
--- a/docs/release-notes/1.3.5.md
+++ b/docs/release-notes/1.3.5.md
@@ -1,3 +1,4 @@
+(v1.3.5)=
 ### 1.3.5 {small}`2018-12-09`
 
 - uncountable figure improvements {pr}`369` {smaller}`F Ramirez`
diff --git a/docs/release-notes/1.3.6.md b/docs/release-notes/1.3.6.md
index 75d5cbbbcc..a8bf3a94a1 100644
--- a/docs/release-notes/1.3.6.md
+++ b/docs/release-notes/1.3.6.md
@@ -1,19 +1,17 @@
+(v1.3.6)=
 ### 1.3.6 {small}`2018-12-11`
 
-```{rubric} Major updates
-```
+#### Major updates
 
 - a new plotting gallery for `visualizing-marker-genes` {smaller}`F Ramirez`
 - tutorials are integrated on ReadTheDocs, `pbmc3k` and `paga-paul15` {smaller}`A Wolf`
 
-```{rubric} Interactive exploration of analysis results through *manifold viewers*
-```
+#### Interactive exploration of analysis results through *manifold viewers*
 
 - CZI’s [cellxgene] directly reads `.h5ad` files {smaller}`the cellxgene developers`
 - the [UCSC Single Cell Browser] requires exporting via {func}`~scanpy.external.exporting.cellbrowser` {smaller}`M Haeussler`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {func}`~scanpy.pp.highly_variable_genes` supersedes {func}`~scanpy.pp.filter_genes_dispersion`, it gives the same results but, by default, expects logarithmized data and doesn’t subset {smaller}`A Wolf`
 
diff --git a/docs/release-notes/1.3.7.md b/docs/release-notes/1.3.7.md
index e69de29bb2..19675fe0e3 100644
--- a/docs/release-notes/1.3.7.md
+++ b/docs/release-notes/1.3.7.md
@@ -0,0 +1,5 @@
+(v1.3.7)=
+### 1.3.7 {small}`2019-01-02`
+
+- API changed from `import scanpy as sc` to `import scanpy.api as sc`.
+- {func}`~scanpy.external.tl.phenograph` wraps the graph clustering package Phenograph {cite:p}`Levine2015` {smaller}`thanks to A Mousa`
diff --git a/docs/release-notes/1.3.8.md b/docs/release-notes/1.3.8.md
index e69de29bb2..f1f6e01282 100644
--- a/docs/release-notes/1.3.8.md
+++ b/docs/release-notes/1.3.8.md
@@ -0,0 +1,5 @@
+(v1.3.8)=
+### 1.3.8 {small}`2019-02-05`
+
+- various documentation and dev process improvements
+- Added {func}`~scanpy.pp.combat` function for batch effect correction {cite:p}`Johnson2006,Leek2012,Pedersen2012` {pr}`398` {smaller}`M Lange`
diff --git a/docs/release-notes/1.4.1.md b/docs/release-notes/1.4.1.md
index 18d689a190..ab503085a4 100644
--- a/docs/release-notes/1.4.1.md
+++ b/docs/release-notes/1.4.1.md
@@ -1,7 +1,7 @@
+(v1.4.1)=
 ### 1.4.1 {small}`2019-04-26`
 
-```{rubric} New functionality
-```
+#### New functionality
 
 - Scanpy has a command line interface again. Invoking it with `scanpy somecommand [args]` calls `scanpy-somecommand [args]`, except for builtin commands (currently `scanpy settings`)  {pr}`604` {smaller}`P Angerer`
 - {func}`~scanpy.datasets.ebi_expression_atlas` allows convenient download of EBI expression atlas {smaller}`I Virshup`
@@ -12,8 +12,7 @@
 - {func}`~scanpy.tl.embedding_density` computes densities on embeddings  {pr}`543` {smaller}`M Luecken`
 - {func}`~scanpy.external.tl.palantir` interfaces Palantir {cite:p}`Setty2019`  {pr}`493` {smaller}`A Mousa`
 
-```{rubric} Code design
-```
+#### Code design
 
 - `.layers` support of scatter plots {smaller}`F Ramirez`
 - fix double-logarithmization in compute of log fold change in {func}`~scanpy.tl.rank_genes_groups` {smaller}`A Muñoz-Rojas`
diff --git a/docs/release-notes/1.4.2.md b/docs/release-notes/1.4.2.md
index f08e21de90..fa3ebf345c 100644
--- a/docs/release-notes/1.4.2.md
+++ b/docs/release-notes/1.4.2.md
@@ -1,19 +1,17 @@
+(v1.4.2)=
 ### 1.4.2 {small}`2019-05-06`
 
-```{rubric} New functionality
-```
+#### New functionality
 
 - {func}`~scanpy.pp.combat` supports additional covariates which may include adjustment variables or biological condition {pr}`618` {smaller}`G Eraslan`
 - {func}`~scanpy.pp.highly_variable_genes` has a `batch_key` option which performs HVG selection in each batch separately to avoid selecting genes that vary strongly across batches {pr}`622` {smaller}`G Eraslan`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - {func}`~scanpy.tl.rank_genes_groups` t-test implementation doesn't return NaN when variance is 0, also changed to scipy's implementation {pr}`621` {smaller}`I Virshup`
 - {func}`~scanpy.tl.umap` with `init_pos='paga'` detects correct `dtype` {smaller}`A Wolf`
 - {func}`~scanpy.tl.louvain` and {func}`~scanpy.tl.leiden` auto-generate `key_added=louvain_R` upon passing `restrict_to`, which was temporarily changed in `1.4.1` {smaller}`A Wolf`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {func}`~scanpy.pp.neighbors` and {func}`~scanpy.tl.umap` got rid of UMAP legacy code and introduced UMAP as a dependency {pr}`576` {smaller}`S Rybakov`
diff --git a/docs/release-notes/1.4.3.md b/docs/release-notes/1.4.3.md
index d034230132..af60127ded 100644
--- a/docs/release-notes/1.4.3.md
+++ b/docs/release-notes/1.4.3.md
@@ -1,11 +1,10 @@
+(v1.4.3)=
 ### 1.4.3 {small}`2019-05-14`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - {func}`~scanpy.pp.neighbors` correctly infers `n_neighbors` again from `params`, which was temporarily broken in `v1.4.2` {smaller}`I Virshup`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {func}`~scanpy.pp.calculate_qc_metrics` is single threaded by default for datasets under 300,000 cells -- allowing cached compilation {pr}`615` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.4.4.md b/docs/release-notes/1.4.4.md
index b82bdaa362..b500c11b6d 100644
--- a/docs/release-notes/1.4.4.md
+++ b/docs/release-notes/1.4.4.md
@@ -1,16 +1,14 @@
+(v1.4.4)=
 ### 1.4.4 {small}`2019-07-20`
 
-```{rubric} New functionality
-```
+#### New functionality
 
 - {mod}`scanpy.get` adds helper functions for extracting data in convenient formats {pr}`619` {smaller}`I Virshup`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Stopped deprecations warnings from AnnData `0.6.22` {smaller}`I Virshup`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {func}`~scanpy.pp.normalize_total` gains param `exclude_highly_expressed`, and `fraction` is renamed to `max_fraction` with better docs {smaller}`A Wolf`
diff --git a/docs/release-notes/1.4.5.md b/docs/release-notes/1.4.5.md
index c56c1270da..44a475ad5d 100644
--- a/docs/release-notes/1.4.5.md
+++ b/docs/release-notes/1.4.5.md
@@ -1,16 +1,15 @@
+(v1.4.5)=
 ### 1.4.5 {small}`2019-12-30`
 
 Please install `scanpy==1.4.5.post3` instead of `scanpy==1.4.5`.
 
-```{rubric} New functionality
-```
+#### New functionality
 
 - {func}`~scanpy.tl.ingest` maps labels and embeddings of reference data to new data {doc}`/tutorials/basics/integrating-data-using-ingest` {pr}`651` {smaller}`S Rybakov, A Wolf`
 - {mod}`~scanpy.queries` recieved many updates including enrichment through [gprofiler] and more advanced biomart queries {pr}`467` {smaller}`I Virshup`
 - {func}`~scanpy.set_figure_params` allows setting `figsize` and accepts `facecolor='white'`, useful for working in dark mode  {smaller}`A Wolf`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {mod}`~scanpy.pp.downsample_counts` now always preserves the dtype of it's input, instead of converting floats to ints {pr}`865` {smaller}`I Virshup`
 - allow specifying a base for {func}`~scanpy.pp.log1p` {pr}`931` {smaller}`G Eraslan`
diff --git a/docs/release-notes/1.4.6.md b/docs/release-notes/1.4.6.md
index 51be1d4569..2ea16c184c 100644
--- a/docs/release-notes/1.4.6.md
+++ b/docs/release-notes/1.4.6.md
@@ -1,19 +1,17 @@
+(v1.4.6)=
 ### 1.4.6 {small}`2020-03-17`
 
-~~~{rubric} Functionality in `external`
-~~~
+#### Functionality in `external`
 
 - {func}`~scanpy.external.tl.sam` self-assembling manifolds {cite:p}`Tarashansky2019` {pr}`903` {smaller}`A Tarashansky`
 - {func}`~scanpy.external.tl.harmony_timeseries` for trajectory inference on discrete time points {pr}`994` {smaller}`A Mousa`
 - {func}`~scanpy.external.tl.wishbone` for trajectory inference (bifurcations) {pr}`1063` {smaller}`A Mousa`
 
-```{rubric} Code design
-```
+#### Code design
 
 - {mod}`~scanpy.pl.violin` now reads `.uns['colors_...']` {pr}`1029` {smaller}`michalk8`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - adapt {func}`~scanpy.tl.ingest` for UMAP 0.4 {pr}`1038` {pr}`1106` {smaller}`S Rybakov`
 - compat with matplotlib 3.1 and 3.2 {pr}`1090` {smaller}`I Virshup, P Angerer`
diff --git a/docs/release-notes/1.5.0.md b/docs/release-notes/1.5.0.md
index b1fff45e03..922e758723 100644
--- a/docs/release-notes/1.5.0.md
+++ b/docs/release-notes/1.5.0.md
@@ -1,29 +1,26 @@
+(v1.5.0)=
 ### 1.5.0 {small}`2020-05-15`
 
 The `1.5.0` release adds a lot of new functionality, much of which takes advantage of {mod}`anndata` updates `0.7.0 - 0.7.2`. Highlights of this release include support for spatial data, dedicated handling of graphs in AnnData, sparse PCA, an interface with scvi, and others.
 
-```{rubric} Spatial data support
-```
+#### Spatial data support
 
 - Basic analysis {doc}`/tutorials/spatial/basic-analysis` and integration with single cell data {doc}`/tutorials/spatial/integration-scanorama` {smaller}`G Palla`
 - {func}`~scanpy.read_visium` read 10x Visium data {pr}`1034` {smaller}`G Palla, P Angerer, I Virshup`
 - {func}`~scanpy.datasets.visium_sge` load Visium data directly from 10x Genomics {pr}`1013` {smaller}`M Mirkazemi, G Palla, P Angerer`
 - {func}`~scanpy.pl.spatial` plot spatial data {pr}`1012` {smaller}`G Palla, P Angerer`
 
-```{rubric} New functionality
-```
+#### New functionality
 
 - Many functions, like {func}`~scanpy.pp.neighbors` and {func}`~scanpy.tl.umap`, now store cell-by-cell graphs in {attr}`~anndata.AnnData.obsp` {pr}`1118` {smaller}`S Rybakov`
 - {func}`~scanpy.pp.scale` and {func}`~scanpy.pp.log1p` can be used on any element in {attr}`~anndata.AnnData.layers` or {attr}`~anndata.AnnData.obsm` {pr}`1173` {smaller}`I Virshup`
 
-```{rubric} External tools
-```
+#### External tools
 
 - `scanpy.external.pp.scvi` for preprocessing with scVI {pr}`1085` {smaller}`G Xing`
 - Guide for using `Scanpy in R` {pr}`1186` {smaller}`L Zappia`
 
-```{rubric} Performance
-```
+#### Performance
 
 - {func}`~scanpy.pp.pca` now uses efficient implicit centering for sparse matrices. This can lead to signifigantly improved performance for large datasets {pr}`1066` {smaller}`A Tarashansky`
 - {func}`~scanpy.tl.score_genes` now has an efficient implementation for sparse matrices with missing values {pr}`1196` {smaller}`redst4r`.
@@ -32,16 +29,14 @@ The `1.5.0` release adds a lot of new functionality, much of which takes advanta
 The new {func}`~scanpy.pp.pca` implementation can result in slightly different results for sparse matrices. See the pr ({pr}`1066`) and documentation for more info.
 ```
 
-```{rubric} Code design
-```
+#### Code design
 
 - {func}`~scanpy.pl.stacked_violin` can now be used as a subplot {pr}`1084` {smaller}`P Angerer`
 - {func}`~scanpy.tl.score_genes` has improved logging {pr}`1119` {smaller}`G Eraslan`
 - {func}`~scanpy.pp.scale` now saves mean and standard deviation in the {attr}`~anndata.AnnData.var` {pr}`1173` {smaller}`A Wolf`
 - {func}`~scanpy.external.tl.harmony_timeseries` {pr}`1091` {smaller}`A Mousa`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - {func}`~scanpy.pp.combat` now works when `obs_names` aren't unique. {pr}`1215` {smaller}`I Virshup`
 - {func}`~scanpy.pp.scale` can now be used on dense arrays without centering {pr}`1160` {smaller}`simonwm`
diff --git a/docs/release-notes/1.5.1.md b/docs/release-notes/1.5.1.md
index 215fe3b3cc..f7c18bb73f 100644
--- a/docs/release-notes/1.5.1.md
+++ b/docs/release-notes/1.5.1.md
@@ -1,7 +1,7 @@
+(v1.5.1)=
 ### 1.5.1 {small}`2020-05-21`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Fixed a bug in {func}`~scanpy.pp.pca`, where `random_state` did not have an effect for sparse input {pr}`1240` {smaller}`I Virshup`
 - Fixed docstring in {func}`~scanpy.pp.pca` which included an unused argument {pr}`1240` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.6.0.md b/docs/release-notes/1.6.0.md
index fe40597a81..19b227fc05 100644
--- a/docs/release-notes/1.6.0.md
+++ b/docs/release-notes/1.6.0.md
@@ -1,9 +1,9 @@
+(v1.6.0)=
 ### 1.6.0 {small}`2020-08-15`
 
 This release includes an overhaul of {func}`~scanpy.pl.dotplot`, {func}`~scanpy.pl.matrixplot`, and {func}`~scanpy.pl.stacked_violin` ({pr}`1210` {smaller}`F Ramirez`), and of the internals of {func}`~scanpy.tl.rank_genes_groups` ({pr}`1156` {smaller}`S Rybakov`).
 
-~~~{rubric} Overhaul of {func}`~scanpy.pl.dotplot`, {func}`~scanpy.pl.matrixplot`, and {func}`~scanpy.pl.stacked_violin` {pr}`1210` {smaller}`F Ramirez`
-~~~
+#### Overhaul of {func}`~scanpy.pl.dotplot`, {func}`~scanpy.pl.matrixplot`, and {func}`~scanpy.pl.stacked_violin` {pr}`1210` {smaller}`F Ramirez`
 
 - An overhauled tutorial {doc}`/tutorials/plotting/core`.
 
@@ -38,8 +38,7 @@ This release includes an overhaul of {func}`~scanpy.pl.dotplot`, {func}`~scanpy.
   > - The linewidth of the violin plots is thinner.
   > - Removed the tics for the y-axis as they tend to overlap with each other. Using the style method they can be displayed if needed.
 
-```{rubric} Additions
-```
+#### Additions
 
 - {func}`~anndata.concat` is now exported from scanpy, see {doc}`anndata:concatenation` for more info. {pr}`1338` {smaller}`I Virshup`
 - Added highly variable gene selection strategy from Seurat v3 {pr}`1204` {smaller}`A Gayoso`
@@ -49,8 +48,7 @@ This release includes an overhaul of {func}`~scanpy.pl.dotplot`, {func}`~scanpy.
 - Optional tie correction for the `'wilcoxon'` method in {func}`~scanpy.tl.rank_genes_groups` {pr}`1330`  {smaller}`S Rybakov`
 - Use `sinfo` for {func}`~scanpy.logging.print_versions` and add {func}`~scanpy.logging.print_header` to do what it previously did. {pr}`1338` {smaller}`I Virshup` {pr}`1373`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Avoid warning in {func}`~scanpy.tl.rank_genes_groups` if 't-test' is passed {pr}`1303` {smaller}`A Wolf`
 - Restrict sphinx version to \<3.1, >3.0 {pr}`1297`  {smaller}`I Virshup`
diff --git a/docs/release-notes/1.7.0.md b/docs/release-notes/1.7.0.md
index 7ea8c8c0c5..0c3f77f4ce 100644
--- a/docs/release-notes/1.7.0.md
+++ b/docs/release-notes/1.7.0.md
@@ -1,7 +1,7 @@
+(v1.7.0)=
 ### 1.7.0 {small}`2021-02-03`
 
-```{rubric} Features
-```
+#### Features
 
 - Add new 10x Visium datasets to {func}`~scanpy.datasets.visium_sge` {pr}`1473` {smaller}`G Palla`
 - Enable download of source image for 10x visium datasets in {func}`~scanpy.datasets.visium_sge` {pr}`1506` {smaller}`H Spitzer`
@@ -14,8 +14,7 @@
 - Added `na_color` and `na_in_legend` keyword arguments to {func}`~scanpy.pl.embedding` plots. Allows specifying color for missing or filtered values in plots like {func}`~scanpy.pl.umap` or {func}`~scanpy.pl.spatial` {pr}`1356` {smaller}`I Virshup`
 - {func}`~scanpy.pl.embedding` plots now support passing `dict` of `{cluster_name: cluster_color, ...}` for palette argument  {pr}`1392` {smaller}`I Virshup`
 
-```{rubric} External tools (new)
-```
+#### External tools (new)
 
 - Add [Scanorama](https://github.com/brianhie/scanorama) integration to scanpy external API ({func}`~scanpy.external.pp.scanorama_integrate`, {cite:t}`Hie2019`) {pr}`1332` {smaller}`B Hie`
 - Scrublet {cite:p}`Wolock2019` integration: {func}`~scanpy.pp.scrublet`, {func}`~scanpy.pp.scrublet_simulate_doublets`, and plotting method {func}`~scanpy.pl.scrublet_score_distribution` {pr}`1476` {smaller}`J Manning`
@@ -23,8 +22,7 @@
 - Added [scirpy](https://github.com/icbi-lab/scirpy) (sc-AIRR analysis) to ecosystem page {pr}`1453` {smaller}`G Sturm`
 - Added [scvi-tools](https://scvi-tools.org) to ecosystem page {pr}`1421` {smaller}`A Gayoso`
 
-```{rubric} External tools (changes)
-```
+#### External tools (changes)
 
 - Updates for {func}`~scanpy.external.tl.palantir` and {func}`~scanpy.external.tl.palantir_results` {pr}`1245` {smaller}`A Mousa`
 - Fixes to {func}`~scanpy.external.tl.harmony_timeseries` docs {pr}`1248` {smaller}`A Mousa`
@@ -32,20 +30,17 @@
 - Deprecate `scanpy.external.pp.scvi` {pr}`1554` {smaller}`G Xing`
 - Updated default params of {func}`~scanpy.external.tl.sam` to work with larger data {pr}`1540` {smaller}`A Tarashansky`
 
-```{rubric} Documentation
-```
+#### Documentation
 
 - {ref}`New contribution guide <contribution-guide>` {pr}`1544` {smaller}`I Virshup`
 - `zsh` installation instructions {pr}`1444` {smaller}`P Angerer`
 
-```{rubric} Performance
-```
+#### Performance
 
 - Speed up {func}`~scanpy.read_10x_h5` {pr}`1402` {smaller}`P Weiler`
 - Speed ups for {func}`~scanpy.get.obs_df` {pr}`1499` {smaller}`F Ramirez`
 
-```{rubric} Bugfixes
-```
+#### Bugfixes
 
 - Consistent fold-change, fractions calculation for filter_rank_genes_groups {pr}`1391` {smaller}`S Rybakov`
 - Fixed bug where `score_genes` would error if one gene was passed {pr}`1398` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.7.1.md b/docs/release-notes/1.7.1.md
index 0e536ca848..c4d28b0455 100644
--- a/docs/release-notes/1.7.1.md
+++ b/docs/release-notes/1.7.1.md
@@ -1,12 +1,11 @@
+(v1.7.1)=
 ### 1.7.1 {small}`2021-02-24`
 
-```{rubric} Documentation
-```
+#### Documentation
 
 - More twitter handles for core devs {pr}`1676` {smaller}`G Eraslan`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - {func}`~scanpy.tl.dendrogram` use `1 - correlation` as distance matrix to compute the dendrogram {pr}`1614` {smaller}`F Ramirez`
 - Fixed {func}`~scanpy.get.obs_df`/ {func}`~scanpy.get.var_df` erroring when `keys` not passed {pr}`1637` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.7.2.md b/docs/release-notes/1.7.2.md
index 90e90c5cc7..816819b3d2 100644
--- a/docs/release-notes/1.7.2.md
+++ b/docs/release-notes/1.7.2.md
@@ -1,15 +1,14 @@
+(v1.7.2)=
 ### 1.7.2 {small}`2021-04-07`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - {func}`scanpy.logging.print_versions` now works when `python<3.8` {pr}`1691` {smaller}`I Virshup`
 - {func}`scanpy.pp.regress_out` now uses `joblib` as the parallel backend, and should stop oversubscribing threads {pr}`1694` {smaller}`I Virshup`
 - {func}`scanpy.pp.highly_variable_genes` with `flavor="seurat_v3"` now returns correct gene means and -variances when used with `batch_key` {pr}`1732` {smaller}`J Lause`
 - {func}`scanpy.pp.highly_variable_genes` now throws a warning instead of an error when non-integer values are passed for method `"seurat_v3"`. The check can be skipped by passing `check_values=False`. {pr}`1679` {smaller}`G Palla`
 
-```{rubric} Ecosystem
-```
+#### Ecosystem
 
 - Added `triku` a feature selection method to the ecosystem page {pr}`1722` {smaller}`AM Ascensión`
 - Added `dorothea` and `progeny` to the ecosystem page {pr}`1767` {smaller}`P Badia-i-Mompel`
diff --git a/docs/release-notes/1.8.0.md b/docs/release-notes/1.8.0.md
index 2ec0a03496..f2e06e8371 100644
--- a/docs/release-notes/1.8.0.md
+++ b/docs/release-notes/1.8.0.md
@@ -1,46 +1,42 @@
+(v1.8.0)=
 ### 1.8.0 {small}`2021-06-28`
 
-```{rubric} Metrics module
-```
+#### Metrics module
 
 - Added {mod}`scanpy.metrics` module!
 
-  > - Added {func}`scanpy.metrics.gearys_c` for spatial autocorrelation {pr}`915` {smaller}`I Virshup`
-  > - Added {func}`scanpy.metrics.morans_i` for global spatial autocorrelation {pr}`1740` {smaller}`I Virshup, G Palla`
-  > - Added {func}`scanpy.metrics.confusion_matrix` for comparing labellings {pr}`915` {smaller}`I Virshup`
+  - Added {func}`scanpy.metrics.gearys_c` for spatial autocorrelation {pr}`915` {smaller}`I Virshup`
+  - Added {func}`scanpy.metrics.morans_i` for global spatial autocorrelation {pr}`1740` {smaller}`I Virshup, G Palla`
+  - Added {func}`scanpy.metrics.confusion_matrix` for comparing labellings {pr}`915` {smaller}`I Virshup`
 
-```{rubric} Features
-```
+#### Features
 
 - Added `layer` and `copy` kwargs to {func}`~scanpy.pp.normalize_total` {pr}`1667` {smaller}`I Virshup`
 - Added `vcenter` and `norm` arguments to the plotting functions {pr}`1551` {smaller}`G Eraslan`
 - Standardized and expanded available arguments to the `sc.pl.rank_genes_groups*` family of functions. {pr}`1529` {smaller}`F Ramirez` {smaller}`I Virshup`
-  \- See examples sections of {func}`~scanpy.pl.rank_genes_groups_dotplot` and {func}`~scanpy.pl.rank_genes_groups_matrixplot` for demonstrations.
+  - See examples sections of {func}`~scanpy.pl.rank_genes_groups_dotplot` and {func}`~scanpy.pl.rank_genes_groups_matrixplot` for demonstrations.
 - {func}`scanpy.tl.tsne` now supports the metric argument and records the passed parameters {pr}`1854` {smaller}`I Virshup`
 - {func}`scanpy.pl.scrublet_score_distribution` now uses same API as other scanpy functions for saving/ showing plots {pr}`1741` {smaller}`J Manning`
 
-```{rubric} Ecosystem
-```
+#### Ecosystem
 
 - Added [Cubé](https://github.com/connerlambden/Cube) to ecosystem page {pr}`1878` {smaller}`C Lambden`
 - Added `triku` a feature selection method to the ecosystem page {pr}`1722` {smaller}`AM Ascensión`
 - Added `dorothea` and `progeny` to the ecosystem page {pr}`1767` {smaller}`P Badia-i-Mompel`
 
-```{rubric} Documentation
-```
+#### Documentation
 
 - Added {doc}`/community` page to docs {pr}`1856` {smaller}`I Virshup`
 - Added rendered examples to many plotting functions {issue}`1664` {smaller}`A Schaar` {smaller}`L Zappia` {smaller}`bio-la` {smaller}`L Hetzel` {smaller}`L Dony` {smaller}`M Buttner` {smaller}`K Hrovatin` {smaller}`F Ramirez` {smaller}`I Virshup` {smaller}`LouisK92` {smaller}`mayarali`
 - Integrated [DocSearch], a find-as-you-type documentation index search. {pr}`1754` {smaller}`P Angerer`
-- - Reorganized reference docs {pr}`1753` {smaller}`I Virshup`
+- Reorganized reference docs {pr}`1753` {smaller}`I Virshup`
 - Clarified docs issues for {func}`~scanpy.pp.neighbors`,
   {func}`~scanpy.tl.diffmap`, {func}`~scanpy.pp.calculate_qc_metrics` {pr}`1680` {smaller}`G Palla`
 - Fixed typos in grouped plot doc-strings {pr}`1877` {smaller}`C Rands`
 - Extended examples for differential expression plotting. {pr}`1529` {smaller}`F Ramirez`
-  \- See {func}`~scanpy.pl.rank_genes_groups_dotplot` or {func}`~scanpy.pl.rank_genes_groups_matrixplot` for examples.
+  - See {func}`~scanpy.pl.rank_genes_groups_dotplot` or {func}`~scanpy.pl.rank_genes_groups_matrixplot` for examples.
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Fix {func}`scanpy.pl.paga_path` `TypeError` with recent versions of anndata {pr}`1047` {smaller}`P Angerer`
 - Fix detection of whether IPython is running {pr}`1844` {smaller}`I Virshup`
@@ -51,14 +47,12 @@
 - {func}`scanpy.pl.rank_genes_groups_violin` now works for `raw=False` {pr}`1669` {smaller}`M van den Beek`
 - {func}`scanpy.pl.dotplot` now uses `smallest_dot` argument correctly {pr}`1771` {smaller}`S Flemming`
 
-```{rubric} Development processes
-```
+#### Development processes
 
 - Switched to [flit] for building and deploying the package, a simple tool with an easy to understand command line interface and metadata {pr}`1527` {smaller}`P Angerer`
 - Use [pre-commit](https://pre-commit.com) for style checks {pr}`1684` {pr}`1848` {smaller}`L Heumos` {smaller}`I Virshup`
 
-```{rubric} Deprecations
-```
+#### Deprecations
 
 - Dropped support for Python 3.6. [More details here](https://numpy.org/neps/nep-0029-deprecation_policy.html). {pr}`1897` {smaller}`I Virshup`
 - Deprecated `layers` and `layers_norm` kwargs to {func}`~scanpy.pp.normalize_total` {pr}`1667` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.8.1.md b/docs/release-notes/1.8.1.md
index 6569748ab4..befef210e5 100644
--- a/docs/release-notes/1.8.1.md
+++ b/docs/release-notes/1.8.1.md
@@ -1,7 +1,7 @@
+(v1.8.1)=
 ### 1.8.1 {small}`2021-07-07`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Fixed reproducibility of {func}`scanpy.tl.score_genes`. Calculation and output is now float64 type.  {pr}`1890` {smaller}`I Kucinski`
 - Workarounds for some changes/ bugs in pandas 1.3 {pr}`1918` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.8.2.md b/docs/release-notes/1.8.2.md
index 8cae543c03..418cae9944 100644
--- a/docs/release-notes/1.8.2.md
+++ b/docs/release-notes/1.8.2.md
@@ -1,12 +1,11 @@
+(v1.8.2)=
 ### 1.8.2 {small}`2021-11-3`
 
-```{rubric} Docs
-```
+#### Docs
 
 - Update conda installation instructions {pr}`1974` {smaller}`L Heumos`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Fix plotting after {func}`scanpy.tl.filter_rank_genes_groups` {pr}`1942` {smaller}`S Rybakov`
 - Fix `use_raw=None` using {attr}`anndata.AnnData.var_names` if {attr}`anndata.AnnData.raw`
@@ -14,7 +13,6 @@
 - Fix compatibility with UMAP 0.5.2 {pr}`2028` {smaller}`L Mcinnes`
 - Fixed non-determinism in {func}`scanpy.pl.paga` node positions {pr}`1922` {smaller}`I Virshup`
 
-```{rubric} Ecosystem
-```
+#### Ecosystem
 
 - Added PASTE (a tool to align and integrate spatial transcriptomics data) to scanpy ecosystem.
diff --git a/docs/release-notes/1.9.0.md b/docs/release-notes/1.9.0.md
index 977489a34b..c89a1b704b 100644
--- a/docs/release-notes/1.9.0.md
+++ b/docs/release-notes/1.9.0.md
@@ -1,13 +1,12 @@
+(v1.9.0)=
 ### 1.9.0 {small}`2022-04-01`
 
-```{rubric} Tutorials
-```
+#### Tutorials
 
 - New tutorial on the usage of Pearson Residuals: {doc}`/tutorials/experimental/pearson_residuals` {smaller}`J Lause, G Palla`
 - [Materials](https://github.com/scverse/scanpy-tutorials/tree/master/scanpy_workshop) and [recordings](https://www.youtube.com/playlist?list=PL4rcQcNPLZxWQQH7LlRBMkAo5NWuHX1e3) for Scanpy workshops by Maren Büttner
 
-```{rubric} Experimental module
-```
+#### Experimental module
 
 - Added {mod}`scanpy.experimental` module! Currently contains functionality related to pearson residuals in {mod}`scanpy.experimental.pp` {pr}`1715` {smaller}`J Lause, G Palla, I Virshup`. This includes:
 
@@ -16,8 +15,7 @@
   - {func}`~scanpy.experimental.pp.normalize_pearson_residuals_pca` for Pearson Residuals normalization and dimensionality reduction with PCA
   - {func}`~scanpy.experimental.pp.recipe_pearson_residuals` for Pearson Residuals normalization, HVG selection and dimensionality reduction with PCA
 
-```{rubric} Features
-```
+#### Features
 
 - {func}`~scanpy.tl.filter_rank_genes_groups` now allows to filter with absolute values of log fold change {pr}`1649` {smaller}`S Rybakov`
 - `_choose_representation` now subsets the provided representation to n_pcs, regardless of the name of the provided representation (should affect mostly {func}`~scanpy.pp.neighbors`)  {pr}`2179`  {smaller}`I Virshup` {smaller}`PG Majev`
@@ -29,8 +27,7 @@
 - Embedding plots now have a `dimensions` argument, which lets users select which dimensions of their embedding to plot and uses the same broadcasting rules as other arguments {pr}`1538` {smaller}`I Virshup`
 - {func}`~scanpy.logging.print_versions` now uses `session_info` {pr}`2089` {smaller}`P Angerer` {smaller}`I Virshup`
 
-```{rubric} Ecosystem
-```
+#### Ecosystem
 
 Multiple packages have been added to our ecosystem page, including:
 
@@ -38,8 +35,7 @@ Multiple packages have been added to our ecosystem page, including:
 - [dandelion](https://github.com/zktuong/dandelion) for B-cell receptor analysis {pr}`1953` {smaller}`Z Tuong`
 - [CIARA](https://github.com/ScialdoneLab/CIARA_python) a feature selection tools for identifying rare cell types {pr}`2175` {smaller}`M Stock`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Fixed finding variables with `use_raw=True` and `basis=None` in {func}`scanpy.pl.scatter` {pr}`2027` {smaller}`E Rice`
 - Fixed {func}`scanpy.pp.scrublet` to address {issue}`1957` {smaller}`FlMai` and ensure raw counts are used for simulation
diff --git a/docs/release-notes/1.9.1.md b/docs/release-notes/1.9.1.md
index dcaa2a77cb..38bf8922cc 100644
--- a/docs/release-notes/1.9.1.md
+++ b/docs/release-notes/1.9.1.md
@@ -1,8 +1,7 @@
+(v1.9.1)=
 ### 1.9.1 {small}`2022-04-05`
 
-
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - {func}`~scanpy.pp.normalize_total` works when Dask is not installed {pr}`2209` {smaller}`R Cannoodt`
 - Fix embedding plots by bumping matplotlib dependency to version 3.4 {pr}`2212` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.9.2.md b/docs/release-notes/1.9.2.md
index c2f5b647da..6b50147f43 100644
--- a/docs/release-notes/1.9.2.md
+++ b/docs/release-notes/1.9.2.md
@@ -1,7 +1,7 @@
+(v1.9.2)=
 ### 1.9.2 {small}`2023-02-16`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * {func}`~scanpy.pp.highly_variable_genes` `layer` argument now works in tandem with `batches` {pr}`2302` {smaller}`D Schaumont`
 * {func}`~scanpy.pp.highly_variable_genes` with `flavor='cell_ranger'` now handles the case in {issue}`2230` where the number of calculated dispersions is less than `n_top_genes` {pr}`2231` {smaller}`L Zappia`
diff --git a/docs/release-notes/1.9.3.md b/docs/release-notes/1.9.3.md
index 83dd8c8454..bec9964182 100644
--- a/docs/release-notes/1.9.3.md
+++ b/docs/release-notes/1.9.3.md
@@ -1,6 +1,6 @@
+(v1.9.3)=
 ### 1.9.3 {small}`2023-03-02`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Variety of fixes against pandas 2.0.0rc0 {pr}`2434` {smaller}`I Virshup`
diff --git a/docs/release-notes/1.9.4.md b/docs/release-notes/1.9.4.md
index 51ca54257b..daf34fa968 100644
--- a/docs/release-notes/1.9.4.md
+++ b/docs/release-notes/1.9.4.md
@@ -1,7 +1,7 @@
+(v1.9.4)=
 ### 1.9.4 {small}`2023-08-24`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 * Support scikit-learn 1.3 {pr}`2515` {smaller}`P Angerer`
 * Deal with `None` value vanishing from things like `.uns['log1p']` {pr}`2546` {smaller}`SP Shen`
diff --git a/docs/release-notes/1.9.5.md b/docs/release-notes/1.9.5.md
index c674da556d..cb96112005 100644
--- a/docs/release-notes/1.9.5.md
+++ b/docs/release-notes/1.9.5.md
@@ -1,6 +1,6 @@
+(v1.9.5)=
 ### 1.9.5 {small}`2023-09-08`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Remove use of deprecated `dtype` argument to AnnData constructor {pr}`2658` {smaller}`Isaac Virshup`
diff --git a/docs/release-notes/1.9.6.md b/docs/release-notes/1.9.6.md
index ca8d43e498..4e26980a54 100644
--- a/docs/release-notes/1.9.6.md
+++ b/docs/release-notes/1.9.6.md
@@ -1,7 +1,7 @@
+(v1.9.6)=
 ### 1.9.6 {small}`2023-10-31`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Allow {func}`scanpy.pl.scatter` to accept a {class}`str` palette name {pr}`2571` {smaller}`P Angerer`
 - Make {func}`scanpy.external.tl.palantir` compatible with palantir >=1.3 {pr}`2672` {smaller}`DJ Otto`
diff --git a/docs/release-notes/1.9.7.md b/docs/release-notes/1.9.7.md
index 927a57dcf7..0b98ac3d80 100644
--- a/docs/release-notes/1.9.7.md
+++ b/docs/release-notes/1.9.7.md
@@ -1,7 +1,7 @@
+(v1.9.7)=
 ### 1.9.7 {small}`2024-01-25`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Fix handling of numpy array palettes (e.g. after write-read cycle) {pr}`2734` {smaller}`P Angerer`
 - Specify correct version of `matplotlib` dependency {pr}`2733` {smaller}`P Fisher`
diff --git a/docs/release-notes/1.9.8.md b/docs/release-notes/1.9.8.md
index c2289144a6..d7e65ec12a 100644
--- a/docs/release-notes/1.9.8.md
+++ b/docs/release-notes/1.9.8.md
@@ -1,6 +1,6 @@
+(v1.9.8)=
 ### 1.9.8 {small}`2024-01-26`
 
-```{rubric} Bug fixes
-```
+#### Bug fixes
 
 - Fix handling of numpy array palettes for old numpy versions {pr}`2832` {smaller}`P Angerer`