feat: Add root-level Updating Unraid guidance (#464)

elibosley · web-flow · commit f48d0675844b · 2026-04-22T22:36:29.000-04:00
## Summary

- Add **Updating Unraid** as a root-level Unraid OS category, with a
concise landing page for the update journey.
- Position **Updating Unraid** below **Troubleshooting** in the Unraid
OS sidebar, with **Release notes** and **Version history** nested under
it for navigation.
- Keep existing **Release notes** and **Version history** document paths
in place, so their URLs do not change.
- Move **Release types** and **Upgrading Unraid** under that root-level
update category, including their update/downgrade partials.
- Keep detailed upgrade, downgrade, and manual recovery steps on
**Upgrading Unraid** instead of overloading the root landing page.
- Keep boot-device replacement under **System administration &gt;
Maintenance** so maintenance is separate from OS update decision-making.
- Link the update journey from **Version history** and update
release-note references to the new update path.
- Add redirects from the old `system-administration/maintain-and-update`
update URLs to the new `updating-unraid` URLs.
- Tighten prerelease guidance so users do not remain on old beta or RC
builds once newer prerelease or stable options are available.

- Clarify **Release types** so Stable covers both `.0` minor releases
and later patch releases, including what Unraid minor and patch releases
typically contain.

- Clarify that release branch changes happen in the Unraid account app;
the Update OS tool only shows updates for the server's current branch.

- Rename **Version history** to **Version Archive** and point users
toward the built-in updater or USB Creator before browsing archived
downloads.

- Add Product Unraid links for stable bug reports, pre-release feedback,
and feature requests, plus one footer link to the Feature and Bug
Tracker.

## Why

Updating Unraid is a core lifecycle task, not just a
system-administration maintenance task. The docs now present it as a
first-class user journey: choose the right release, understand
prerelease risk, run the update, find older versions, and troubleshoot
if needed.

Separating boot-device replacement into Maintenance keeps
hardware/configuration maintenance distinct from OS update guidance.
Nesting Release notes and Version history under Updating Unraid keeps
the full update flow together in the sidebar without forcing
release-note URL changes.

## Validation

- `node -e 'const { sortSidebarItems } =
require("./sidebar-semver-sort.js"); const items =
[{type:"category",label:"Updating
Unraid",items:[{type:"doc",id:"unraid-os/updating-unraid/index"}]},{type:"category",label:"Release
notes",items:[{type:"doc",id:"unraid-os/release-notes/7.3.0"},{type:"doc",id:"unraid-os/release-notes/7.2.5"}]},{type:"doc",id:"unraid-os/download_list",label:"Version
history"}]; console.log(JSON.stringify(sortSidebarItems(items), null,
2));'`\n- `pnpm exec remark docs/unraid-os/updating-unraid/index.mdx
--quiet --frail`\n- `pnpm exec remark
docs/unraid-os/updating-unraid/index.mdx
docs/unraid-os/updating-unraid/release-types.mdx
docs/unraid-os/updating-unraid/upgrading-unraid.mdx
docs/unraid-os/updating-unraid/partials/manual-downgrade-command-line.mdx
docs/unraid-os/updating-unraid/partials/manual-downgrade-simplest.mdx
docs/unraid-os/updating-unraid/partials/upgrade-legacy-611-612.mdx
docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx
docs/unraid-os/download_list.mdx docs/unraid-os/release-notes/7.2.0.md
docs/unraid-os/release-notes/7.2.1.md
docs/unraid-os/release-notes/7.2.2.md
docs/unraid-os/release-notes/7.2.3.md
docs/unraid-os/release-notes/7.2.4.md
docs/unraid-os/release-notes/7.2.5.md
docs/unraid-os/release-notes/7.3.0.md
docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx
--quiet --frail`\n- `pnpm exec remark docs/unraid-os/download_list.mdx
--quiet --frail`\n- `pnpm run check-case-sensitivity`\n- `git diff
--check`\n\n- `git diff --check --
docs/unraid-os/updating-unraid/release-types.mdx`

- `pnpm exec remark docs/unraid-os/updating-unraid/release-types.mdx
docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx --quiet
--frail`

- `git diff --check -- docs/unraid-os/download_list.mdx`

- `pnpm exec remark docs/unraid-os/updating-unraid/release-types.mdx
--quiet --frail`

- `pnpm exec prettier --check docusaurus.config.ts`

- `git diff --check -- docs/unraid-os/updating-unraid/release-types.mdx
docusaurus.config.ts`

Per repo guidance, I did not run the full Docusaurus build.


&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;
## Summary by CodeRabbit

* **Documentation**
* Added a new "Release Types" guide explaining Stable/Beta/RC and update
guidance.
* Introduced user-facing instructions for updating via the web "Update
OS" tool.
* Renamed and consolidated content under "Updating Unraid" and updated
the Version Archive.
* Reorganized sidebar ordering and added redirects to group
update-related docs.
* Updated links, fixed line-ending/formatting issues, and added a
"Feature and Bug Tracker" footer link.
&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/docs/unraid-os/advanced-configurations/_category_.json b/docs/unraid-os/advanced-configurations/_category_.json
@@ -4,4 +4,4 @@
     "link": {
       "type": "generated-index"
     }
-  }
+  }
diff --git a/docs/unraid-os/download_list.mdx b/docs/unraid-os/download_list.mdx
@@ -1,12 +1,14 @@
 ---
