Merge pull request #1583 from hydephp/normalize-navigation-configuration-api

[2.x] Breaking: Change configuration option `docs.sidebar_order` to `docs.sidebar.order`

Author: emmadesilva

config/docs.php

@@ -33,29 +33,29 @@
         // Should the sidebar footer be shown? You can also set this to a string
         // of Markdown to show in the footer. Set to `false` to disable.
         'footer' => true,
-    ],
-
-    /*
-    |--------------------------------------------------------------------------
-    | Sidebar Page Order
-    |--------------------------------------------------------------------------
-    |
-    | In the generated Documentation pages the navigation links in the sidebar
-    | default to sort alphabetically. You can reorder the page identifiers
-    | in the list below, and the links will get sorted in that order.
-    |
-    | 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 or by specifying
-    | a value to the array key in the list to override the inferred value.
-    |
-    */
 
-    'sidebar_order' => [
-        'readme',
-        'installation',
-        'getting-started',
+        /*
+        |--------------------------------------------------------------------------
+        | Sidebar Page Order
+        |--------------------------------------------------------------------------
+        |
+        | In the generated Documentation pages the navigation links in the sidebar
+        | default to sort alphabetically. You can reorder the page identifiers
+        | in the list below, and the links will get sorted in that order.
+        |
+        | 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 or by specifying
+        | a value to the array key in the list to override the inferred value.
+        |
+        */
+
+        'order' => [
+            'readme',
+            'installation',
+            'getting-started',
+        ],
     ],
 
     /*

docs/creating-content/documentation-pages.md

@@ -223,10 +223,12 @@ To quickly arrange the order of items in the sidebar, you can reorder the page i
 Link items without an entry here will fall back to the default priority of 999, putting them last.
 
 ```php
-'sidebar_order' => [
-    'readme',
-    'installation',
-    'getting-started',
+'sidebar' => [
+    'order' => [
+        'readme',
+        'installation',
+        'getting-started',
+    ],
 ]
 ```
 

docs/digging-deeper/customization.md

@@ -259,7 +259,7 @@ Learn more in the [Navigation Menu](navigation) documentation.
 
 #### Customizing the documentation sidebar
 
-- To customize the sidebar, use the setting `sidebar_order` in the `docs.php` config.
+- To customize the sidebar, use the setting `sidebar.order` in the `docs.php` config.
 - When customizing the sidebar, can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page.
 
 Learn more in the [Documentation Pages](documentation-pages) documentation.

docs/digging-deeper/navigation.md

@@ -122,12 +122,12 @@ Next up, let's look at how to customize the navigation menus using the config fi
 - 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.
 
-- To customize the sidebar, use the setting `sidebar_order` in the `docs.php` config.
+- To customize the sidebar, use the setting `sidebar.order` in the `docs.php` config.
 - When customizing the sidebar, can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page.
 
 ### Changing the priorities
 
-The `navigation.order` and `sidebar_order` settings allow you to customize the order of the pages in the navigation menus.
+The `navigation.order` and `sidebar.order` settings allow you to customize the order of the pages in the navigation menus.
 
 #### Basic syntax for changing the priorities
 
@@ -149,10 +149,12 @@ The offset is added to make it easier to place pages earlier in the list using f
 ```php
 // filepath: config/docs.php
 
-'sidebar_order' => [
-    'readme', // Gets priority 500
-    'installation', // Gets priority 501
-    'getting-started', // Gets priority 502
+'sidebar' => [
+    'order' => [
+        'readme', // Gets priority 500
+        'installation', // Gets priority 501
+        'getting-started', // Gets priority 502
+    ]
 ]
 ```
 
@@ -175,10 +177,12 @@ You can also specify explicit priorities by adding a value to the array key:
 ```php
 // filepath: config/docs.php
 
-'sidebar_order' => [
-    'readme' => 10, // Gets priority 10
-    'installation' => 15, // Gets priority 15
-    'getting-started' => 20, // Gets priority 20
+'sidebar' => [
+    'order' => [
+        'readme' => 10, // Gets priority 10
+        'installation' => 15, // Gets priority 15
+        'getting-started' => 20, // Gets priority 20
+    ]
 ]
 ```
 

packages/framework/config/docs.php

@@ -33,29 +33,29 @@
         // Should the sidebar footer be shown? You can also set this to a string
         // of Markdown to show in the footer. Set to `false` to disable.
         'footer' => true,
-    ],
-
-    /*
-    |--------------------------------------------------------------------------
-    | Sidebar Page Order
-    |--------------------------------------------------------------------------
-    |
-    | In the generated Documentation pages the navigation links in the sidebar
-    | default to sort alphabetically. You can reorder the page identifiers
-    | in the list below, and the links will get sorted in that order.
-    |
-    | 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 or by specifying
-    | a value to the array key in the list to override the inferred value.
-    |
-    */
 
