Merge pull request #1432 from hydephp/normalize-navigation-menu-confi…

…guration-options

Support both route keys and identifiers for specifying sidebar order

config/docs.php

@@ -43,10 +43,11 @@
     | default to sort alphabetically. You can reorder the page identifiers
     | in the list below, and the links will get sorted in that order.
     |
-    | Internally, the items listed will get a position priority of 500 + the order its found in the list.
-    | Link items without an entry here will have fall back to the default priority of 999, putting them last.
+    | The items will get a priority of 500 plus the order its found in the list.
+    | Pages without a priority will fall back to the default priority of 999.
     |
-    | You can also set explicit priorities in front matter.
+    | You can also set explicit priorities in front matter or by specifying
+    | a value to the array key in the list to override the inferred value.
     |
     */
 

config/hyde.php

@@ -300,27 +300,31 @@
     |
     | If you are looking to customize the main navigation menu, this is the place!
     |
+    | All these settings uses Route Keys to identify the page you want to configure.
+    | A route key is simply the URL path to the page, without the file extension.
+    | So `_site/posts/hello-world.html` has the route key 'posts/hello-world'.
+    |
     */
 
     '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 should match the page's route key (slug).
-        // Lower values show up first in the menu.
+        // 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' => [
             '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 (slug) as the key, and the label as the value.
+        // Simply add the route key as the array key, and the label as the value.
         'labels' => [
             'index' => 'Home',
             'docs/index' => 'Docs',
         ],
 
-        // These are the pages that should not show up in the navigation menu.
+        // These are the route keys of pages that should not show up in the navigation menu.
         'exclude' => [
             '404',
         ],

packages/framework/config/docs.php

@@ -43,10 +43,11 @@
     | default to sort alphabetically. You can reorder the page identifiers
     | in the list below, and the links will get sorted in that order.
     |
-    | Internally, the items listed will get a position priority of 500 + the order its found in the list.
-    | Link items without an entry here will have fall back to the default priority of 999, putting them last.
+    | The items will get a priority of 500 plus the order its found in the list.
+    | Pages without a priority will fall back to the default priority of 999.
     |
-    | You can also set explicit priorities in front matter.
+    | You can also set explicit priorities in front matter or by specifying
+    | a value to the array key in the list to override the inferred value.
     |
     */
 

packages/framework/config/hyde.php

@@ -300,27 +300,31 @@
     |
     | If you are looking to customize the main navigation menu, this is the place!
     |
+    | All these settings uses Route Keys to identify the page you want to configure.
+    | A route key is simply the URL path to the page, without the file extension.
+    | So `_site/posts/hello-world.html` has the route key 'posts/hello-world'.
+    |
     */
 
     '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 should match the page's route key (slug).
-        // Lower values show up first in the menu.
+        // 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' => [
             '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 (slug) as the key, and the label as the value.
+        // Simply add the route key as the array key, and the label as the value.
         'labels' => [
             'index' => 'Home',
             'docs/index' => 'Docs',
         ],
 
-        // These are the pages that should not show up in the navigation menu.
+        // These are the route keys of pages that should not show up in the navigation menu.
         'exclude' => [
             '404',
         ],

packages/framework/src/Framework/Factories/NavigationDataFactory.php

@@ -162,7 +162,12 @@ private function searchForPriorityInSidebarConfig(): ?int
         /** @var array<string>|array<string, int> $config */
         $config = Config::getArray('docs.sidebar_order', []);
 
-        return $this->parseNavigationPriorityConfig($config);
+        return
+            // For consistency with the navigation config.
+            $this->parseNavigationPriorityConfig($config, 'routeKey')
+            // For backwards compatibility, and ease of use, as the route key prefix
+            // is redundant due to it being the same for all documentation pages
+            ?? $this->parseNavigationPriorityConfig($config, 'identifier');
     }
 
     private function searchForPriorityInNavigationConfig(): ?int
@@ -174,15 +179,13 @@ private function searchForPriorityInNavigationConfig(): ?int
             'docs/index' => 100,
         ]);
 
-        return $this->parseNavigationPriorityConfig($config);
+        return $this->parseNavigationPriorityConfig($config, 'routeKey');
     }
 
     /** @param array<string, int>|array<string> $config */
-    private function parseNavigationPriorityConfig(array $config): ?int
+    private function parseNavigationPriorityConfig(array $config, string $pageKeyName): ?int
     {
-        $pageKey = $this->isInstanceOf(DocumentationPage::class)
-            ? $this->identifier // Required for backwards compatibility.
-            : $this->routeKey;
+        $pageKey = $this->{$pageKeyName};
 
         // Check if the config entry is a flat array or a keyed array.
         if (! array_key_exists($pageKey, $config)) {

packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php

@@ -128,6 +128,24 @@ public function testSearchForPriorityInNavigationConfigForDocumentationPageSuppo
         $this->assertSame(999, $factory->makePriority());
     }
 
+    public function testRouteKeysCanBeUsedForDocumentationSidebarPriorities()
+    {
+        self::mockConfig(['docs.sidebar_order' => [
+            'key/foo',
+            'key/bar',
+            'baz',
+        ]]);
+
+        $factory = new NavigationConfigTestClass($this->makeCoreDataObject('foo', routeKey: 'key/foo', pageClass: DocumentationPage::class));
+        $this->assertSame(500, $factory->makePriority());
+
+        $factory = new NavigationConfigTestClass($this->makeCoreDataObject('bar', routeKey: 'key/bar', pageClass: DocumentationPage::class));
+        $this->assertSame(501, $factory->makePriority());
+
+        $factory = new NavigationConfigTestClass($this->makeCoreDataObject('baz', routeKey: 'key', pageClass: DocumentationPage::class));
+        $this->assertSame(502, $factory->makePriority());
+    }
+
     protected function makeCoreDataObject(string $identifier = '', string $routeKey = '', string $pageClass = MarkdownPage::class): CoreDataObject
     {
         return new CoreDataObject(new FrontMatter(), new Markdown(), $pageClass, $identifier, '', '', $routeKey);