-sidebar_position: 7
-title: Version history
+sidebar_position: 9
+title: Version Archive
 ---
 
 import {VersionsTable} from '@site/src/components/VersionsTable';
 
-# Version history
+# Version Archive
 
-Need the USB Creator? [Getting Started With Unraid](https://unraid.net/getting-started)
+Use this archive to find release notes and download links for Unraid OS versions. To update an existing server, use the built-in updater; see the [standard update process](./updating-unraid/index.mdx#standard-update-process) for steps. To create a new boot device, use the [Unraid USB Creator](https://unraid.net/download).
+
+If you are deciding which release to install, start with [Unraid OS release types](./updating-unraid/release-types.mdx).
 
 <VersionsTable />
diff --git a/docs/unraid-os/release-notes/7.2.0.md b/docs/unraid-os/release-notes/7.2.0.md
@@ -6,7 +6,7 @@ Note that some plugins may have visual issues in this release; please give plugi
 
 ## Upgrading
 
-For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
+For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
 
 ### Known issues
 
diff --git a/docs/unraid-os/release-notes/7.2.1.md b/docs/unraid-os/release-notes/7.2.1.md
@@ -4,7 +4,7 @@ This is a small update with some great fixes and improvements.
 
 ## Upgrading
 
-For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
+For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
 
 ### Known issues
 
diff --git a/docs/unraid-os/release-notes/7.2.2.md b/docs/unraid-os/release-notes/7.2.2.md
@@ -8,7 +8,7 @@ If you are on 7.2.0 or earlier you can skip straight to 7.2.2.
 
 ## Upgrading
 
-For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
+For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
 
 ### Known issues
 
diff --git a/docs/unraid-os/release-notes/7.2.3.md b/docs/unraid-os/release-notes/7.2.3.md
@@ -4,7 +4,7 @@ This is a security and bugfix release, recommended for all users.
 
 ## Upgrading
 
-For step-by-step instructions, see [Upgrading Unraid](../../unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
+For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](../../unraid-os/troubleshooting/licensing-faq.mdx#license-types--features)?
 
 ### Known issues
 
diff --git a/docs/unraid-os/release-notes/7.2.4.md b/docs/unraid-os/release-notes/7.2.4.md
@@ -6,7 +6,7 @@ This release includes critical security updates and bug fixes.
 
 ## Upgrading
 
-For step-by-step instructions, see [Upgrading Unraid](/unraid-os/system-administration/maintain-and-update/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)?
+For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)?
 
 ### Known issues
 
diff --git a/docs/unraid-os/release-notes/7.2.5.md b/docs/unraid-os/release-notes/7.2.5.md
@@ -8,7 +8,7 @@ This release is recommended for all 7.2.x users.
 
 ## Upgrading
 
-For step-by-step instructions, see [Upgrading Unraid](/unraid-os/system-administration/maintain-and-update/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)?
+For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)?
 
 ### Known issues
 
diff --git a/docs/unraid-os/release-notes/7.3.0.md b/docs/unraid-os/release-notes/7.3.0.md
@@ -4,13 +4,15 @@ This release candidate includes onboarding and internal boot, TPM-based licensin
 
 This is RELEASE CANDIDATE software. Please use on test servers only.
 
+Curious about what our different release types are? See [Unraid OS release types](/unraid-os/updating-unraid/release-types/).
+
 ## Upgrading
 
-For step-by-step instructions, see [Upgrading Unraid](/unraid-os/system-administration/maintain-and-update/upgrading-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)?
+For step-by-step instructions, see [Updating Unraid](/unraid-os/updating-unraid/). Questions about your [license](/unraid-os/troubleshooting/licensing-faq/)?
 
 ### Known issues
 
-See [Unraid OS Prerelease (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback) for issues reported by other testers.
+See [Unraid OS Pre-release (Bugs & Feedback)](https://product.unraid.net/b/unraid-os-prerelease-bugs-feedback) for issues reported by other testers.
 
 - During internal boot setup, the WebGUI may show **Array Offline** while internal boot configures. **DO NOT** manually restart or remove your flash drive during this process.
 - Internal boot requires boot storage that can be accessed by in-tree Linux drivers during startup. Devices that require third-party drivers or post-boot configuration cannot be used for internal boot.
@@ -22,10 +24,10 @@ See [Unraid OS Prerelease (Bugs & Feedback)](https://product.unraid.net/b/unraid
 
 ### Rolling back
 
-- If you already enabled internal boot or switched to TPM-based licensing while testing the 7.3 prerelease, you can roll back to `7.3.0-beta.1` without issue.
+- If you already enabled internal boot or switched to TPM-based licensing while testing the 7.3 pre-release, you can roll back to `7.3.0-beta.1` without issue.
 - Do not roll back to `7.2.4` or earlier after enabling internal boot or TPM-based licensing.
 - If you upgrade ZFS pool features, earlier Unraid releases may not be able to import those pools.
-- If you need to roll back, follow the normal prerelease rollback process before moving between builds.
+- If you need to roll back, follow the normal pre-release rollback process before moving between builds.
 
 If you are considering any rollback path below `7.3.0-beta.1`, also see the [7.2.4 release notes](/unraid-os/release-notes/7.2.4/).
 
@@ -280,7 +282,7 @@ To proactively switch to TPM-based licensing, see [How can I move from flash-bas
 - zfs: version 2.4.1
 - zlib: version 1.3.2
 
-## Prerelease tester notes
+## Pre-release tester notes
 
 ### CHANGES FROM BETA.2
 
diff --git a/docs/unraid-os/release-notes/_category_.json b/docs/unraid-os/release-notes/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Release notes",
-  "position": 6,
+  "position": 8,
   "link": {
     "type": "generated-index",
     "description": "Unraid Release Notes"
diff --git a/docs/unraid-os/system-administration/_category_.json b/docs/unraid-os/system-administration/_category_.json
@@ -4,4 +4,4 @@
     "link": {
       "type": "generated-index"
     }
-  }
+  }
diff --git a/docs/unraid-os/system-administration/maintain-and-update/_category_.json b/docs/unraid-os/system-administration/maintain-and-update/_category_.json
@@ -1,7 +1,4 @@
 {
-    "label": "Maintain and update",
-    "position": 2,
-    "link": {
-      "type": "generated-index"
-    }
-  }
+    "label": "Maintenance",
+    "position": 2
+  }
diff --git a/docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx b/docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 sidebar_label: Changing the boot device
 ---
 
diff --git a/docs/unraid-os/system-administration/maintain-and-update/partials/upgrade-modern.mdx b/docs/unraid-os/system-administration/maintain-and-update/partials/upgrade-modern.mdx
diff --git a/docs/unraid-os/troubleshooting/_category_.json b/docs/unraid-os/troubleshooting/_category_.json
@@ -1,4 +1,4 @@
 {
     "label": "Troubleshooting",
     "position": 5
-}
+}
diff --git a/docs/unraid-os/updating-unraid/_category_.json b/docs/unraid-os/updating-unraid/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Updating Unraid",
+  "position": 7,
+  "link": {
+    "type": "doc",
+    "id": "unraid-os/updating-unraid/index"
+  }
+}
diff --git a/docs/unraid-os/updating-unraid/index.mdx b/docs/unraid-os/updating-unraid/index.mdx
@@ -1,6 +1,6 @@
 ---
-sidebar_position: 2
-sidebar_label: Upgrading Unraid
+sidebar_position: 1
+sidebar_label: Updating Unraid
 ---
 
 <!-- markdownlint-disable MD041 MD033 -->
@@ -12,17 +12,19 @@ import UpgradeLegacy611612 from "./partials/upgrade-legacy-611-612.mdx";
 import ManualDowngradeSimplest from "./partials/manual-downgrade-simplest.mdx";
 import ManualDowngradeCommandLine from "./partials/manual-downgrade-command-line.mdx";
 
-# Upgrading Unraid
+# Updating Unraid
 
-Upgrading Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard upgrade process, along with troubleshooting tips and manual upgrade options.
+Updating Unraid OS ensures that you have the latest features, security updates, and hardware support. This page outlines the standard update process, along with troubleshooting tips and manual update options.
+
+For help deciding between Stable, Beta, and Release Candidate (RC) builds, see [Unraid OS release types](./release-types.mdx).
 
 :::note[Prerequisites]
 
-Before you start upgrading, make sure to create a complete backup of your boot device. For more details, refer to [Backing up your boot device](../maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device).
+Before you start updating, make sure to create a complete backup of your boot device. For more details, refer to [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device).
 
 :::
 
-:::tip[Best practices before upgrading]
+:::tip[Best practices before updating]
 
 1. **Make a backup** of your boot device and any important data.
 2. **Read the Release Notes** for the version you plan to install.
@@ -33,7 +35,7 @@ Before you start upgrading, make sure to create a complete backup of your boot d
 
 :::
 
-## Standard upgrade process
+## Standard update process
 
 <Tabs>
   <TabItem value="modern-7x" label="Unraid 7.x and later" default>
@@ -47,7 +49,7 @@ Before you start upgrading, make sure to create a complete backup of your boot d
 
 :::caution[ZFS pool upgrade warnings]
 
-When upgrading to Unraid 7.x, you may see warnings about [%%ZFS|zfs%%](../../advanced-configurations/optimize-storage/zfs-storage.mdx) pool feature upgrades during boot or in the %%WebGUI|web-gui%%. These warnings are not a sign of a problem; they simply indicate that your %%ZFS|zfs%% pool is using features from an older version of ZFS.
+When upgrading to Unraid 7.x, you may see warnings about [%%ZFS|zfs%%](../advanced-configurations/optimize-storage/zfs-storage.mdx) pool feature upgrades during boot or in the %%WebGUI|web-gui%%. These warnings are not a sign of a problem; they simply indicate that your %%ZFS|zfs%% pool is using features from an older version of ZFS.
 
 Upgrading your pool isn't urgent, but if you do decide to upgrade, keep in mind that it may not work with previous versions of Unraid. This means you may not be able to revert to a previous Unraid version after making the upgrade.
 
@@ -141,7 +143,7 @@ If you don't see the option to downgrade under **Tools → Downgrade OS**, use t
 
 ### Manual downgrade or upgrade
 
-Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your boot device. For more details, see [Backing up your boot device](../maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device).
+Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your boot device. For more details, see [Backing up your boot device](../system-administration/maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device).
 
 <Tabs>
   <TabItem value="Simplest method" label="Simplest method">
diff --git a/docs/unraid-os/updating-unraid/partials/manual-downgrade-command-line.mdx b/docs/unraid-os/updating-unraid/partials/manual-downgrade-command-line.mdx
@@ -4,7 +4,7 @@ This method should only be used if you are comfortable with the Linux command li
 
 :::
 
-1. Copy the URL of the desired Unraid version ZIP file from the [Version History](../../../download_list.mdx).
+1. Copy the URL of the desired Unraid version ZIP file from the [Version History](../../download_list.mdx).
 2. Log in via %%SSH|ssh%% or console.
 3. Execute the following commands *one at a time* (replace `<URL>` with the copied link):
 
diff --git a/docs/unraid-os/updating-unraid/partials/manual-downgrade-simplest.mdx b/docs/unraid-os/updating-unraid/partials/manual-downgrade-simplest.mdx
@@ -1,4 +1,4 @@
-1. Download the Unraid version ZIP file from the [Version History](../../../download_list.mdx).
+1. Download the Unraid version ZIP file from the [Version History](../../download_list.mdx).
 2. Unzip the file on your computer.
 3. Access the `flash` network share (your boot volume; the share name may still be `flash` even when the UI says **Boot device**) or connect the USB boot device to your computer.
 4. Create a `previous` directory if it doesn't already exist.
diff --git a/docs/unraid-os/updating-unraid/partials/upgrade-legacy-611-612.mdx b/docs/unraid-os/updating-unraid/partials/upgrade-legacy-611-612.mdx
diff --git a/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx b/docs/unraid-os/updating-unraid/partials/upgrade-modern.mdx
@@ -0,0 +1,13 @@
+Updating Unraid is done using the new **Update OS tool** with a user-friendly interface:
+
+1. In the %%WebGUI|web-gui%%, click the top-right dropdown menu and select **Check for Update** or navigate to ***Tools → Update OS***.
+2. Review the update shown for your server's current release branch.
+3. Click **View Changelog to Start Update**. The Changelog will appear for you to review before hitting **Continue**.
+4. Click **Confirm and start update** to apply the selected release.
+5. When prompted, reboot your server to complete the upgrade.
+
+:::note
+
+To change between the **Stable** and **Next** release branches, open the top-right account menu and choose **Manage Unraid.net Account**. Release branches are managed in the Unraid account app, not directly in the OS.
+
+:::
diff --git a/docs/unraid-os/updating-unraid/release-types.mdx b/docs/unraid-os/updating-unraid/release-types.mdx
diff --git a/docs/unraid-os/using-unraid-to/_category_.json b/docs/unraid-os/using-unraid-to/_category_.json
diff --git a/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx b/docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
diff --git a/sidebar-semver-sort.js b/sidebar-semver-sort.js

Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,4 @@`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index"`
`6`	`6`	`}`
`7`		`- }`
	`7`	`+ }`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"label": "Release notes",`
`3`		`- "position": 6,`
	`3`	`+ "position": 8,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`	`6`	`"description": "Unraid Release Notes"`