qupath · alanocallaghan · Feb 12, 2026
diff --git a/conf.py b/conf.py
@@ -40,7 +40,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', "env", ".env", ".venv", "README.md"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -93,12 +93,14 @@
     "tasklist",
 ]
 
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 3
 
 highlight_language = 'groovy'
 
 html_logo = 'docs/images/qupath_128.png'
 
-html_favicon = 'docs/images/QuPath.ico'
+html_favicon = 'docs/images/qupath.ico'
 
 # Variables for current QuPath version
 release = '0.6.0'

diff --git a/docs/concepts/object_hierarchy.md b/docs/concepts/object_hierarchy.md
@@ -2,11 +2,6 @@
 
 {doc}`Objects <objects>` in QuPath need to be stored somewhere - and that place is the *object hierarchy*.
 
-:::{important}
-The hierarchy behavior has changed in v0.2.0! <br />
-If you are familiar with the old behavior, be sure to read {ref}`Differences from QuPath v0.1.2`.
-:::
-
 The name comes from the fact that the objects are all stored in a hierarchical, tree-like structure.
 This is achieved by each object having having a reference to:
 
@@ -128,8 +123,8 @@ This is crucial because the `PathObjectHierarchy` class uses spatial caching and
 
 In QuPath v0.1.2, the hierarchy was resolved automatically (without asking) and this was *essential* to make sense of the measurements.
 
