From d657e6df30b4214c200b0e4206e042389f419f1a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 27 Nov 2023 18:45:10 +0100 Subject: [PATCH 1/3] Extract helper to generate documentation sidebar group name in class --- .../views/components/docs/sidebar-items.blade.php | 2 +- .../Features/Navigation/DocumentationSidebar.php | 6 ++++++ .../tests/Feature/Services/DocumentationSidebarTest.php | 8 ++++++++ 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/packages/framework/resources/views/components/docs/sidebar-items.blade.php b/packages/framework/resources/views/components/docs/sidebar-items.blade.php index cb9669c9c11..4c26062cf9f 100644 --- 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)
  • -

    {{ Hyde::makeTitle($group) }}

    +

    {{ $sidebar->makeGroupTitle($group) }}

    @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 index 6cf239a9661..bc89ad235bc 100644 --- a/packages/framework/src/Framework/Features/Navigation/DocumentationSidebar.php +++ b/packages/framework/src/Framework/Features/Navigation/DocumentationSidebar.php @@ -4,6 +4,7 @@ namespace Hyde\Framework\Features\Navigation; +use Hyde\Hyde; use Hyde\Foundation\Facades\Routes; use Hyde\Pages\DocumentationPage; use Hyde\Support\Facades\Render; @@ -56,6 +57,11 @@ public function isGroupActive(string $group): bool || $this->isPageIndexPage() && $this->shouldIndexPageBeActive($group); } + public function makeGroupTitle(string $group): string + { + return 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 index 9ac37522cc1..3fa4e074631 100644 --- a/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php +++ b/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php @@ -337,6 +337,14 @@ 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_can_have_multiple_grouped_pages_with_the_same_name_labels() { $this->makePage('foo', ['navigation.group' => 'foo', 'navigation.label' => 'Foo']); From 576d011e0962c584ab55db06b89012e3b441f718 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 27 Nov 2023 19:16:51 +0100 Subject: [PATCH 2/3] Add config feature to set automatic sidebar group labels Fixes https://github.com/hydephp/develop/issues/1467 --- docs/creating-content/documentation-pages.md | 17 +++++++++++++++++ .../Navigation/DocumentationSidebar.php | 3 ++- .../Services/DocumentationSidebarTest.php | 10 ++++++++++ 3 files changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index a2e36adb328..5a842ff183b 100644 --- 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.
    +### 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/src/Framework/Features/Navigation/DocumentationSidebar.php b/packages/framework/src/Framework/Features/Navigation/DocumentationSidebar.php index bc89ad235bc..919b93434a6 100644 --- a/packages/framework/src/Framework/Features/Navigation/DocumentationSidebar.php +++ b/packages/framework/src/Framework/Features/Navigation/DocumentationSidebar.php @@ -5,6 +5,7 @@ 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; @@ -59,7 +60,7 @@ public function isGroupActive(string $group): bool public function makeGroupTitle(string $group): string { - return Hyde::makeTitle($group); + return Config::getNullableString("docs.sidebar_group_labels.$group") ?? Hyde::makeTitle($group); } protected function canAddRoute(Route $route): bool diff --git a/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php b/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php index 3fa4e074631..5562c1ece44 100644 --- a/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php +++ b/packages/framework/tests/Feature/Services/DocumentationSidebarTest.php @@ -345,6 +345,16 @@ public function test_make_group_title_turns_group_key_into_title() $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']); From 09a587ae6d9067a6a2008581b21b9d2581a8ebe2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 27 Nov 2023 19:41:06 +0100 Subject: [PATCH 3/3] Update RELEASE_NOTES.md --- RELEASE_NOTES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 24b384a5e64..7309c20bf19 100644 --- 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