Update navigation documentation

docs/digging-deeper/customization.md

@@ -202,117 +202,77 @@ If you don't want to have a footer on your site, you can set the `'footer'` conf
 
 ### Navigation Menu & Sidebar
 
-One of my favourite features with Hyde is its automatic navigation menu and documentation sidebar generator.
+A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation.
+Hyde is designed to automatically configure these menus for you based on the content you have in your project.
 
-#### How it works:
+Still, you will likely want to customize some parts of these menus, and thankfully, Hyde makes it easy to do so.
 
-The sidebar works by creating a list of all the documentation pages.
+#### Customizing the navigation menu
 
-The navigation menu is a bit more sophisticated, it adds all the top-level Blade and Markdown pages.
-It also adds an automatic link to the docs if there is an `index.md` in the `_docs` directory.
+- To customize the navigation menu, use the setting `navigation.order` in the `hyde.php` config.
+- When customizing the navigation menu, you should use the [route key](core-concepts#route-keys) of the page.
 
-#### Reordering Sidebar Items
+Learn more in the [Navigation Menu](navigation-menus) documentation.
 
-Sadly, Hyde is not intelligent enough to determine what order items should be in (blame Dr Jekyll for this),
-so you will probably want to set a custom order.
+#### Customizing the documentation sidebar
 
-Reordering items in the documentation sidebar is as easy as can be. In the `docs` config, there is an array just for this.
-If a page identifier is found here it will get priority calculated according to its position in the list,
-plus an offset of 500. This offset allows you to pages earlier in the list using front matter.
+- To customize the sidebar, use the setting `sidebar_order` in the `docs.php` config.
+- When customizing the sidebar, can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page. 
 
-If a page does not exist in the list they get priority 999, which puts them last.
-You can also use front matter to set a priority for a page.
-The front matter value will always take precedence.
+Learn more in the [Documentation Pages](documentation-pages) documentation.
 
-Let's see an example:
+### Primer on priorities
 
-```php
-// filepath: config/docs.php
-// These are the default values in the config. It puts the readme.md first in order.
-'sidebar_order' => [
-    'readme', // This is the first entry, so it gets the priority 500 + 0
-    'installation', // This gets priority 500 + 1
-    'getting-started', // And this gets priority 500 + 2
-    // Any other pages not listed will get priority 999
-]
-```
-
-#### Reordering Navigation Menu Items
+All navigation menu items have an internal priority value that determines its order in the navigation.
+Lower values means that the item will be higher up in the menu. The default for pages is `999` which puts them last.
+However, some pages are autoconfigured to have a lower priority, for example, the `index` page defaults to a priority of `0`,
 
-As Hyde makes an effort to organize the menu items in a sensible way, your project comes preconfigured to put what it thinks are your most
-important pages first. This may of course not always match what you want, so thankfully it's easy to reorder the menu items!
+#### Basic syntax for changing the priorities
 
-Simply update the `navigation.order` array in the Hyde config! The priorities set will determine the order of the menu items.
-Lower values are higher in the menu, and any pages not listed will get priority 999, which puts them last.
+The cleanest way is to use the list-style syntax where each item will get the priority calculated according to its position in the list, plus an offset of `500`. 
+The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings.
 
 ```php
-// filepath config/hyde.php
-'navigation' => [
-    'order' => [
-        'index' => 0, // _pages/index.md (or .blade.php)
-        'posts' => 10, // _pages/posts.md (or .blade.php)
-        'docs/index' => 100, // _docs/index.md
-    ]
+[
+    'readme', // Gets priority 500
+    'installation', // Gets priority 501
+    'getting-started', // Gets priority 502
 ]
 ```
 
-You can also set the priority of a page directly in the front matter. This will override any dynamically inferred or
-config defined priority. While this is useful for one-offs, it can make it harder to reorder items later on.
-It's up to you which method you prefer to use. This setting can be used both for the navigation menu and the sidebar.
-
-```markdown
----
-navigation:
-    priority: 10
----
-```
-
->info Tip: If you are using automatic subdirectory dropdowns, you can also set their priority in the config. Just use the directory name instead of the page identifier.
+#### Explicit syntax for changing the priorities
 
-#### Adding Custom Navigation Menu Links
-
-You can easily add custom navigation menu links similar how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array.
-
-When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the
-destination and label, both required. Third argument is the priority, which is optional, and defaults to 500.
+You can also specify explicit priorities by adding a value to the array key:
 
 ```php
-// filepath config/hyde.php
-use Hyde\Framework\Features\Navigation\NavItem;
-
-'navigation' => [
-    'custom' => [
-        NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
-    ]
+[
+    'readme' => 10, // Gets priority 10
+    'installation' => 15, // Gets priority 15
+    'getting-started' => 20, // Gets priority 20
 ]
 ```
 
-Simplified, this will then be rendered as follows:
-
-```html
-<a href="https://github.com/hydephp/hyde">GitHub</a>
-```
-
-#### Excluding Items (Blacklist)
-
-Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu.
-To remove items from being automatically added, simply add the page's route key to the blacklist.
-As you can see, the `404` page has already been filled in for you.
+You can also combine these options if you want:
 
 ```php
-'navigation' => [
-    'exclude' => [
-        '404'
-    ]
+[
+    'readme' => 10, // Gets priority 10
+    'installation', // Gets priority 500
+    'getting-started', // Gets priority 501
 ]
 ```
 
-You can also specify that a page should be excluded by setting the page front matter.
+#### Customizing navigation settings using front matter
+
+You can also customize all the navigation settings on a per-page basis using front matter.
 
 ```markdown
 ---
 navigation:
-    hidden: true
+    label: "Customizing your Site" # Override navigation/sidebar label
+    group: "Digging Deeper" # Override sidebar group or dropdown
+    priority: 25 # Override navigation/sidebar priority
+    hidden: true # Hide page from navigation/sidebar
 ---
 ```