Merge pull request #1481 from hydephp/customizable-automatic-sidebar-navigation-group-names

emmadesilva · web-flow · commit 108ba0f8139b · 2023-11-27T19:46:35.000+01:00
Add config option to customize automatic sidebar navigation group names
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -12,6 +12,7 @@ This serves two purposes:
 ### Added
 - Adds a new fancy output for the realtime compiler serve command in https://github.com/hydephp/develop/pull/1444
 - Added support for dot notation in the Yaml configuration files in https://github.com/hydephp/develop/pull/1478
+- Added a config option to customize automatic sidebar navigation group names in https://github.com/hydephp/develop/pull/1481
 
 ### Changed
 - The `docs.sidebar.footer` config option now accepts a Markdown string to replace the default footer in https://github.com/hydephp/develop/pull/1477
diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md
@@ -234,6 +234,23 @@ Link items without an entry here will have fall back to the default priority of
 
 See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br>
 
+### Automatic sidebar group labels
+
+When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names.
+If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file.
+The array key is the directory name, and the value is the label.
+
+Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself!
+
+```php
+// Filepath: config/docs.php
+
+'sidebar_group_labels' => [
+    'questions-and-answers' => 'Questions & Answers',
+],
+```
+
+
 ### Table of contents settings
 
 In the `config/docs.php` file you can configure the behavior, content, and the look and feel of the sidebar table of contents.
diff --git a/packages/framework/resources/views/components/docs/sidebar-items.blade.php b/packages/framework/resources/views/components/docs/sidebar-items.blade.php
@@ -11,7 +11,7 @@
         @foreach ($sidebar->getGroups() as $group)
             <li class="sidebar-group" role="listitem" @if($collapsible) x-data="{ groupOpen: {{ $sidebar->isGroupActive($group) ? 'true' : 'false' }} }" @endif>
                 <header class="sidebar-group-header p-2 px-4 -ml-2 flex justify-between items-center @if($collapsible) group hover:bg-black/10 @endif" @if($collapsible) @click="groupOpen = ! groupOpen" @endif>
-                    <h4 class="sidebar-group-heading text-base font-semibold @if($collapsible) cursor-pointer dark:group-hover:text-white @endif">{{ Hyde::makeTitle($group) }}</h4>
+                    <h4 class="sidebar-group-heading text-base font-semibold @if($collapsible) cursor-pointer dark:group-hover:text-white @endif">{{ $sidebar->makeGroupTitle($group) }}</h4>
                     @if($collapsible)
                         @include('hyde::components.docs.sidebar-group-toggle-button')
                     @endif
diff --git a/packages/framework/src/Framework/Features/Navigation/DocumentationSidebar.php b/packages/framework/src/Framework/Features/Navigation/DocumentationSidebar.php
@@ -4,6 +4,8 @@
 
 namespace Hyde\Framework\Features\Navigation;
 
+use Hyde\Hyde;
+use Hyde\Facades\Config;
 use Hyde\Foundation\Facades\Routes;
 use Hyde\Pages\DocumentationPage;
 use Hyde\Support\Facades\Render;
@@ -56,6 +58,11 @@ public function isGroupActive(string $group): bool
             || $this->isPageIndexPage() && $this->shouldIndexPageBeActive($group);
     }
 
+    public function makeGroupTitle(string $group): string
+    {
+        return Config::getNullableString("docs.sidebar_group_labels.$group") ?? Hyde::makeTitle($group);
+    }
+
     protected function canAddRoute(Route $route): bool
     {
         return parent::canAddRoute($route) && ! $route->is(DocumentationPage::homeRouteName());
diff --git a/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php b/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php
@@ -337,6 +337,24 @@ public function test_automatic_index_page_group_expansion_respects_custom_naviga
         $this->assertTrue(DocumentationSidebar::create()->isGroupActive('baz'));
     }
 
+    public function test_make_group_title_turns_group_key_into_title()
+    {
+        $this->assertSame('Hello World', DocumentationSidebar::create()->makeGroupTitle('hello world'));
+        $this->assertSame('Hello World', DocumentationSidebar::create()->makeGroupTitle('hello-world'));
+        $this->assertSame('Hello World', DocumentationSidebar::create()->makeGroupTitle('hello_world'));
+        $this->assertSame('Hello World', DocumentationSidebar::create()->makeGroupTitle('helloWorld'));
+    }
+
+    public function test_make_group_title_uses_configured_sidebar_group_labels_when_available()
+    {
+        Config::set('docs.sidebar_group_labels', [
+            'example' => 'Hello world!',
+        ]);
+
+        $this->assertSame('Hello world!', DocumentationSidebar::create()->makeGroupTitle('example'));
+        $this->assertSame('Default', DocumentationSidebar::create()->makeGroupTitle('default'));
+    }
+
     public function test_can_have_multiple_grouped_pages_with_the_same_name_labels()
     {
         $this->makePage('foo', ['navigation.group' => 'foo', 'navigation.label' => 'Foo']);
