From 135b008d05907e7b49397c9f7afae02397fa8db5 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 6 Nov 2023 20:28:14 +0100 Subject: [PATCH 1/5] Update the navigation configuration documentation --- config/docs.php | 7 ++++--- config/hyde.php | 12 ++++++++---- packages/framework/config/docs.php | 7 ++++--- packages/framework/config/hyde.php | 12 ++++++++---- 4 files changed, 24 insertions(+), 14 deletions(-) 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', ], From 3df56694121466456b4480e1930b0604cdefe26a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Tue, 7 Nov 2023 10:20:37 +0100 Subject: [PATCH 2/5] Extract helper method parameter instead of ternary check --- .../src/Framework/Factories/NavigationDataFactory.php | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/packages/framework/src/Framework/Factories/NavigationDataFactory.php b/packages/framework/src/Framework/Factories/NavigationDataFactory.php index 44dcf51b400..7f7d02b7342 100644 --- a/packages/framework/src/Framework/Factories/NavigationDataFactory.php +++ b/packages/framework/src/Framework/Factories/NavigationDataFactory.php @@ -162,7 +162,7 @@ private function searchForPriorityInSidebarConfig(): ?int /** @var array|array $config */ $config = Config::getArray('docs.sidebar_order', []); - return $this->parseNavigationPriorityConfig($config); + return $this->parseNavigationPriorityConfig($config, 'identifier'); } private function searchForPriorityInNavigationConfig(): ?int @@ -178,11 +178,9 @@ private function searchForPriorityInNavigationConfig(): ?int } /** @param array|array $config */ - private function parseNavigationPriorityConfig(array $config): ?int + private function parseNavigationPriorityConfig(array $config, string $pageKeyName = 'routeKey'): ?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)) { From 1a4b498d470889fa97aae520bd67add0b096c397 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Tue, 7 Nov 2023 10:22:07 +0100 Subject: [PATCH 3/5] Unwrap default value Will make the next refactor more readable --- .../src/Framework/Factories/NavigationDataFactory.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Framework/Factories/NavigationDataFactory.php b/packages/framework/src/Framework/Factories/NavigationDataFactory.php index 7f7d02b7342..95492b0e4f2 100644 --- a/packages/framework/src/Framework/Factories/NavigationDataFactory.php +++ b/packages/framework/src/Framework/Factories/NavigationDataFactory.php @@ -174,11 +174,11 @@ 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, string $pageKeyName = 'routeKey'): ?int + private function parseNavigationPriorityConfig(array $config, string $pageKeyName): ?int { $pageKey = $this->{$pageKeyName}; From 4622ee3cf794f56c0f7a228b63ff6b1f05ff4d39 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Tue, 7 Nov 2023 10:24:14 +0100 Subject: [PATCH 4/5] Support both route keys and identifiers for specifying sidebar order - Supports route keys for consistency with the navigation config. - Supports identifiers for backwards compatibility and ease of use, as the route key prefix is redundant due to it being the same for all documentation pages. --- .../Factories/NavigationDataFactory.php | 3 ++- .../Unit/NavigationDataFactoryUnitTest.php | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Factories/NavigationDataFactory.php b/packages/framework/src/Framework/Factories/NavigationDataFactory.php index 95492b0e4f2..be6655de73e 100644 --- a/packages/framework/src/Framework/Factories/NavigationDataFactory.php +++ b/packages/framework/src/Framework/Factories/NavigationDataFactory.php @@ -162,7 +162,8 @@ private function searchForPriorityInSidebarConfig(): ?int /** @var array|array $config */ $config = Config::getArray('docs.sidebar_order', []); - return $this->parseNavigationPriorityConfig($config, 'identifier'); + return $this->parseNavigationPriorityConfig($config, 'routeKey') // For consistency with the navigation config. + ?? $this->parseNavigationPriorityConfig($config, 'identifier'); // For backwards compatibility and ease of use } private function searchForPriorityInNavigationConfig(): ?int 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); From dd896f78592be407c7e83b87928fe2614bec6172 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Tue, 7 Nov 2023 10:38:41 +0100 Subject: [PATCH 5/5] Better document code --- .../src/Framework/Factories/NavigationDataFactory.php | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Framework/Factories/NavigationDataFactory.php b/packages/framework/src/Framework/Factories/NavigationDataFactory.php index be6655de73e..d9406d6f2ca 100644 --- a/packages/framework/src/Framework/Factories/NavigationDataFactory.php +++ b/packages/framework/src/Framework/Factories/NavigationDataFactory.php @@ -162,8 +162,12 @@ private function searchForPriorityInSidebarConfig(): ?int /** @var array|array $config */ $config = Config::getArray('docs.sidebar_order', []); - return $this->parseNavigationPriorityConfig($config, 'routeKey') // For consistency with the navigation config. - ?? $this->parseNavigationPriorityConfig($config, 'identifier'); // For backwards compatibility and ease of use + 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