diff --git a/config/docs.php b/config/docs.php index c26d702ed1c..fe9cf452fd5 100644 --- a/config/docs.php +++ b/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. | */ diff --git a/config/hyde.php b/config/hyde.php index f9126cb32df..0f83b8031a4 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -300,13 +300,17 @@ | | 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, @@ -314,13 +318,13 @@ ], // 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', ], diff --git a/packages/framework/config/docs.php b/packages/framework/config/docs.php index c26d702ed1c..fe9cf452fd5 100644 --- a/packages/framework/config/docs.php +++ b/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. | */ diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php index f9126cb32df..0f83b8031a4 100644 --- a/packages/framework/config/hyde.php +++ b/packages/framework/config/hyde.php @@ -300,13 +300,17 @@ | | 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, @@ -314,13 +318,13 @@ ], // 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', ], diff --git a/packages/framework/src/Framework/Factories/NavigationDataFactory.php b/packages/framework/src/Framework/Factories/NavigationDataFactory.php index 44dcf51b400..d9406d6f2ca 100644 --- a/packages/framework/src/Framework/Factories/NavigationDataFactory.php +++ b/packages/framework/src/Framework/Factories/NavigationDataFactory.php @@ -162,7 +162,12 @@ private function searchForPriorityInSidebarConfig(): ?int /** @var array|array $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|array $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)) { diff --git a/packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php b/packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php index 539d080fc04..a118c695723 100644 --- a/packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php +++ b/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);