Merge pull request #1818 from hydephp/unify-the-navigation-api

[2.x] Unify the Navigation API

RELEASE_NOTES.md

@@ -15,6 +15,9 @@ This serves two purposes:
 - Added a new `\Hyde\Framework\Exceptions\ParseException` exception class to handle parsing exceptions in data collection files in https://github.com/hydephp/develop/pull/1732
 - Added a new `\Hyde\Framework\Exceptions\InvalidConfigurationException` exception class to handle invalid configuration exceptions in https://github.com/hydephp/develop/pull/1799
 - The `\Hyde\Facades\Features` class is no longer marked as internal, and is now thus part of the public API.
+- Added support for setting custom navigation items in the YAML configuration in https://github.com/hydephp/develop/pull/1818
+- Added support for setting extra attributes for navigation items in https://github.com/hydephp/develop/pull/1824
+- Introduced a new navigation config builder class to simplify navigation configuration in https://github.com/hydephp/develop/pull/1827
 
 ### 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.
@@ -23,6 +26,8 @@ This serves two purposes:
 - **Breaking:** The `hyde.authors` config setting should now be keyed by the usernames. For more information, see below.
 - **Breaking:** The `Author::create()` method now returns an array instead of a `PostAuthor` instance. For more information, see below.
 - **Breaking:** The `Author::get()` method now returns `null` if an author is not found, rather than creating a new instance. For more information, see below.
+- **Breaking:** The custom navigation item configuration now uses array inputs instead of the previous format. For more information, see the upgrade guide below.
+- **Breaking:** Renamed the `hyde.navigation.subdirectories` configuration option to `hyde.navigation.subdirectory_display`.
 - Medium: The `route` function will now throw a `RouteNotFoundException` if the route does not exist in https://github.com/hydephp/develop/pull/1741
 - 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.)
@@ -43,6 +48,8 @@ This serves two purposes:
 - Calling the `DataCollection` methods will no longer create the data collections directory in https://github.com/hydephp/develop/pull/1732
 - Markdown includes are now converted to HTML using the custom HydePHP Markdown service, meaning they now support full GFM spec and custom Hyde features like colored blockquotes and code block filepath labels in https://github.com/hydephp/develop/pull/1738
 - Markdown returned from includes are now trimmed of trailing whitespace and newlines in https://github.com/hydephp/develop/pull/1738
+- Reorganized and cleaned up the navigation and sidebar documentation for improved clarity.
+- Moved the sidebar documentation to the documentation pages section for better organization.
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -333,3 +340,78 @@ For example, an empty or malformed JSON file will now throw an exception like th
 
 In order to normalize the thrown exceptions, we now rethrow the `ParseException` from `Symfony/Yaml` as our custom `ParseException` to match the JSON and Markdown validation.
 Additionally, an exception will be thrown if a data file is empty, as this is unlikely to be intentional. Markdown files can have an empty body if front matter is present.
+
+## New features
+
+<!-- Editors note: Todo: Maybe move to the relevant docs... -->
+
+### Navigation configuration changes
+
+The custom navigation item configuration format has been updated to use array inputs. This change allows for more flexibility and consistency in defining navigation items.
+
+#### Old format:
+
+```php
+'navigation' => [
+    'custom_items' => [
+        'Custom Item' => '/custom-page',
+    ],
+],
+```
+
+#### New format:
+
+```php
+'navigation' => [
+    'custom_items' => [
+        ['label' => 'Custom Item', 'destination' => '/custom-page'],
+    ],
+],
+```
+
+Additionally, the `hyde.navigation.subdirectories` configuration option has been renamed to `hyde.navigation.subdirectory_display`. Update your configuration files accordingly.
+
+### YAML configuration for navigation items
+
+You can now set custom navigation items directly in your YAML configuration files. This provides an alternative to defining them in the PHP configuration files.
+
+Example:
+
+```yaml
+navigation:
+  custom_items:
+    - label: Custom Item
+      destination: /custom-page
+```
+
+### Extra attributes for navigation items
+
+Navigation items now support extra attributes, allowing you to add custom data or styling to your navigation elements. You can set these attributes in both PHP and YAML configurations.
+
+Example in PHP:
+
+```php
+'navigation' => [
+    'custom_items' => [
+        [
+            'label' => 'Custom Item',
+            'destination' => '/custom-page',
+            'attributes' => ['class' => 'special-link', 'target' => '_blank'],
+        ],
+    ],
+],
+```
+
+Example in YAML:
+
+```yaml
+navigation:
+  custom_items:
+    - label: Custom Item
+      destination: /custom-page
+      attributes:
+        class: special-link
+        target: _blank
+```
+
+These changes provide more flexibility and control over your site's navigation structure. Make sure to update your configuration files and any custom code that interacts with navigation items to align with these new formats and features.

app/config.php

@@ -97,6 +97,7 @@
         'Features' => \Hyde\Facades\Features::class,
         'Config' => \Hyde\Facades\Config::class,
         'Filesystem' => \Hyde\Facades\Filesystem::class,
+        'Navigation' => \Hyde\Facades\Navigation::class,
         'Routes' => \Hyde\Foundation\Facades\Routes::class,
         'HtmlPage' => \Hyde\Pages\HtmlPage::class,
         'BladePage' => \Hyde\Pages\BladePage::class,

config/hyde.php

@@ -25,6 +25,7 @@
 use Hyde\Facades\Author;
 use Hyde\Facades\Meta;
 use Hyde\Enums\Feature;
+use Hyde\Facades\Navigation;
 
 return [
 
@@ -331,40 +332,23 @@
     |
     */
 
-    'navigation' => [
-        // This configuration sets the priorities used to determine the order of the menu.
-        // The default values have been added below for reference and easy editing.
-        // The array key is the page's route key, the value is the priority.
-        // Lower values show up first in the menu. The default is 999.
-        'order' => [
+    'navigation' => Navigation::configure()
+        ->setPagePriorities([
             'index' => 0,
             'posts' => 10,
             'docs/index' => 100,
-        ],
-
-        // In case you want to customize the labels for the menu items, you can do so here.
-        // Simply add the route key as the array key, and the label as the value.
-        'labels' => [
+        ])
+        ->setPageLabels([
             'index' => 'Home',
             'docs/index' => 'Docs',
-        ],
-
-        // These are the route keys of pages that should not show up in the navigation menu.
-        'exclude' => [
+        ])
+        ->excludePages([
             '404',
-        ],
-
-        // Any extra links you want to add to the navigation menu can be added here.
-        // To get started quickly, you can uncomment the defaults here.
-        // See the documentation link above for more information.
-        'custom' => [
-            // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200),
-        ],
-
-        // How should pages in subdirectories be displayed in the menu?
-        // You can choose between 'dropdown', 'flat', and 'hidden'.
-        'subdirectories' => 'hidden',
-    ],
+        ])
+        ->addNavigationItems([
+            // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200),
+        ])
+        ->setSubdirectoryDisplayMode('hidden'),
 
     /*
     |--------------------------------------------------------------------------