[2.x] Refactor navigation internals to store navigation in the kernel

.github/workflows/deploy-documentation-preview.yml

@@ -5,21 +5,25 @@ on:
     branches: [ "master" ]
     paths:
       - 'docs/**'
-      - '.github/workflows/deploy-documentation-preview.yml'
 
 jobs:
 
-  build-and-deploy-documentation-preview:
+  build-documentation-preview:
+    # We could add a check to only rerun if docs have changed since last run on the PR
+    # But this would require a state storage, and the current version is good enough.
     if: "! contains(github.event.pull_request.labels.*.name, 'pause-pages')"
 
     environment:
       name: pr-documentation-${{ github.event.pull_request.number }}
-      url: https://ci.hydephp.com/previews/develop/${{ github.event.pull_request.number }}
+      url: https://hydephp.github.io/develop/pr-${{ github.event.pull_request.number }}/dev-docs-preview
 
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.1"
 
       - name: Cache Composer packages
         id: composer-cache
@@ -45,7 +49,7 @@ jobs:
       - name: Update configuration files
         run: |
           echo "output_directories:" >> hyde.yml
-          echo "  Hyde\Pages\DocumentationPage: ''" >> hyde.yml
+          echo "  Hyde\Pages\DocumentationPage: dev-docs-preview" >> hyde.yml
           sed -i "s/'header' => env('SITE_NAME', 'HydePHP').' Docs'/'header' => 'PR #${{ github.event.pull_request.number }} - Docs'/g" config/docs.php
 
       - name: Remove published article component
@@ -83,36 +87,46 @@ jobs:
       - name: Configure environment variables
         run: |
           echo 'SITE_NAME="HydePHP Documentation Preview"' >> .env
-          echo 'SITE_URL="https://ci.hydephp.com/previews/develop/${{ github.event.pull_request.number }}"' >> .env
+          echo 'SITE_URL="https://hydephp.github.io/develop/pr-${{ github.event.pull_request.number }}/dev-docs-preview"' >> .env
 
       - name: Move documentation files
         run: rm -rf _docs && mv -f docs _docs
 
       - name: Compile the static site
         run: php hyde build
 
-      - name: Package the static site
-        run: zip -r site.zip _site
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v1
+        with:
+          name: 'preview-docs'
+          path: '_site/dev-docs-preview'
+
 
-      - name: Sign the artifact
-        run: |
-          echo '${{ secrets.CI_PREVIEW_SIGNING_RSA_PRIVATE_KEY }}' > private.pem
-          openssl dgst -sha256 -sign private.pem -out signature.bin site.zip
-          unlink private.pem
+  upload-generated-site:
+
+    runs-on: ubuntu-latest
+    needs:
+      - build-documentation-preview
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: 'gh-pages'
 
-      - name: Upload the artifact
+      - name: Reset output directories
         run: |
-            repository="develop"
-            bearerToken="${{ secrets.CI_SERVER_TOKEN }}"
-            pullRequest="${{ github.event.pull_request.number }}"
-            signature="$(openssl base64 -in signature.bin)"
-            artifact="site.zip"
-
-            curl -X POST --fail-with-body \
-              -H "Content-Type: multipart/form-data" \
-              -H "Authorization: Bearer $bearerToken" \
-              -F "repository=$repository" \
-              -F "pullRequest=$pullRequest" \
-              -F "artifact=@$artifact" \
-              -F "signature=$signature" \
-              https://ci.hydephp.com/api/deployment-previews
+          rm -rf pr-${{ github.event.pull_request.number }}/dev-docs-preview
+          mkdir -p pr-${{ github.event.pull_request.number }}/dev-docs-preview
+
+      - name: Download documentation artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: preview-docs
+          path: pr-${{ github.event.pull_request.number }}/dev-docs-preview
+
+      - name: Commit changes
+        uses: EndBug/add-and-commit@v9
+        with:
+          pull: 'origin gh-pages'
+          add: 'pr-${{ github.event.pull_request.number }}/dev-docs-preview'
+          message: 'Upload documentation preview for PR ${{ github.event.pull_request.number }}'

RELEASE_NOTES.md

@@ -11,10 +11,12 @@ 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 `NavItem::getLink()` method contain the previous `NavItem::getDestination()` logic, to return the link URL.
 
 ### Changed
 - 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.
+- The `NavItem::getDestination()` method now returns its `Route` instance if that is the destination type.
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -54,6 +56,14 @@ For more information, see https://github.com/hydephp/develop/pull/1498.
 
 ## Low impact
 
+### Navigation item changes
+
+The `NavItem::getDestination()` method now returns its `Route` instance if that is the destination type. This allows for deferring the route evaluation.
+
+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.
+
+If you want to retain the previous state where a string is always returned, you can use the new `NavItem::getLink()` method instead, which will resolve the route immediately.
+
 ### New documentation search implementation
 
 As the new documentation search implementation brings changes to their code API you may need to adapt your code

docs/creating-content/documentation-pages.md

@@ -100,8 +100,12 @@ and where the data is from as well as where it can be overridden.
 The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order
 of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings.
 
