Reorganize bundle instructions page to make it easier to navigate and provide download links (#813)

psobolewskiPhD · web-flow · commit 1eeb7157518d · 2025-08-07T09:32:30.000-07:00
Closes: #714 Note: this is a reorganization borne out of a review by Harry Barng at SciPy 2025 # Description This PR makes it simpler to navigate the bundle installation: 1. adds tiles to jump to the instructions for a chosen OS 2. adds direct links to the proper GitHub download for the version. Note I tried to use tiles for this, but the version substitution didn't work. I'm open to other suggestions for how to do it. E.g. it might be possible to use an image as the click target. After discussing with Harry we decided that best was the enemy of the good and this was still worth implementing. I also made some copy edits, mostly to just standardize on "app" for this, since bundle isn't at all obvious to the target audience, while everyone is familiar with apps.
diff --git a/docs/tutorials/fundamentals/installation_bundle_conda.md b/docs/tutorials/fundamentals/installation_bundle_conda.md
@@ -13,39 +13,65 @@ jupyter:
     name: python3
 ---
 
-# How to install napari as a bundled app
+# How to install the napari app
 
-napari can be installed as a bundled app on [MacOS](#how-to-install-the-macos-bundle), [Windows](#how-to-install-the-windows-bundle), and [Linux](#how-to-install-the-linux-bundle) with a simple one click download and guided installation process. This installation method is best if you mainly want to use napari as a standalone GUI app. However, certain plugins may not be supported.
+napari can be installed as a bundled app on [MacOS](#macos-bundle), [Windows](#windows-bundle), and [Linux](#linux-bundle) with a simple one click download and guided installation process. This installation method is best if you mainly want to use napari as a standalone GUI app. However, certain plugins may not be supported.
 
 ```{note}
-If you want to use napari from Python to programmatically interact with the app, please follow the [Python package installation guide](installation.md#install-as-python-package-recommended). This installation method is recommended to take full advantage of napari's features and to access additional plugins.
+* If you want to use napari within a Python project, please follow the [Python package installation guide](installation.md#install-as-python-package-recommended).
+* If you want to contribute code back into napari, please follow the [development installation instructions in the contributing guide](napari-contributing).
 ```
 
-```{note}
-If you want to contribute code back into napari, please follow the [development installation instructions in the contributing guide](napari-contributing).
-```
+## Prerequisites
+
+This installation method does not have any prerequisites.
+
+## Download and install the napari app ({{ napari_version }}) for your operating system
+
+Click the tile below to jump to the installation instructions for your operating system.
 
-To start, visit the [latest napari release page](https://github.com/napari/napari/releases/latest) and go to the 'Assets' tab and download the file that corresponds to your operating system:
+::::{grid}
 
-- Windows users will want the `*-Windows-x86_64.exe` installer.
-- For macOS users, it depends on the processor. This can be checked by going to Apple menu > About This Mac.
-  - For Intel processors, download the `*-macOS-x86_64.pkg` installer
-  - For Apple processors, download the `*-macOS-arm64.pkg` installer.
-- Linux users will need to choose the `*-Linux-x86_64.sh` installer.
+:::{grid-item-card} macOS
+:link: macos-bundle
+:link-type: ref
+:::
+
+:::{grid-item-card} Windows
+:link: windows-bundle
+:link-type: ref
+:::
+
+:::{grid-item-card} Linux
+:link: linux-bundle
+:link-type: ref
+:::
+
+::::
 
-![Cropped screenshot of the GitHub Releases page for napari version 0.4.15. The expanded assets tab shows a number of installers available for different operating systems and architectures. Yellow rectangles highlight the files that correspond to the conda-based installers described in this tutorial.](../../_static/images/bundle_02.png)
 
 ```{note}
-If you are interested in an earlier version of napari, you may access those files by scrolling below the latest release on the [napari release page](https://github.com/napari/napari/releases). The instructions below will work for napari versions 0.4.15 and above.
+If you are interested in an earlier version of the napari app, you may access those files by scrolling below the latest release on the [napari GitHub release page](https://github.com/napari/napari/releases). Each release (0.4.15 and above) will have an "Assets" section with the installers for Windows, macOS, and Linux.
 ```
 
-## Prerequisites
+(macos-bundle)=
 
-This installation method does not have any prerequisites.
+## How to install the macOS app
 
-### How to install the macOS bundle
+Download the napari app ({{ napari_version }}) for your platform:
 
-Once you have downloaded the appropriate macOS package file, you will have a file with a name like `napari-0.5.0-macOS-x86_64.pkg`. Double click this file to open the installer.
+```{admonition} macOS Apple Silicon (arm64)
+:class: admonition
+{{ '# [Download from GitHub](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-macOS-arm64.pkg)'.replace('NAPARI_VER', napari_version) }}
+```
+
+```{admonition} macOS Intel (x86)
+:class: admonition
+{{ '# [Download from GitHub](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-macOS-x86_64.pkg)'.replace('NAPARI_VER', napari_version) }}
+```
+
+Once you have downloaded the appropriate macOS package file, you will have a file with a name like `napari-0.5.0-macOS-x86_64.pkg`, but the version number will be {{ napari_version }}.
+Double click this file to open the installer.
 
 ![Cropped screenshot of macOS desktop UI showing the icon of the PKG installer file, and an arrow pointing to the Welcome page in the opened PKG installer.](../../_static/images/bundle_04.png)
 
@@ -77,21 +103,27 @@ After finishing with no errors, a new page with the text "The installation was s
 
 ![Cropped screenshot of the final page of the PKG installer, Summary, reporting "The installation was successful" with a green check mark icon. A blue Close button is available.](../../_static/images/bundle_11.png)
 
-Click Close to finish. You can now get started using napari! Use Launchpad to open the application.
+Click Close to finish. You can now get started using napari like any macOS application! You can use Launchpad to open it or find it using the Finder, under 🏠 [User directory] > Applications.
 
 ![Montage of two cropped screenshots. On the left, the macOS finder icon and the Launchpad icon, highlighted with a red circle. On the right, the opened launchpad UI showing a 4x4 grid of applications icon, with napari appearing in the bottom right corner.](../../_static/images/bundle_13.png)
 
-```{note}
-The first time you open napari you must use the Launchpad, but in subsequent uses, the napari application should show up in Spotlight search ({kbd}`⌘+spacebar`). The application shortcut will also be available in Finder, under 🏠 [User directory] > Applications.
-```
-
 napari comes installed with sample images from scikit-image. Use the dropdown menu File > Open Sample > napari to open a sample image, or open one of your own images using File > Open or dragging and dropping your image onto the canvas.
 
 Next check out our [tutorial on the viewer](viewer.md) or explore any of the pages under the [Usage tab](../../usage.md).
 
-### How to Install the Windows bundle
+(windows-bundle)=
+
+## How to install the Windows app
 
-Once you have downloaded the Windows executable file, you will have a file with a name like `napari-0.5.0-Windows-x86_64.exe`. Double click this file to open the napari Setup.
+Download the napari app ({{ napari_version }}) for your platform:
+
+```{admonition} Windows (x86_64)
+:class: admonition
+{{ '# [Download from GitHub](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-Windows-x86_64.exe)'.replace('NAPARI_VER', napari_version) }}
+```
+
+Once you have downloaded the Windows executable file, you will have a file with a name like `napari-0.5.0-Windows-x86_64.exe`, but the version number will be {{ napari_version }}.
+Double click this file to open the napari Setup.
 
 ![Montage of the napari EXE installer icon with an arrow pointing to the Welcome page of the napari EXE installer on Windows.](../../_static/images/bundle_17.png)
 
@@ -121,9 +153,19 @@ napari comes installed with sample images from scikit-image. Use the dropdown me
 
 Next check out our [tutorial on the viewer](viewer.md) or explore any of the pages under the [Usage tab](../../usage.md).
 
-### How to Install the Linux bundle
+(linux-bundle)=
+
+## How to install the Linux app
+
+Download the napari app ({{ napari_version }}) for your platform:
+
+```{admonition} Linux (x86_64)
+:class: admonition
+{{ '# [Download from GitHub](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-Linux-x86_64.sh)'.replace('NAPARI_VER', napari_version) }}
+```
 
-Once you have downloaded the Linux SH file, you will have a file with a name like `napari-0.5.0-Linux-x86_64.sh`. Open a new terminal window, navigate to the downloads folder (usually `cd ~/Downloads`) and run the command `bash napari-*-Linux-x86_64.sh`.
+Once you have downloaded the Linux SH file, you will have a file with a name like `napari-0.5.0-Linux-x86_64.sh`, but the version number will be {{ napari_version }}.
+Open a new terminal window, navigate to the downloads folder (usually `cd ~/Downloads`) and run the command `bash napari-*-Linux-x86_64.sh`.
 
 ![Montage of the SH installer icon on Ubuntu, with an arrow pointing to an open terminal instance with a pre-typed command that reads 'bash napari-0.4.14.dev73-Linux-x86_64.sh'.](../../_static/images/bundle_28.png)
 
