Update RELEASE_NOTES.md

Author: emmadesilva

RELEASE_NOTES.md

@@ -11,15 +11,14 @@ This serves two purposes:
 
 ### Added
 - Added a new `\Hyde\Framework\Actions\PreBuildTasks\TransferMediaAssets` build task handle media assets transfers for site builds.
-- Added a new `NavigationItem::getLink()` method contain the previous `NavigationItem::getDestination()` logic, to return the link URL.
 
 ### Changed
+- **Breaking:** The internals of the navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations. For more information, see below.
+- Minor: Navigation menu items are now no longer filtered by duplicates (meaning two items with the same label can now exist in the same menu) in https://github.com/hydephp/develop/pull/1573
+- Minor: Due to changes in the navigation system, it is possible that existing configuration files will need to be adjusted in order for menus to look the same (in terms of ordering etc.) 
+- Minor: The documentation article component now supports disabling the semantic rendering using a falsy value in https://github.com/hydephp/develop/pull/1566
 - Changed how the documentation search is generated, to be an `InMemoryPage` instead of a post-build task.
 - Media asset files are now copied using the new build task instead of the deprecated `BuildService::transferMediaAssets()` method.
-- Minor: The documentation article component now supports disabling the semantic rendering using a falsy value in https://github.com/hydephp/develop/pull/1566
-- Navigation menu items are now no longer filtered by duplicates (meaning two items with the same label can now exist in the same menu) in https://github.com/hydephp/develop/pull/1573
-- Breaking: The `NavigationItem` class now always stores the destination as a `Route` instance.
-- Breaking: The `NavigationItem::getDestination()` method now returns its `Route` instance.
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -45,6 +44,32 @@ Please see the "Breaking changes & upgrade guide" section below for more informa
 
 Please read through this section to ensure your site upgrades smoothly.
 
+## High impact
+
+### Navigation system rewrite
+
+The navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations, see more down below.
+
+For most users, the only impact will be that configuration files need to be updated to use the new configuration format. Due to the internal changes,
+it's also possible that menu items will be in a slightly different order than before, depending on your setup. Please verify that your site's menus
+look as expected after upgrading, and adjust the configuration files if necessary, before deploying to production.
+
+### Navigation and sidebar configuration changes
+
+The navigation and sidebar configuration files have been updated to use the new Navigation API. 
+This means that you will need to update your configuration files to use the new format.
+
+The easiest way to upgrade is to publish updated configuration files (`hyde.php` and `docs.php`) and copy over your customizations.
+
+The following configuration entries have been updated:
+
+-  Changed configuration option `docs.sidebar_order` to `docs.sidebar.order` in https://github.com/hydephp/develop/pull/1583
+-  Upgrade path: Move the `sidebar_order` option's array in the `config/docs.php` file into the `sidebar` array in the same file.
+
+-  Changed configuration option `docs.table_of_contents` to `docs.sidebar.table_of_contents` in https://github.com/hydephp/develop/pull/1584
+-  Upgrade path: Move the `table_of_contents` option's array in the `config/docs.php` file into the `sidebar` array in the same file.
+
+
 ## General impact
 
 ### Documentation search page changes
@@ -60,13 +85,22 @@ For more information, see https://github.com/hydephp/develop/pull/1498.
 
 ## Low impact
 
-### Navigation item changes
+### Navigation internal changes
+
+The navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations.
+
+If you have previously in your custom code done any of the following, or similar, you will need to adapt your code to use the new Navigation API:
+- Created custom navigation menus or Blade components
+- Extended or called the navigation related classes directly
+- Customized the navigation system in any way beyond the standard configuration
+
 
-The `NavigationItem::getDestination()` method now returns its `Route` instance. This allows for deferring the route evaluation.
+#### Upgrade guide
 
-If you have previously used this method directly and expected a string to be returned, you may need to adapt your code to handle the new return type.
+Due to the scope of the rewrite, the easiest and fastest way to upgrade your code is to recreate it using the new Navigation API.
 
-If you want to retain the previous state where a string is always returned, you can use the new `NavigationItem::getLink()` method instead, which will resolve the route immediately.
+- For a full comparison of the changes, you may see the PR that introduced the new API: https://github.com/hydephp/develop/pull/1568/files
+- For information on how to use the new Navigation API, see the documentation: https://hydephp.com/docs/2.x/navigation-api
 
 ### HTML ID changes