-Since this feature shares a lot of similarities and implementation details with the navigation menu,
-I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology.
+### Table of contents
+
+Hyde automatically generates a table of contents for the page and adds it to the sidebar.
+
+The behaviour of this can be changed in the configuration file.
+See [the customization page](customization#navigation-menu--sidebar) for more details.
 
 ### Sidebar ordering
 
@@ -133,7 +137,7 @@ Sidebar grouping allows you to group items in the sidebar into categories. This
 The Hyde docs for instance use this.
 
 The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set
-in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories.
+in the front matter. This will then switch to a slightly more compact sidebar layout with pages sorted into categories.
 Any pages without the group front matter will get put in the "Other" group.
 
 ### Sidebar footer customization
@@ -165,9 +169,7 @@ You can also automatically group your documentation pages by placing source file
 
 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 overwrite each other.
-
->info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key.
+>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.
 
 ### Hiding items
 
@@ -250,8 +252,6 @@ Please note that this option is not added to the config file by default, as it's
 
 ### Table of contents settings
 
-Hyde automatically generates a table of contents for the page and adds it to the sidebar.
-
 In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents.
 You can also disable the feature completely.
 

docs/digging-deeper/advanced-markdown.md

@@ -1,7 +1,7 @@
 ---
 navigation:
     label: "Advanced Markdown"
-    priority: 27
+    priority: 26
 ---
 
 # Advanced Markdown

docs/digging-deeper/customization.md

@@ -255,7 +255,7 @@ 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.
 
-Learn more in the [Navigation Menu](navigation) documentation.
+Learn more in the [Navigation Menu](navigation-menus) documentation.
 
 #### Customizing the documentation sidebar
 
@@ -264,6 +264,147 @@ Learn more in the [Navigation Menu](navigation) documentation.
 
 Learn more in the [Documentation Pages](documentation-pages) documentation.
 
+>info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key.
+
+### Primer on priorities
+
+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`,
+
+#### Basic syntax for changing the priorities
+
+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
+[
+    'readme', // Gets priority 500
+    'installation', // Gets priority 501
+    'getting-started', // Gets priority 502
+]
+```
+
+#### Explicit syntax for changing the priorities
+
+You can also specify explicit priorities by adding a value to the array key:
+
+```php
+[
+    'readme' => 10, // Gets priority 10
+    'installation' => 15, // Gets priority 15
+    'getting-started' => 20, // Gets priority 20
+]
+```
+
+You can also combine these options if you want:
+
+```php
+[
+    'readme' => 10, // Gets priority 10
+    'installation', // Gets priority 500
+    'getting-started', // Gets priority 501
+]
+```
+
+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: 25
+---
+```
+
+#### Changing the menu item labels
+
+Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles.
+You can override the label using the `navigation.label` front matter property.
+
+From the Hyde config you can also override the label of navigation links using the by mapping the route key
+to the desired title. Note that the front matter property will take precedence over the config property.
+
+```php
+// filepath config/hyde.php
+'navigation' => [
+    'labels' => [
+        'index' => 'Start',
+        'docs/index' => 'Documentation',
+    ]
+]
+```
+
+#### 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.
+
+```php
+// filepath config/hyde.php
+'navigation' => [
+    'exclude' => [
+        '404'
+    ]
+]
+```
+
+You can also specify that a page should be excluded by setting the page front matter.
+
+```markdown
+---
+navigation:
+    hidden: true
+---
+
+#### 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.
+
+```php
+// filepath config/hyde.php
+use Hyde\Framework\Features\Navigation\NavItem;
+
+'navigation' => [
+    'custom' => [
+        NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
+    ]
+]
+```
+
+Simplified, this will then be rendered as follows:
+
+```html
+<a href="https://github.com/hydephp/hyde">GitHub</a>
+```
+
+#### Automatic navigation menu dropdowns
+
+HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories.
+
+For pages that can be in the main site menu, ths feature needs to be enabled in the `hyde.php` config file.
+
+```php
+// filepath config/hyde.php
+
+'navigation' => [
+    'subdirectories' => 'dropdown',
+],
+```
+
+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 works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups.
+This feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped.
+
+For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started".
 
 ## Additional Advanced Options
 
@@ -325,7 +466,6 @@ use \Hyde\Framework\Services\AssetService;
 'hydefront_cdn_url' => AssetService::HYDEFRONT_CDN_URL,
 ```
 
-
 ## Blade Views
 
 Hyde uses the Laravel Blade templating engine. Most parts of the included templates have been extracted into components to be customized easily.
@@ -339,14 +479,12 @@ php hyde publish:views
 
 The files will then be available in the `resources/views/vendor/hyde` directory.
 
-
 ## Frontend Styles
 
 Hyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template
 for you to get up and running quickly. If you want to customize these, you are free to do so.
 Please see the [Managing Assets](managing-assets) page to learn more.
 
-
 ## Markdown Configuration
 
 Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML, and
@@ -409,7 +547,6 @@ arbitrary PHP code specified in Markdown to be executed. It's easy to enable how
 
 See the [Blade in Markdown](advanced-markdown#blade-support) documentation for more information on how to use this feature.
 
-
 ## YAML Configuration
 
 The settings in the `config/hyde.php` file can also be set by using a `hyde.yml` file in the root of your project directory.

packages/framework/resources/views/layouts/navigation.blade.php

@@ -1,5 +1,5 @@
 @php
-    $navigation = \Hyde\Framework\Features\Navigation\NavigationMenu::create();
+    $navigation = \Hyde\Hyde::navigation();
 @endphp
 
 <nav aria-label="Main navigation" id="main-navigation" class="flex flex-wrap items-center justify-between p-4 shadow-lg sm:shadow-xl md:shadow-none dark:bg-gray-800">