-    'sidebar_order' => [
-        'readme',
-        'installation',
-        'getting-started',
+        /*
+        |--------------------------------------------------------------------------
+        | Sidebar Page Order
+        |--------------------------------------------------------------------------
+        |
+        | In the generated Documentation pages the navigation links in the sidebar
+        | default to sort alphabetically. You can reorder the page identifiers
+        | in the list below, and the links will get sorted in that order.
+        |
+        | 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 or by specifying
+        | a value to the array key in the list to override the inferred value.
+        |
+        */
+
+        'order' => [
+            'readme',
+            'installation',
+            'getting-started',
+        ],
     ],
 
     /*

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

@@ -160,7 +160,7 @@ private function searchForPriorityInConfigs(): ?int
     private function searchForPriorityInSidebarConfig(): ?int
     {
         /** @var array<string>|array<string, int> $config */
-        $config = Config::getArray('docs.sidebar_order', []);
+        $config = Config::getArray('docs.sidebar.order', []);
 
         return
             // For consistency with the navigation config.

packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php

@@ -182,7 +182,7 @@ protected function searchForGroupLabelInConfig(string $groupKey): ?string
 
     protected function searchForGroupPriorityInConfig(string $groupKey): ?int
     {
-        $key = $this->generatesSidebar ? 'docs.sidebar_order' : 'hyde.navigation.order';
+        $key = $this->generatesSidebar ? 'docs.sidebar.order' : 'hyde.navigation.order';
 
         return Config::getArray($key, [])[$groupKey] ?? null;
     }

packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php