-The behavior of the object hierarchy has changed in QuPath v0.2.0, with the aim of making the software faster, more powerful, and more intuitive.
-In v0.2.0 the details of the hierarchy can very often be ignored, and exists only to support sophisticated workflows where it might be needed.
+The behavior of the object hierarchy changed in QuPath v0.2.0, with the aim of making the software faster, more powerful, and more intuitive.
+In v0.2.0 and onwards, the details of the hierarchy can very often be ignored, and exists only to support sophisticated workflows where it might be needed.
 
 [This blog post](https://petebankhead.github.io/qupath/2019/11/17/changing-the-hierarchy.html) describes the reasons why it changed.
 To read about the earlier behavior see [Object hierarchies](https://github.com/qupath/qupath/wiki/Object-hierarchies) on the old wiki.
diff --git a/docs/deep/stardist.md b/docs/deep/stardist.md
@@ -403,7 +403,7 @@ def stardist = StarDist2D.builder(pathModel)
 
 Furthermore, we can use preprocessing to convert images to become more compatible with pretrained StarDist models.
 For example, `dsb2018_heavy_augment.pb` works very well for fluorescence microscopy images, but only supports a single input channel.
-However, by applying {ref}`color deconvolution<Separating stains>` as preprocessing we can convert a 3-channel brightfield image to a single-channel image that *looks* much more like a fluorescence image.
+However, by applying {ref}`color deconvolution<docs/tutorials/separating_stains:Separating stains>` as preprocessing we can convert a 3-channel brightfield image to a single-channel image that *looks* much more like a fluorescence image.
 If needed, we can add extra things like filters to reduce noise as well.
 
 ```groovy

diff --git a/docs/deep/wsinfer.md b/docs/deep/wsinfer.md
@@ -153,7 +153,7 @@ wsinfer
 
 The QuPath WSInfer extension is scriptable, which makes it much easier to apply across multiple images.
 
-When a model is run, the command parameters are stored in the [workflow](workflows) so that a [script can be generated automatically](workflows-to-scripts).
+When a model is run, the command parameters are stored in the [workflow](docs/scripting/workflows:Workflows) so that a [script can be generated automatically](docs/scripting/workflows_to_scripts:Workflows to scripts).
 
 An example script would be
 

diff --git a/docs/intro/installation.md b/docs/intro/installation.md
@@ -23,7 +23,7 @@ QuPath requires 64-bit Windows.
 Running QuPath on 32-bit Windows is not supported.
 :::
 
-#### Installing the Windows .msi package
+### Installing the Windows .msi package
 Double-click to launch the installer.
 
 Windows tries to protect you from software it does not know, so you'll probably see a scary-looking warning whenever the QuPath installer is first run:
@@ -57,7 +57,7 @@ If the QuPath installer does not start at all, you may not have administrator pr
 Try downloading the `.zip` file instead, which should not need such privileges.
 :::
 
-#### Installing the Windows .zip package
+### Installing the Windows .zip package
 Right-click on the .zip file and choose to extract all the contents.
 This should give you a normal folder containing QuPath's files.
 
@@ -70,7 +70,7 @@ The first time you try this, you might see similar warning dialogs to those show
 On Windows, you can either run `QuPath.exe` or `QuPath (console).exe`.
 
 The difference is that `QuPath (console).exe` will also open a small window that contains QuPath's log messages.
-The console can be useful for debugging problems, or when using the {ref}`Command line`.
+The console can be useful for debugging problems, or when using the {ref}`docs/advanced/command_line:Command line`.
 :::
 
 :::{admonition} QuPath won't launch!
@@ -170,4 +170,4 @@ QuPath for Linux was compiled on Ubuntu - with best efforts made to include all
 
 ## Running from source
 
-If all else fails, you can try [](building) - which should work on Windows, macOS and Linux.
+If all else fails, you can try [](building) - which should work on Windows, macOS and Linux.
diff --git a/docs/reference/building.md b/docs/reference/building.md
@@ -65,7 +65,7 @@ Example of command line build success
 **That's it!**
 You can find QuPath inside the `./build/dist/` subdirectory.
 
-If it *didn't* go so well, check out [](#Troubleshooting).
+If it *didn't* go so well, check out {ref}`docs/reference/building:Troubleshooting`.
 
 :::{admonition} Which Java version do I need?
 :class: tip
@@ -181,7 +181,7 @@ Check out the docs associated with the specific version if this is the case.
 (building-qupath-fiji)=
 ## Building with Fiji
 By default, QuPath embeds a version of [ImageJ](https://imagej.net/software/imagej/).
-This allows you to [send image regions to ImageJ, and even use custom ImageJ plugins](ImageJ).
+This allows you to [send image regions to ImageJ, and even use custom ImageJ plugins](docs/advanced/imagej:ImageJ).
 
 [Fiji](https://fiji.sc) is a special distribution of ImageJ that contains a *lot* of custom plugins, and many extra features and other changes.
 

diff --git a/docs/reference/faqs.md b/docs/reference/faqs.md
@@ -131,7 +131,7 @@ It is designed so that other machine learning libraries could potentially be use
 
 ### Why do I see a warning when I try to install QuPath?
 
-See {ref}`Installation`.
+See {ref}`docs/intro/installation:Installation`.
 
 (set-max-memory)=
 
@@ -185,11 +185,11 @@ See {doc}`../intro/formats` for details about which formats are supported, and t
 ### {menuselection}`File --> Open URI...` doesn't work for me!
 
 {menuselection}`File --> Open URI...` requires a compatible extension needs to read images hosted remotely.
-See {ref}`Open URI` for more details.
+See {ref}`docs/intro/formats:Open URI` for more details.
 
 ### Why does my image open but look weird?
 
-See {ref}`Why can't QuPath open my image?`
+See {ref}`docs/reference/faqs:Why can't QuPath open my image?`
 
 ### Is it possible to view slide labels?
 

diff --git a/docs/reference/tips_and_tricks.md b/docs/reference/tips_and_tricks.md
diff --git a/docs/tutorials/density_maps.md b/docs/tutorials/density_maps.md
@@ -20,7 +20,7 @@ In some cases, density maps can even be a replacement for {doc}`pixel_classifica
 
 :::{warning}
 Like most commands in QuPath, Density Maps are currently calculated only in 2D.
-And, like many other commands, you should create Density Maps within a {ref}`project <Projects>` if you want to reuse them later.
+And, like many other commands, you should create Density Maps within a {ref}`project <docs/tutorials/projects:Projects>` if you want to reuse them later.
 :::
 
 ## Getting started with density maps
@@ -61,7 +61,7 @@ Hovering your mouse over any option should provide some help text.
 
 The {guilabel}`Object type` and {guilabel}`Main class` define which objects will contribute to the density map in some way.
 
-Left to the defaults, the density map will make use of all detection objects (which {ref}`includes cells <types of object>`) regardless of their classification.
+Left to the defaults, the density map will make use of all detection objects (which {ref}`includes cells <docs/concepts/objects:types of object>`) regardless of their classification.
 
 If I choose the {guilabel}`Main class` to be **Tumor**, then the density map will *only* include detections that are classified as **Tumor**.
 

diff --git a/docs/tutorials/separating_stains.md b/docs/tutorials/separating_stains.md
@@ -16,7 +16,7 @@
 QuPath supports images of different kinds.
 
 Some commands will work on almost any kind of image without complaint, while some need to know a bit more about the image.
-This information can be provided by {ref}`setting the image type <Setting the image type>`.
+This information can be provided by {ref}`setting the image type <docs/starting/first_steps:Setting the image type>`.
 
 Typically the type will be either *Brightfield* or *Fluorescence*.
 
@@ -118,7 +118,7 @@ The stain vectors are key to color deconvolution.
 They ought to give a normalized representation of the color of each 'pure' stain in the image, without regard for staining intensity.
 A similar color vector characterizing the background encodes what 'no stain' looks like, and also plays an important role in the calculations.
 
-When {ref}`setting the image type <Setting the image type>` to *Brightfield (H&E)*, *Brightfield (H-DAB)* or *Brightfield (Other)*, QuPath will set default stain vectors to characterize hematoxylin, eosin or DAB.
+When {ref}`setting the image type <docs/starting/first_steps:Setting the image type>` to *Brightfield (H&E)*, *Brightfield (H-DAB)* or *Brightfield (Other)*, QuPath will set default stain vectors to characterize hematoxylin, eosin or DAB.
 However, you may see better results with some commands (e.g. *Cell detection*) by setting the stain and background vectors explicitly to better match the actual staining in the image.
 
 This requires two steps:

diff --git a/index.md b/index.md
@@ -13,7 +13,7 @@ To read up on the latest changes, check out the [release notes](https://github.c
 ## Quick links
 
 Can't install QuPath?
-: Check out {ref}`installation` for instructions & solutions to common problems
+: Check out {ref}`docs/intro/installation:installation` for instructions & solutions to common problems
 
 Images won't open?
 : See {ref}`supported-image-formats` to find out which formats *should* work - and ways to increase this.