diff --git a/.github/dev-docs/RELEASE-NOTES-DRAFT.md b/.github/dev-docs/RELEASE-NOTES-DRAFT.md new file mode 100644 index 00000000..29403b4c --- /dev/null +++ b/.github/dev-docs/RELEASE-NOTES-DRAFT.md @@ -0,0 +1,26 @@ +# Draft for the release notes of upcoming HydePHP versions + +## Changes to the configuration files + +The entire configuration system has been refactored. + +### Snake_case is used for all configuration keys + +All configuration keys are now in the snake_case_format. Published configuration files will need to be updated accordingly. This is pretty fast in a modern code editor like VS Code. + +### Documentation options have been moved to a new file + +The documentation page specific options have been moved to the `config/docs.php` file. +You may need to republish Blade views if you have done so before. + +This is also easy to do in a modern code editor. See this example of the search and replace I used +to update the codebase: + +`hyde.docs_sidebar_header_title` => `docs.header_title` + + +### Deprecations and removals + +The deprecated option named `hyde.docs_directory` has been removed. + +Use `docs.output_directory` instead. \ No newline at end of file diff --git a/.github/dev-docs/documentation-pages.md b/.github/dev-docs/documentation-pages.md index 8ab3b162..edd28537 100644 --- a/.github/dev-docs/documentation-pages.md +++ b/.github/dev-docs/documentation-pages.md @@ -111,7 +111,7 @@ The default priority is 999. You can override the priority using the following f priority: 5 ``` -You can also change the order in the Hyde configuration file. +You can also change the order in the Docs configuration file. See [the chapter in the customization page](customization.html#navigation-menu--sidebar) for more details.
_I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._ @@ -162,20 +162,20 @@ including the documentation pages. Here is a high level overview for quick refer ### Output directory If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, -for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. +for example to specify a version like the Hyde docs does, you can specify the output directory in the Docs configuration file. ```php -'docs_directory' => 'docs' // default -'docs_directory' => 'docs/master' // What the Hyde docs use +'output_directory' => 'docs' // default +'output_directory' => 'docs/master' // What the Hyde docs use ``` ### Sidebar header name By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". -You can change this in the Hyde configuration file. +You can change this in the Docs configuration file. ```php -'docs_sidebar_header_title' => 'API Documentation', +'title' => 'API Documentation', ``` ### Sidebar page order @@ -184,7 +184,7 @@ To quickly arrange the order of items in the sidebar, you can reorder the page s Link items without an entry here will have fall back to the default priority of 999, putting them last. ```php -'documentation_page_order' => [ +'sidebar_order' => [ 'readme', 'installation', 'getting-started', @@ -196,11 +196,12 @@ See [the chapter in the customization page](customization.html#navigation-menu-- ### Table of contents settings -In the Hyde config you can configure the behavior, content, and the look and feel of the sidebar table of contents. +In the `config/docs.php` file you can configure the behavior, content, +and the look and feel of the sidebar table of contents. You can also disable the feature completely. ```php -'documentation_page_table_of_contents' => [ +'table_of_contents' => [ 'enabled' => true, 'min_heading_level' => 2, 'max_heading_level' => 4, diff --git a/config/docs.php b/config/docs.php new file mode 100644 index 00000000..01e6207a --- /dev/null +++ b/config/docs.php @@ -0,0 +1,84 @@ + config('hyde.name', 'HydePHP').' Docs', + + + /* + |-------------------------------------------------------------------------- + | Documentation Site Output Directory + |-------------------------------------------------------------------------- + | + | If you want to store the compiled documentation pages in a different + | directory than the default 'docs' directory, for example to set the + | specified version, you can specify the directory here. + | + | Note that you need to take care as to not set it to something that + | may conflict with other parts, such as media or posts directories. + | + | The default value is 'docs'. For easy versioning you can do what + | HydePHP.com does, setting it to 'docs/master'. + | + */ + + 'output_directory' => 'docs', + + + /* + |-------------------------------------------------------------------------- + | Sidebar Page Order + |-------------------------------------------------------------------------- + | + | In the generated Documentation pages the navigation links in the sidebar + | are sorted alphabetically by default. As this rarely makes sense, you + | can reorder the page slugs in the list and the links will be sorted + | in that order. Link items without an entry here will have fall + | back to the default priority of 999, putting them last. + | + | You can also set explicit priorities in front matter. + | + */ + + 'sidebar_order' => [ + 'readme', + 'installation', + 'getting-started', + ], + + /* + |-------------------------------------------------------------------------- + | Table of Contents Settings + |-------------------------------------------------------------------------- + | + | The Hyde Documentation Module comes with a fancy Sidebar that, by default, + | has a Table of Contents included. Here, you can configure its behavior, + | content, look and feel. You can also disable the feature completely. + | + */ + + 'table_of_contents' => [ + 'enabled' => true, + 'min_heading_level' => 2, + 'max_heading_level' => 4, + ], +]; \ No newline at end of file diff --git a/config/hyde.php b/config/hyde.php index f9640f53..f300a9ce 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -182,38 +182,7 @@ '404', ], - /* - |-------------------------------------------------------------------------- - | Documentation Sidebar Header Name - |-------------------------------------------------------------------------- - | - | By default, the sidebar title shown in the documentation page layouts uses - | the app name suffixed with "docs". You can change it with this setting. - | - */ - - 'docs_sidebar_header_title' => $siteName.' Docs', - - /* - |-------------------------------------------------------------------------- - | Documentation Site Output Directory - |-------------------------------------------------------------------------- - | - | If you want to store the compiled documentation pages in a different - | directory than the default 'docs' directory, for example to set the - | specified version, you can specify the directory here. - | - | Note that you need to take care as to not set it to something that - | may conflict with other parts, such as media or posts directories. - | - | The default value is 'docs'. - | - */ - - /** - * @deprecated version 0.25.0, will be renamed to documentationOutputPath - */ - 'docs_directory' => 'docs', + /* |-------------------------------------------------------------------------- @@ -230,41 +199,6 @@ 'site_output_path' => Hyde\Framework\Hyde::path('_site'), - /* - |-------------------------------------------------------------------------- - | Documentation Sidebar Page Order - |-------------------------------------------------------------------------- - | - | In the generated Documentation pages the navigation links in the sidebar - | are sorted alphabetically by default. As this rarely makes sense, you - | can reorder the page slugs in the list and the links will be sorted - | in that order. Link items without an entry here will have fall - | back to the default priority of 999, putting them last. - | - */ - - 'documentation_page_order' => [ - 'readme', - 'installation', - 'getting-started', - ], - - /* - |-------------------------------------------------------------------------- - | Documentation Table of Contents Settings - |-------------------------------------------------------------------------- - | - | The Hyde Documentation Module comes with a fancy Sidebar that, by default, - | has a Table of Contents included. Here, you can configure its behavior, - | content, look and feel. You can also disable the feature completely. - | - */ - - 'documentation_page_table_of_contents' => [ - 'enabled' => true, - 'min_heading_level' => 2, - 'max_heading_level' => 4, - ], /* |-------------------------------------------------------------------------- diff --git a/resources/views/layouts/docs.blade.php b/resources/views/layouts/docs.blade.php index a6def2f7..30cad9ce 100644 --- a/resources/views/layouts/docs.blade.php +++ b/resources/views/layouts/docs.blade.php @@ -15,10 +15,10 @@ @if(Hyde::docsIndexPath() !== false) - {{ config('hyde.docs_sidebar_header_title', 'Documentation') }} + {{ config('docs.title', 'Documentation') }} @else - {{ config('hyde.docs_sidebar_header_title', 'Documentation') }} + {{ config('docs.title', 'Documentation') }} @endif @include('hyde::components.navigation.theme-toggle-button') @@ -35,10 +35,10 @@ @if(Hyde::docsIndexPath() !== false) - {{ config('hyde.docs_sidebar_header_title', 'Documentation') }} + {{ config('docs.title', 'Documentation') }} @else - {{ config('hyde.docs_sidebar_header_title', 'Documentation') }} + {{ config('docs.title', 'Documentation') }} @endif @include('hyde::components.navigation.theme-toggle-button') diff --git a/src/Actions/GeneratesTableOfContents.php b/src/Actions/GeneratesTableOfContents.php index ae939194..7b853902 100644 --- a/src/Actions/GeneratesTableOfContents.php +++ b/src/Actions/GeneratesTableOfContents.php @@ -30,8 +30,8 @@ public function execute(): string 'html_class' => 'table-of-contents', 'position' => 'top', 'style' => 'bullet', - 'min_heading_level' => config('hyde.documentation_page_table_of_contents.min_heading_level', 2), - 'max_heading_level' => config('hyde.documentation_page_table_of_contents.max_heading_level', 4), + 'min_heading_level' => config('docs.table_of_contents.min_heading_level', 2), + 'max_heading_level' => config('docs.table_of_contents.max_heading_level', 4), 'normalize' => 'relative', ], 'heading_permalink' => [ diff --git a/src/Concerns/HasTableOfContents.php b/src/Concerns/HasTableOfContents.php index 06c584d9..e38ffbe8 100644 --- a/src/Concerns/HasTableOfContents.php +++ b/src/Concerns/HasTableOfContents.php @@ -15,7 +15,7 @@ trait HasTableOfContents public function constructTableOfContents(): void { - if (config('hyde.documentation_page_table_of_contents.enabled', true)) { + if (config('docs.table_of_contents.enabled', true)) { $this->tableOfContents = (new GeneratesTableOfContents($this->body))->execute(); } } diff --git a/src/Concerns/Internal/FileHelpers.php b/src/Concerns/Internal/FileHelpers.php index 2ad85cac..b3eaf03a 100644 --- a/src/Concerns/Internal/FileHelpers.php +++ b/src/Concerns/Internal/FileHelpers.php @@ -17,7 +17,7 @@ trait FileHelpers * * @deprecated will be renamed to be more distinct from other path helpers. * Naming suggestion is `getDocumentationOutputPath()`. - * The configuration is deprecated as well and will be renamed. + * The configuration option has been renamed. * * @todo Test and if needed add support for storing documentation files in the site root * @@ -25,7 +25,7 @@ trait FileHelpers */ public static function docsDirectory(): string { - return trim(config('hyde.docs_directory', 'docs'), '/\\'); + return trim(config('docs.output_directory', 'docs'), '/\\'); } /** diff --git a/src/Concerns/Markdown/HasMarkdownFeatures.php b/src/Concerns/Markdown/HasMarkdownFeatures.php index 74d3f274..889cf29f 100644 --- a/src/Concerns/Markdown/HasMarkdownFeatures.php +++ b/src/Concerns/Markdown/HasMarkdownFeatures.php @@ -11,6 +11,6 @@ trait HasMarkdownFeatures { public static function hasTableOfContents(): bool { - return config('hyde.documentation_page_table_of_contents.enabled', true); + return config('docs.table_of_contents.enabled', true); } } diff --git a/src/Models/DocumentationSidebarItem.php b/src/Models/DocumentationSidebarItem.php index ecb662ea..53b4fb11 100644 --- a/src/Models/DocumentationSidebarItem.php +++ b/src/Models/DocumentationSidebarItem.php @@ -30,7 +30,7 @@ public function __construct(string $label, string $destination, ?int $priority = protected function findPriorityInConfig(string $slug): int { - $orderIndexArray = config('hyde.documentationPageOrder', []); + $orderIndexArray = config('docs.sidebar_order', []); if (! in_array($slug, $orderIndexArray)) { return 500; diff --git a/tests/Feature/Services/DocumentationSidebarServiceTest.php b/tests/Feature/Services/DocumentationSidebarServiceTest.php index f5fada57..1ae0ce9e 100644 --- a/tests/Feature/Services/DocumentationSidebarServiceTest.php +++ b/tests/Feature/Services/DocumentationSidebarServiceTest.php @@ -79,7 +79,7 @@ public function test_files_with_front_matter_hidden_set_to_true_are_removed_from public function test_sidebar_is_ordered_alphabetically_when_no_order_is_set_in_config() { - Config::set('hyde.documentationPageOrder', []); + Config::set('docs.sidebar_order', []); touch(Hyde::path('_docs/alpha.md')); touch(Hyde::path('_docs/bravo.md')); touch(Hyde::path('_docs/charlie.md')); @@ -93,7 +93,7 @@ public function test_sidebar_is_ordered_alphabetically_when_no_order_is_set_in_c public function test_sidebar_is_ordered_by_priority_when_priority_is_set_in_config() { - Config::set('hyde.documentationPageOrder', [ + Config::set('docs.sidebar_order', [ 'charlie', 'bravo', 'alpha', @@ -127,14 +127,14 @@ public function test_sidebar_item_priority_set_in_config_overrides_front_matter( (new ConvertsArrayToFrontMatter)->execute(['priority' => 25]) ); - Config::set('hyde.documentationPageOrder', ['foo']); + Config::set('docs.sidebar_order', ['foo']); $this->assertEquals(25, DocumentationSidebarService::get()->first()->priority); } public function test_sidebar_priorities_can_be_set_in_both_front_matter_and_config() { - Config::set('hyde.documentationPageOrder', [ + Config::set('docs.sidebar_order', [ 'first', 'third', 'second', diff --git a/tests/Feature/Services/HasConfigurableMarkdownFeaturesTest.php b/tests/Feature/Services/HasConfigurableMarkdownFeaturesTest.php index e8b1bdf4..5c1c1461 100644 --- a/tests/Feature/Services/HasConfigurableMarkdownFeaturesTest.php +++ b/tests/Feature/Services/HasConfigurableMarkdownFeaturesTest.php @@ -95,7 +95,7 @@ public function test_has_features_array_can_enable_permalinks() // Test that method canEnablePermalinks is automatically for DocumentationPages public function test_has_features_array_can_enable_permalinks_auto() { - Config::set('hyde.documentationPageTableOfContents.enabled', true); + Config::set('docs.table_of_contents.enabled', true); $this->sourceModel = DocumentationPage::class; $this->assertTrue($this->canEnablePermalinks()); diff --git a/tests/Feature/StaticPageBuilderTest.php b/tests/Feature/StaticPageBuilderTest.php index c90a856d..76f022e6 100644 --- a/tests/Feature/StaticPageBuilderTest.php +++ b/tests/Feature/StaticPageBuilderTest.php @@ -106,7 +106,7 @@ public function test_creates_custom_documentation_directory() { $page = new DocumentationPage([], '# Body', 'Title', 'foo'); - Config::set('hyde.docsDirectory', 'docs/foo'); + Config::set('docs.output_directory', 'docs/foo'); new StaticPageBuilder($page, true); diff --git a/tests/Unit/HasMarkdownFeaturesTest.php b/tests/Unit/HasMarkdownFeaturesTest.php index 9b14727f..28b63622 100644 --- a/tests/Unit/HasMarkdownFeaturesTest.php +++ b/tests/Unit/HasMarkdownFeaturesTest.php @@ -17,10 +17,10 @@ public function test_has_table_of_contents() { $this->assertIsBool(static::hasTableOfContents()); - Config::set('hyde.documentationPageTableOfContents.enabled', true); + Config::set('docs.table_of_contents.enabled', true); $this->assertTrue(static::hasTableOfContents()); - Config::set('hyde.documentationPageTableOfContents.enabled', false); + Config::set('docs.table_of_contents.enabled', false); $this->assertFalse(static::hasTableOfContents()); } }