@@ -745,17 +745,15 @@ public function testSidebarWithFrontMatterGroupAndCategory()
 
     public function testSidebarWithConfigOrder()
     {
-        // TODO should be sidebar.order instead of docs.sidebar_order
-
-        config(['docs.sidebar_order' => ['first', 'second', 'third']]);
+        config(['docs.sidebar.order' => ['first', 'second', 'third']]);
 
         $this->assertSidebarEquals(['First', 'Second', 'Third'], [
             new DocumentationPage('first'),
             new DocumentationPage('second'),
             new DocumentationPage('third'),
         ]);
 
-        config(['docs.sidebar_order' => ['third', 'second', 'first']]);
+        config(['docs.sidebar.order' => ['third', 'second', 'first']]);
 
         $this->assertSidebarEquals(['Third', 'Second', 'First'], [
             new DocumentationPage('first'),
@@ -776,7 +774,7 @@ public function testSidebarWithConfigOrderHasInferredPriorities()
             new DocumentationPage('third'),
         ]);
 
-        config(['docs.sidebar_order' => ['first', 'second', 'third']]);
+        config(['docs.sidebar.order' => ['first', 'second', 'third']]);
 
         $this->assertSidebarEquals([
             ['priority' => 500],
@@ -791,23 +789,23 @@ public function testSidebarWithConfigOrderHasInferredPriorities()
 
     public function testSidebarWithExplicitConfigOrder()
     {
-        config(['docs.sidebar_order' => ['first' => 1, 'second' => 2, 'third' => 3]]);
+        config(['docs.sidebar.order' => ['first' => 1, 'second' => 2, 'third' => 3]]);
 
         $this->assertSidebarEquals(['First', 'Second', 'Third'], [
             new DocumentationPage('first'),
             new DocumentationPage('second'),
             new DocumentationPage('third'),
         ]);
 
-        config(['docs.sidebar_order' => ['first' => 3, 'second' => 2, 'third' => 1]]);
+        config(['docs.sidebar.order' => ['first' => 3, 'second' => 2, 'third' => 1]]);
 
         $this->assertSidebarEquals(['Third', 'Second', 'First'], [
             new DocumentationPage('first'),
             new DocumentationPage('second'),
             new DocumentationPage('third'),
         ]);
 
-        config(['docs.sidebar_order' => ['first' => 1, 'second' => 2, 'third' => 3]]);
+        config(['docs.sidebar.order' => ['first' => 1, 'second' => 2, 'third' => 3]]);
 
         $this->assertSidebarEquals([
             ['label' => 'First', 'priority' => 1],
@@ -822,7 +820,7 @@ public function testSidebarWithExplicitConfigOrder()
 
     public function testSidebarWithMixedConfigOrders()
     {
-        config(['docs.sidebar_order' => ['foo', 'bar' => 650]]);
+        config(['docs.sidebar.order' => ['foo', 'bar' => 650]]);
 
         $this->assertSidebarEquals([
             ['label' => 'Foo', 'priority' => 500],
@@ -1059,7 +1057,7 @@ public function testSidebarGroupsAreSortedByLowestFoundPriorityInEachGroupUnless
             new DocumentationPage('baz', ['navigation.group' => 'c', 'navigation.priority' => 10]),
         ]);
 
-        config(['docs.sidebar_order' => ['a' => 5]]);
+        config(['docs.sidebar.order' => ['a' => 5]]);
 
         $this->assertSidebarEquals([
             'A', 'C', 'B',
@@ -1117,7 +1115,7 @@ public function testMainNavigationDropdownPriorityCanBeSetInConfigUsingDiffering
 
     public function testSidebarGroupPriorityCanBeSetInConfig()
     {
-        config(['docs.sidebar_order' => ['foo' => 500]]);
+        config(['docs.sidebar.order' => ['foo' => 500]]);
 
         $this->assertSidebarEquals(
             [['label' => 'Foo', 'priority' => 500]],
@@ -1127,7 +1125,7 @@ public function testSidebarGroupPriorityCanBeSetInConfig()
 
     public function testSidebarGroupPriorityCanBeSetInConfigUsingDifferingCases()
     {
-        config(['docs.sidebar_order' => ['hello-world' => 500]]);
+        config(['docs.sidebar.order' => ['hello-world' => 500]]);
 
         $expected = [['label' => 'Hello World', 'priority' => 500]];
         $this->assertSidebarEquals($expected, [new DocumentationPage('Hello World/bar')]);

packages/framework/tests/Feature/Services/DocumentationSidebarTest.php

@@ -77,7 +77,7 @@ public function testFilesWithFrontMatterHiddenSetToTrueAreRemovedFromSidebar()
 
     public function testSidebarIsOrderedAlphabeticallyWhenNoOrderIsSetInConfig()
     {
-        Config::set('docs.sidebar_order', []);
+        Config::set('docs.sidebar.order', []);
         Filesystem::touch('_docs/a.md');
         Filesystem::touch('_docs/b.md');
         Filesystem::touch('_docs/c.md');
@@ -94,7 +94,7 @@ public function testSidebarIsOrderedAlphabeticallyWhenNoOrderIsSetInConfig()
 
     public function testSidebarIsOrderedByPriorityWhenPriorityIsSetInConfig()
     {
-        Config::set('docs.sidebar_order', [
+        Config::set('docs.sidebar.order', [
             'c',
             'b',
             'a',
@@ -124,14 +124,14 @@ public function testSidebarItemPrioritySetInConfigOverridesFrontMatter()
     {
         $this->makePage('foo', ['navigation.priority' => 25]);
 
-        Config::set('docs.sidebar_order', ['foo']);
+        Config::set('docs.sidebar.order', ['foo']);
 
         $this->assertEquals(25, NavigationMenuGenerator::handle(DocumentationSidebar::class)->getItems()->first()->getPriority());
     }
 
     public function testSidebarPrioritiesCanBeSetInBothFrontMatterAndConfig()
     {
-        Config::set('docs.sidebar_order', [
+        Config::set('docs.sidebar.order', [
             'first',
             'third',
             'second',

packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php

@@ -74,7 +74,7 @@ public function testSearchForPriorityInNavigationConfigForMarkdownPageSupportsMi
 
     public function testSearchForPriorityInNavigationConfigForDocumentationPageWithListConfig()
     {
-        self::mockConfig(['docs.sidebar_order' => [
+        self::mockConfig(['docs.sidebar.order' => [
             'foo' => 15,
             'bar' => 10,
         ]]);
@@ -88,7 +88,7 @@ public function testSearchForPriorityInNavigationConfigForDocumentationPageWithL
 
     public function testSearchForPriorityInNavigationConfigForDocumentationPageWithKeyedConfig()
     {
-        self::mockConfig(['docs.sidebar_order' => [
+        self::mockConfig(['docs.sidebar.order' => [
             'foo',
             'bar' => 10,
             'baz',
@@ -109,7 +109,7 @@ public function testSearchForPriorityInNavigationConfigForDocumentationPageWithK
 
     public function testSearchForPriorityInNavigationConfigForDocumentationPageSupportsMixingKeyedAndListConfig()
     {
-        self::mockConfig(['docs.sidebar_order' => [
+        self::mockConfig(['docs.sidebar.order' => [
             'foo',
             'bar' => 10,
             'baz',
@@ -130,7 +130,7 @@ public function testSearchForPriorityInNavigationConfigForDocumentationPageSuppo
 
     public function testRouteKeysCanBeUsedForDocumentationSidebarPriorities()
     {
-        self::mockConfig(['docs.sidebar_order' => [
+        self::mockConfig(['docs.sidebar.order' => [
             'key/foo',
             'key/bar',
             'baz',