Merge pull request #1841 from hydephp/clean-up-the-navigation-documentation

Move the sidebar documentation to the documentation pages page

Author: emmadesilva

docs/creating-content/documentation-pages.md

@@ -100,7 +100,39 @@ navigation:
     priority: 5
 ```
 
-You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
+You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites.
+
+#### Basic Priority Syntax
+
+A nice and simple way to define the order of pages is to add their route keys as a simple list array. Hyde will then match that array order.
+
+It may be useful to know that Hyde internally will assign a 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/docs.php
+'sidebar' => [
+    'order' => [
+        'readme', // Priority: 500
+        'installation', // Priority: 501
+        'getting-started', // Priority: 502
+    ]
+]
+```
+
+#### Explicit Priority Syntax
+
+You can also specify explicit priorities by adding a value to the array keys. Hyde will then use these exact values as the priorities.
+
+```php
+// filepath: config/docs.php
+'sidebar' => [
+    'order' => [
+        'readme' => 10,
+        'installation' => 15,
+        'getting-started' => 20,
+    ]
+]
+```
 
 ### Sidebar Labels
 
@@ -130,13 +162,11 @@ navigation:
 
 #### Automatic Subdirectory-Based Grouping
 
-You can also automatically group your documentation pages by placing source files in sub-directories.
+You can also automatically group your documentation pages by placing source files in subdirectories.
 
 For example, putting a Markdown file in `_docs/getting-started/` is equivalent to adding the same front matter seen above.
 
->info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they would overwrite each other.
-
->info Tip: When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file.
+>warning Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they would overwrite each other.
 
 ### Hiding Items
 
@@ -213,11 +243,9 @@ To quickly arrange the order of items in the sidebar, you can reorder the page i
 
 See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br>
 
-### Automatic Sidebar Group Labels
-
-When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label.
+### Setting Sidebar Group Labels
 
-Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself!
+When using the automatic sidebar grouping feature the titles of the groups are generated from the subdirectory names. If these are not to your liking, for example if you need to use special characters, you can override them in the configuration file. The array key is the directory name, and the value is the label.
 
 ```php
 // Filepath: config/docs.php
@@ -227,6 +255,80 @@ Please note that this option is not added to the config file by default, as it's
 ],
 ```
 
+Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself!
+
+#### Setting Sidebar Group Priorities
+
+By default, each group will be assigned the lowest priority found inside the group. However, you can specify the order and priorities for sidebar group keys the same way you can for the sidebar items.
+
+Just use the sidebar group key as instead of the page identifier/route key:
+
+```php
+// Filepath: config/docs.php
+'sidebar' => [
+    'order' => [
+        'readme',
+        'installation',
+        'getting-started',
+    ],
+],
+```
+
+### Numerical Prefix Sidebar Ordering
+
+HydePHP v2 introduces sidebar item ordering based on numerical prefixes in filenames. This feature works for the documentation sidebar.
+
+This has the great benefit of matching the sidebar layout with the file structure view. It also works especially well with subdirectory-based sidebar grouping.
+
+```shell
+_docs/
+  01-installation.md     # Priority: 1
+  02-configuration.md    # Priority: 2
+  03-usage.md            # Priority: 3
+```
+
+As you can see, Hyde parses the number from the filename and uses it as the priority for the page in the sidebar, while stripping the prefix from the route key.
+
+#### Important Notes
+
+1. The numerical prefix remains part of the page identifier but is stripped from the route key.
+   For example: `_docs/01-installation.md` has route key `installation` and page identifier `01-installation`.
+2. You can delimit the numerical prefix with either a dash or an underscore.
+   For example: Both `_docs/01-installation.md` and `_docs/01_installation.md` are valid.
+3. Leading zeros are optional. `_docs/1-installation.md` is equally valid.
+
+#### Using Numerical Prefix Ordering in Subdirectories
+
+This feature integrates well with automatic subdirectory-based sidebar grouping. Here's an example of how you could organize a documentation site:
+
+```shell
+_docs/
+  01-getting-started/
+    01-installation.md
+    02-requirements.md
+    03-configuration.md
+  02-usage/
+    01-quick-start.md
+    02-advanced-usage.md
+  03-features/
+    01-feature-1.md
+    02-feature-2.md
+```
+
+Here are two useful tips:
+
+1. You can use numerical prefixes in subdirectories to control the sidebar group order.
+2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory.
+
+#### Customization
+
+If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key.
+
+```php
+// filepath: config/hyde.php
+'numerical_page_ordering' => false,
+```
+
 ### Table of Contents Settings
 
 Hyde automatically generates a table of contents for the page and adds it to the sidebar.

docs/digging-deeper/customization.md

@@ -283,15 +283,18 @@ Still, you will likely want to customize some parts of these menus, and thankful
 
 - 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.
+- You can use either a basic list array or specify explicit priorities.
 
 Learn more in the [Navigation Menu](navigation) documentation.
 
 #### Customizing the documentation sidebar
 
 - 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.
+- When customizing the sidebar, you can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page.
+- Similar to the navigation menu, you can use a basic list array or specify explicit priorities.
+- You can also use front matter in individual documentation pages to customize their appearance and behavior in the sidebar.
 
