napari · psobolewskiPhD · Jan 23, 2024 · Dec 7, 2023 · Jan 22, 2024 · Jan 22, 2024
diff --git a/docs/community/governance.md b/docs/community/governance.md
@@ -42,7 +42,7 @@ among other possibilities. Any community member can become a contributor, and
 all are encouraged to do so. By contributing to the project, community members
 can directly help to shape its future.
 
-Contributors are encouraged to read the [contributing guide](napari-contributing).
+Contributors are encouraged to read the [contributing guide](contributing-code).
 
 ### Core developers
 

diff --git a/docs/community/index.md b/docs/community/index.md
@@ -7,7 +7,7 @@ examples, you are welcome to help develop and improve napari.
 
 To ask questions and interact with the team, you can join our
 [zulip chat](https://napari.zulipchat.com/login/) or participate in our
-[meetings](./meeting_schedule).
+[meetings](meeting-schedule).
 
 If you are interested in contributing, check out our
-[contributing guide](../developers/index).
+[contributing guide](contributing).
diff --git a/docs/community/meeting_schedule.md b/docs/community/meeting_schedule.md
@@ -1,3 +1,5 @@
+(meeting-schedule)=
+
 # Meeting schedule
 
 We hold regular meetings, the timings of which are available on our [public calendar](https://calendar.google.com/calendar/embed?src=c_35r93ec6vtp8smhm7dv5uot0v4%40group.calendar.google.com).

diff --git a/docs/developers/architecture/napari_models.md b/docs/developers/architecture/napari_models.md
@@ -29,7 +29,7 @@ The separation of the Python models from viewer GUI code allows:
   used
 * tests to be easily run headlessly
 * the Python models to be run headlessly (see
-  [Running napari headlessly](../howtos/headless) for more)
+  [Running napari headlessly](headless) for more)
 
 ## Python models and events
 

diff --git a/docs/developers/benchmarks.md b/docs/developers/benchmarks.md
@@ -1,4 +1,4 @@
-(napari-benchmarks)=
+(benchmarks)=
 # Benchmarks
 
 While not mandatory for most pull requests, we ask that performance related

diff --git a/docs/developers/contributing.md b/docs/developers/contributing.md
@@ -1,11 +1,11 @@
-(napari-contributing)=
+(contributing-code)=
 # Contributing guide
 
 We welcome your contributions! Please see the provided steps below and never hesitate to contact us.
 
 If you are a new user, we recommend checking out the detailed [Github Docs](https://docs.github.com/en).
 
-You can see the general direction for napari development and possible work plans in our current [Roadmap](../roadmaps/index.md).
+You can see the general direction for napari development and possible work plans in our current [Roadmap](roadmaps).
 
 (dev-installation)=
 ## Setting up a development installation
@@ -55,10 +55,12 @@ In order to make changes to `napari`, you will need to [fork](https://docs.githu
 
 4. Install the package in editable mode, along with all of the developer tools.
 
+    ```{note}
     If you only want to use napari, you can install it on most macOS, Linux and
     Windows systems with Python {{ python_version_range }}
     by following the directions on the
-    [instructions page](../tutorials/fundamentals/installation.md#install-as-python-package-recommended).
+    [instructions page](install-python-package).
+    ```
 
     napari supports different Qt backends, and you can choose which one to install and use.
 

diff --git a/docs/developers/core_dev_guide.md b/docs/developers/core_dev_guide.md
@@ -45,7 +45,7 @@ When merging, use GitHub's
 to ensure a clean git history.
 
 You should also continue to make your own pull requests as before and in accordance
-with the [general contributor guide](napari-contributing). These pull requests still
+with the [general contributor guide](contributing-code). These pull requests still
 require the approval of another core developer before they can be merged.
 
 ## Reviewing
@@ -80,7 +80,7 @@ consult back with our [mission and values](mission-and-values).
 2. **Performance and benchmarks:** As `napari` targets scientific applications that often involve
 large multidimensional datasets, high performance is a key value of `napari`. While
 every new feature won't scale equally to all sizes of data, keeping in mind performance
-and our [benchmarks](napari-benchmarks) during a review may be important, and you may
+and our [benchmarks](benchmarks) during a review may be important, and you may
 need to ask for benchmarks to be run and reported or new benchmarks to be added.
 
 3. **APIs and stability:** Coding users and plugin developers will make
@@ -154,11 +154,11 @@ For details on how the documentation and website are built, see
 As a core member, you should be familiar with community and developer
 resources such as:
 
-- Our [contributor guide](napari-contributing).
+- Our [contributor guide](contributing-code).
 - Our [code of conduct](napari-coc).
 - Our [governance](napari-governance).
 - Our [mission and values](mission-and-values).
-- Our [benchmarking guide](napari-benchmarks).
+- Our [benchmarking guide](benchmarks).
 - [PEP8](https://peps.python.org/pep-0008/) for Python style.
 - [PEP257](https://peps.python.org/pep-0257/) and the
    [NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style)

diff --git a/docs/developers/documentation/docs_deployment.md b/docs/developers/documentation/docs_deployment.md
@@ -3,7 +3,7 @@
 ```{note}
 This guide is intended for napari core contributors and is not required reading
 for regular contributors. If you're looking for information on how to contribute
-to the documentation, see [](docs_contributing_guide).
+to the documentation, see [](contributing-docs).
 ```
 
 The napari documentation and website sources are spread over three repositories,

diff --git a/docs/developers/documentation/docs_template.md b/docs/developers/documentation/docs_template.md
@@ -14,6 +14,8 @@ theme:
   intro: Template for adding new napari documentation
 ---
 
+(docs-template)=
+
 # Docs template
 
 This template will guide you to write a well formatted document and prepare it for contribution to napari.org.

diff --git a/docs/developers/documentation/index.md b/docs/developers/documentation/index.md
@@ -1,4 +1,4 @@
-(docs_contributing_guide)=
+(contributing-docs)=
 # Contributing Documentation
 
 This guide will teach you how to submit new documents to napari's usage
@@ -106,13 +106,13 @@ that could be expanded to include the content you think is lacking.
 Go to your local `napari/docs` folder to find examples of documents you might
 want to contribute. The paths are listed in parentheses below.
 
-- [**Explanations**](../../guides/index) (in [`napari/docs/guides`](https://github.com/napari/docs/tree/main/docs/guides)):
+- [**Explanations**](explanations) (in [`napari/docs/guides`](https://github.com/napari/docs/tree/main/docs/guides)):
   in depth content about napari architecture, development choices and some complex features
-- [**Tutorials**](../../tutorials/index) (in [`napari/docs/tutorials`](https://github.com/napari/docs/tree/main/docs/tutorials)):
+- [**Tutorials**](tutorials) (in [`napari/docs/tutorials`](https://github.com/napari/docs/tree/main/docs/tutorials)):
   detailed, reproducible step by step guides, usually combining multiple napari features to complete a potentially complex task
-- [**How-tos**](../../howtos/index) (in [`napari/docs/howtos`](https://github.com/napari/docs/tree/main/docs/howtos)):
+- [**How-tos**](how-tos) (in [`napari/docs/howtos`](https://github.com/napari/docs/tree/main/docs/howtos)):
   simple step by step guides demonstrating the use of common features
-- [**Getting started**](../../tutorials/start_index) (in [`napari/docs/tutorials/fundamentals`](https://github.com/napari/docs/tree/main/docs/tutorials/fundamentals)):
+- [**Getting started**](getting-started) (in [`napari/docs/tutorials/fundamentals`](https://github.com/napari/docs/tree/main/docs/tutorials/fundamentals)):
   these documents are a mix of tutorials and how-tos covering the fundamentals of installing and working with napari for beginners
 
 The [**Examples gallery**](../../gallery) sources are in the [main `napari/napari` repository](https://github.com/napari/napari/tree/main/examples)
@@ -122,9 +122,11 @@ and show code examples of how to use napari.
 :class: tip
 
 If you already have teaching materials e.g. recordings, slide decks or Jupyter notebooks
-hosted somewhere, you can add links to these on our [napari workshops](../../further-resources/napari-workshops.md) page.
+hosted somewhere, you can add links to these on our [napari workshops](workshops) page.
 ```
 
+(contributing-docs-step-one)=
+
 ## 1. Write your documentation
 
 Our goal is that all tutorials and how-tos are easily downloadable and
@@ -138,7 +140,7 @@ documents in our repository and on [napari.org](https://napari.org).
 
 If you are amending existing documentation, you can do so in your preferred text
 editor. If you wish to add a new tutorial or a how-to, we recommend you use our
-[template](./docs_template). Inside the template you'll find handy tips for
+[template](docs-template). Inside the template you'll find handy tips for
 taking screenshots of the viewer, hiding code cells, using style guides and what
 to include in the required prerequisites section.
 

diff --git a/docs/developers/index.md b/docs/developers/index.md
@@ -1,21 +1,23 @@
+(contributing)=
+
 # Contributing
 
 Here you can find resources about the contributing workflow for both code to napari core and documentation of the project, as well as information for onboarding of new core developers.
 
-You can see the general direction for napari development and possible work plans in our current [Roadmap](../roadmaps/index.md).
+You can see the general direction for napari development and possible work plans in our current [Roadmap](roadmaps).
 
 ## For contributors
 
-- [Contributing guide](./contributing)
-- [Contributing documentation](./documentation/index)
-- [Translations](./translations)
-- [Testing](./testing)
-- [Profiling](./profiling)
-- [Benchmarks](./benchmarks)
+- [Contributing guide](contributing-code)
+- [Contributing documentation](contributing-docs)
+- [Translations](translations)
+- [Testing](napari-testing)
+- [Profiling](profiling)
+- [Benchmarks](benchmarks)
 
 ## For core developers
 
-- [Core Developer guide](./core_dev_guide)
-- [Release guide](./release)
-- [Maintenance](./maintenance)
+- [Core Developer guide](core-dev-guide)
+- [Release guide](release)
+- [Maintenance](maintenance)
 
diff --git a/docs/developers/maintenance.md b/docs/developers/maintenance.md
@@ -1,3 +1,5 @@
+(maintenance)=
+
 # Maintenance
 
 This document describes maintenance tasks that need to be performed from time to time. Its purpose is to avoid relying on personal memory alone, and it should be updated regularly.

diff --git a/docs/developers/profiling.md b/docs/developers/profiling.md
@@ -1,3 +1,5 @@
+(profiling)=
+
 # Profiling
 
 In contrast to performance tracing, profiling does not provide information

diff --git a/docs/developers/release.md b/docs/developers/release.md
@@ -1,3 +1,5 @@
+(release)=
+
 # Release guide
 
 This guide documents `napari`'s release process.

diff --git a/docs/further-resources/napari-workshops.md b/docs/further-resources/napari-workshops.md
@@ -1,4 +1,4 @@
-(napari-workshops)=
+(workshops)=
 # napari workshops
 
 There have been many workshops and tutorials given about napari.
@@ -14,7 +14,8 @@ as a starting point.
 
 If you have organized a napari workshop and would like to see it featured here
 in this page, you can
-[send a Pull Request to the napari/docs repository](../developers/documentation/index.md)
+[send a Pull Request](contributing-docs-step-one) to the
+[napari/docs repository](https://github.com/napari/docs)
 or contact the core developers on [zulip chat](https://napari.zulipchat.com/login/).
 ```
 

diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -3,8 +3,8 @@
 
 ```{note}
 These pages describe advanced usage and how napari works internally. If you are
-just getting started, check out our [tutorials](../tutorials/index.md) or
-[how-to guides](../howtos/index.md) instead.
+just getting started, check out our [tutorials](tutorials) or
+[how-to guides](how-tos) instead.
 ```
 
 ## Advanced usage

diff --git a/docs/guides/layers.md b/docs/guides/layers.md
@@ -1,7 +1,7 @@
 (layers-glance)=
 # Layers at a glance
 
-[Layers](napari.layers) are the basic viewable objects that can be added to a
+{class}`~napari.layers` are the basic viewable objects that can be added to a
 viewer. **napari** supports seven main different layer types: `Image`, `Labels`,
 `Points`, `Shapes`, `Surface`, `Tracks` and `Vectors`. Each of the layer types
 corresponds to a different data type, visualization, and interactivity. You can
@@ -24,9 +24,9 @@ viewer.add_image(data, name='astronaut')
 To learn more about the layers available, see the
 [Layers documentation](napari.layers). To learn about how to use the layers
 currently supported by napari, check out the
-[Using layers how-to guides](../../howtos/layers/index). For a gentle
+[Using layers how-to guides](using-layers). For a gentle
 introduction, check out the
-[Layer list section in the napari viewer tutorial](layer_list).
+[Layer list section in the napari viewer tutorial](layer-list).
 
 ## Layer visibility
 

diff --git a/docs/howtos/docker.md b/docs/howtos/docker.md
@@ -1,3 +1,5 @@
+(docker)=
+
 # Napari in Docker
 
 ## Build

diff --git a/docs/howtos/headless.md b/docs/howtos/headless.md
@@ -1,3 +1,5 @@
+(headless)=
+
 # Running napari headlessly
 
 Running napari headlessly (without opening a napari GUI interface) may be

diff --git a/docs/howtos/index.md b/docs/howtos/index.md
@@ -4,23 +4,22 @@
 These guides show you how to complete tasks with napari. They assume you have
 already installed **napari**, know how to launch the viewer, and are familiar
 with its layout. For help with installation see our
-[installation tutorial](../tutorials/fundamentals/installation). For help
+[installation tutorial](installation). For help
 getting started with the viewer see our
-[Getting started guide](../tutorials/fundamentals/getting_started). For
+[How to launch napari guide](launch). For
 help understanding the organisation of the viewer, including things like the
 layers list, the layer properties widgets, the layer control panels, and the
-dimension sliders see our [napari viewer](../tutorials/fundamentals/viewer)
+dimension sliders see our [napari viewer](viewer-tutorial)
 tutorial.
 
-- [Using layers](layers/index): Learn about how to use the layers currently
+- [Using layers](using-layers): Learn about how to use the layers currently
 supported by napari.
 - [Extending napari](extending-napari): Learn how to extend napari by adding widgets
   and connecting callbacks.
-- [napari + ImageJ how-to guide](./napari_imageJ): Learn about how to use napari
-and ImageJ simultaneously.
-- [napari in Docker](./docker): Learn about using napari in docker.
-- [Performance monitoring](./perfmon): Learn about how to monitor napari
+- [napari + ImageJ how-to guide](napari-imagej): Learn about how to use napari
+- [napari in Docker](docker): Learn about using napari in docker.
+- [Performance monitoring](perfmon): Learn about how to monitor napari
 performance and diagnose potential problems.
-- [napari headless](./headless): Tips on how to run napari headlessly.
+- [napari headless](headless): Tips on how to run napari headlessly.
 - [Themes](themes): Changing appearance of the napari GUI with your own theme
   and sharing your theme via a plugin.
diff --git a/docs/howtos/layers/index.md b/docs/howtos/layers/index.md
@@ -12,4 +12,4 @@ Each of these guides has a section on how to manipulate the layers using the GUI
 controls and a section on how to manipulate them programmatically.
 
 For a high-level overview of the napari Layers, see
-[Layers at a glance](../../guides/layers).
+[Layers at a glance](layers-glances).
diff --git a/docs/howtos/layers/labels.md b/docs/howtos/layers/labels.md
@@ -414,7 +414,15 @@ and [zarr arrays](https://zarr.readthedocs.io/en/stable/api/core.html). A
 Because the `labels` layer subclasses the `image` layer, it inherits the great
 properties of the `image` layer, like supporting lazy loading and multiscale
 images for big data layers. For more information about both these concepts see
-the details in [Using the image layer](./image).
+the details in the [image layer guide](image-layer).
+
+## Creating a new labels layer
+
+As you can edit a `Labels` layer using the paintbrush and fill bucket, it is
+possible to create a brand-new empty labels layers by clicking the new labels
+layer button above the layers list. The shape of the new labels layer will match
+the size of any currently existing image layers, allowing you to paint on top of
+them.
 
 ```{admonition} Want to save without compression?
 :class: tip

diff --git a/docs/howtos/layers/points.md b/docs/howtos/layers/points.md
@@ -30,9 +30,9 @@ all the points simultaneously.
 Each data point can have annotations associated with it using the
 `Points.properties` dictionary. These properties can be used to set the face and
 edge colors of the points. For example, when displaying points of different
-classes/types, one could automatically set the color of the individual points by
-their respective class/type. For more details on point properties, see
-[](#setting-point-edge-and-face-color-with-properties) below or the
+classes/types, one could automatically set color the individual points by their
+respective class/type. For more details on point properties, see
+[](#setting-point-edge-and-face-color-with-properties) or
 [point annotation tutorial](../../tutorials/annotation/annotate_points).
 
 ## Creating and editing the `points` layer using the GUI
@@ -266,7 +266,7 @@ name of the property and the values are NumPy arrays with a value for each point
 (i.e., length N for N points in `Points.data`). As we will see below, we can use
 the values in a property to set the display properties of the points (e.g., face
 color or edge color). To see the points properties in action, please see the
-[Point annotation tutorial](../../tutorials/annotation/annotate_points).
+[Point annotation tutorial](annotating-points).
 
 
 ### Non-editable mode

diff --git a/docs/howtos/layers/surface.md b/docs/howtos/layers/surface.md
@@ -144,13 +144,13 @@ object. You can list all the available colormaps using `layer.colormaps`.
 It is also possible to create your own colormaps using vispy's
 `vispy.color.Colormap` object, see it's full
 [documentation here](https://vispy.org/api/vispy.color.colormap.html#vispy.color.colormap.Colormap).
-For more detail see [](./image).
+For more detail see the [image layer guide](image-layer).
 
 ## Adjusting contrast limits
 
-The vertex values of the `surface` layer get mapped through its colormap
-according to values called `contrast limits`. These are a 2-tuple of values
-defining how what values get applied the minimum and maximum of the colormap and
-follow the same principles as the `contrast_limits` described in [](./image).
-They are also accessible through the same keyword arguments, properties, and GUI
-layer controls as in the image layer.
+The vertex values of the `surface` layer get mapped through its colormap according
+to values called `contrast limits`. These are a 2-tuple of values defining how
+what values get applied the minimum and maximum of the colormap and follow the
+same principles as the `contrast_limits` described in the
+[image layer guide](image-layer). They are also accessible through the same keyword
+arguments, properties, and GUI layer controls as in the image layer.
diff --git a/docs/howtos/layers/tracks.md b/docs/howtos/layers/tracks.md
@@ -11,6 +11,8 @@ kernelspec:
   name: python3
 ---
 
+(layers-tracks)=
+
 # Using the `tracks` layer
 
 In this document, you will learn about the `napari` `tracks` layer, including

diff --git a/docs/howtos/napari_imageJ.md b/docs/howtos/napari_imageJ.md
@@ -1,3 +1,5 @@
+(napari-imagej)=
+
 # napari + ImageJ how-to guide
 
 ImageJ is a Java-based image processing program that provides extensibility via Java plugins and recordable macros. It can display, edit, analyze, process, save, and print 8-bit color and grayscale, 16-bit integer, and 32-bit floating point images. It can read many image file formats, including TIFF, PNG, GIF, JPEG, BMP, DICOM, and FITS, as well as raw formats. It has a plethora of features that can be checked out [here](https://en.wikipedia.org/wiki/ImageJ#Features).

diff --git a/docs/index.md b/docs/index.md
@@ -89,7 +89,7 @@ How to install napari.
 :::
 
 :::{grid-item-card} Getting started
-:link: getting_started
+:link: launch
 :link-type: ref
 
 Get started with napari.