-Learn more in the [Documentation Pages](documentation-pages) documentation.
+Learn more in the [Documentation Pages](documentation-pages#sidebar) documentation.
 
 ## Additional Advanced Options
 

docs/digging-deeper/navigation.md

@@ -8,15 +8,15 @@ navigation:
 
 ## Introduction
 
-HydePHP offers automatic navigation menu and documentation sidebar generation features, designed to take the pain out of creating navigation menus.
+HydePHP offers automatic navigation menu generation features, designed to take the pain out of creating navigation menus.
 While Hyde does its best to configure these menus automatically based on understanding your project files, you may want to customize them further.
 
 There are two types of navigation menus in Hyde:
 
 1. **Primary Navigation Menu**: The main navigation menu appearing on most pages of your site. Unique features include dropdowns for subdirectories, depending on configuration.
 2. **Documentation Sidebar**: The sidebar on documentation pages with links to other documentation pages. Unique features include automatic grouping based on subdirectories.
 
-This documentation will guide you through the customization process. To learn even more about sidebars, visit the [Documentation Pages](documentation-pages) documentation.
+This documentation will guide you through the customization process of the primary navigation menu. To learn about the documentation sidebar, visit the [Documentation Pages](documentation-pages) documentation.
 
 ### Internal Structure Overview
 
@@ -43,11 +43,10 @@ Hyde provides multiple ways to customize navigation menus to suit your needs:
 
 1. Front matter data in Markdown and Blade page files, applicable to all menu types
 2. Configuration in the `hyde` config file for main navigation items
-3. Configuration in the `docs` config file for documentation sidebar items
 
 Keep in mind that front matter data overrides dynamically inferred or config-defined priorities. While useful for quick one-off changes on small sites, it can make reordering items later on more challenging as you can't see the entire structure at once.
 
-Additionally, general options for the entire navigation menus are also available in the `hyde` and `docs` config files.
+Additionally, general options for the entire navigation menus are also available in the `hyde` config file.
 
 ## Front Matter Configuration
 
@@ -105,16 +104,15 @@ navigation:
 
 ## Config File Configuration
 
-Let's explore how to customize navigation menus using configuration files:
+Let's explore how to customize the main navigation menu using configuration files:
 
 - For the main navigation menu, use the `navigation` setting in the `hyde.php` config file.
-- For the sidebar, use the `sidebar` setting in the `docs.php` config file.
 
-When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers).
+When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page.
 
 ### Changing Priorities
 
-The `navigation.order` and `sidebar.order` settings allow you to customize the order of pages in the navigation menus.
+The `navigation.order` setting allows you to customize the order of pages in the main navigation menu.
 
 #### Basic Priority Syntax
 
@@ -133,17 +131,6 @@ It may be useful to know that we internally will assign a priority calculated ac
 ]
 ```
 
-```php
-// filepath: config/docs.php
-'sidebar' => [
-    'order' => [
-        'readme', // Priority: 500
-        'installation', // Priority: 501
-        'getting-started', // Priority: 502
-    ]
-]
-```
-
 #### Explicit Priority Syntax
 
 You can also specify explicit priorities by adding a value to the array keys. We'll then use these exact values as the priorities.
@@ -159,28 +146,6 @@ You can also specify explicit priorities by adding a value to the array keys. We
 ]
 ```
 
-```php
-// filepath: config/docs.php
-'sidebar' => [
-    'order' => [
-        'readme' => 10,
-        'installation' => 15,
-        'getting-started' => 20,
-    ]
-]
-```
-
-You could also combine these methods if desired:
-
-```php
-// filepath: Applicable to both
-[
-    'readme' => 10, // Priority: 10
-    'installation', // Priority: 500
-    'getting-started', // Priority: 501
-]
-```
-
 ### Changing Menu Item Labels
 
 Hyde makes a few attempts to find suitable labels for the navigation menu items to automatically create helpful titles.
@@ -197,8 +162,6 @@ If you're not happy with these, it's easy to override navigation link labels by
 ]
 ```
 
-**Note:** This feature is not yet supported for the sidebar.
-
 ### Excluding Items (Blacklist)
 
 When you have many pages, it may be useful to prevent links from being added to the main navigation menu.
@@ -268,22 +231,14 @@ Enable this feature in the `hyde.php` config file by setting the `subdirectory_d
 
 Now if you create a page called `_pages/about/contact.md`, it will automatically be placed in a dropdown called "About".
 
-#### Automatic Documentation Sidebar Grouping
-
-This feature is always enabled for documentation pages. Simply place your pages in subdirectories to have them grouped in the sidebar.
-
-For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started".
-
->info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key.
-
 #### Dropdown Menu Notes
 
 - Dropdowns take priority over standard items. If you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu.
 - Example: With this file structure: `_pages/foo.md`, `_pages/foo/bar.md`, `_pages/foo/baz.md`, the link to `foo` will be lost, so please keep this in mind when using this feature.
 
 ## Numerical Prefix Navigation Ordering
 
-HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar.
+HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for the primary navigation menu.
 
 This has the great benefit of matching the navigation menu layout with the file structure view. It also works especially well with subdirectory-based navigation grouping.
 
@@ -308,25 +263,9 @@ As you can see, Hyde parses the number from the filename and uses it as the prio
 
 This feature integrates well with automatic subdirectory-based navigation grouping. Here are two useful tips:
 
-1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order.
+1. You can use numerical prefixes in subdirectories to control the dropdown order.
 2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory.
 
-Here is an example structure of how you could organize a documentation site:
-
-```shell
-_docs/
-  01-getting-started/
-    01-installation.md
-    02-requirements.md
-    03-configuration.md
-  02-usage/
-    01-quick-start.md
-    02-advanced-usage.md
-  03-features/
-    01-feature-1.md
-    02-feature-2.md
-```
-
 ### Customization
 
 If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key.

packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php

@@ -194,6 +194,7 @@ protected function normalizeGroupLabel(string $label): string
 
     protected function searchForGroupLabelInConfig(string $groupKey): ?string
     {
+        // TODO: Normalize this: sidebar_group_labels -> docs.sidebar.labels
         return $this->getConfigArray($this->generatesSidebar ? 'docs.sidebar_group_labels' : 'hyde.navigation.labels')[$groupKey] ?? null;
     }