From 0ff38901ad7097ba71afbad960688c8f81448bd3 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Tue, 7 Nov 2023 11:19:17 +0100 Subject: [PATCH 1/6] Move up tip to text body --- docs/creating-content/documentation-pages.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index c3694d3350f..a8ce3d5b3df 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -199,14 +199,12 @@ By default, a link to the documentation page is added to the navigation menu whe ### 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 Docs configuration file. +You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. ```php 'title' => 'API Documentation', ``` ->info Tip: The header will link to the docs/index page, if it exists. - ### Sidebar page order To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. From 4e61340f27c8b9a081764c6b21cbcc0de0fe4792 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Tue, 7 Nov 2023 11:19:52 +0100 Subject: [PATCH 2/6] Use less absolute language --- docs/digging-deeper/customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index daf4f24f7b8..b0b2e74c68b 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -56,7 +56,7 @@ In some cases, the same options can be set in the front matter of a page or in a ### A note on file paths When Hyde references files, especially when passing filenames between components, the file path is almost always -relative to the root of the project. Specifying absolute paths yourself will likely lead to unforeseen problems. +relative to the root of the project. Specifying absolute paths yourself could lead to unforeseen problems. ## Configuration Files Overview From 1523eb7e49c94e5f5e26e589dbabdb6d4957d672 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sun, 12 Nov 2023 15:33:59 +0100 Subject: [PATCH 3/6] Clarify language --- docs/architecture-concepts/architecture-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture-concepts/architecture-concepts.md b/docs/architecture-concepts/architecture-concepts.md index a1e76e4ded9..077fc8e0fc0 100644 --- a/docs/architecture-concepts/architecture-concepts.md +++ b/docs/architecture-concepts/architecture-concepts.md @@ -8,7 +8,7 @@ navigation: ## Introduction -These chapters are written for power users and contributors. If you're just looking to get a site up and running, +These chapters are written for power users and package contributors. If you're just looking to get a site up and running, you can safely skip this section. The documentation here will cover advanced topics under the presumption that the reader has a basic to intermediate understanding of programming, as well as PHP, object-oriented design, and to some extent Laravel, as the articles are heavily driven by code examples. From 73e569006f920846a7508235820773fbc6e69a07 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sun, 12 Nov 2023 15:39:24 +0100 Subject: [PATCH 4/6] Create navigation-menus.md --- docs/digging-deeper/navigation-menus.md | 176 ++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/digging-deeper/navigation-menus.md diff --git a/docs/digging-deeper/navigation-menus.md b/docs/digging-deeper/navigation-menus.md new file mode 100644 index 00000000000..979a08b7d22 --- /dev/null +++ b/docs/digging-deeper/navigation-menus.md @@ -0,0 +1,176 @@ +--- +navigation: + label: "Navigation Menus" + priority: 30 +--- + +# Navigation Menu & Sidebar + +## Introduction + +A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation. +Hyde is designed to automatically configure these menus for you based on the content you have in your project. +You will likely want to customize some parts of these menus, and thankfully, Hyde makes it easy to do so. + +## How navigation menus work + +To better understand how to customize the navigation menus, it's beneficial to have a high level understanding of how +they are generated by HydePHP. You can of course skip this section if you prefer to just dive in to the customization. + +### Discovery + +The sidebar works by creating a list of all the documentation pages. If your documentation is organized in subdirectories, +those will be used to create sidebar category groups. + +The main navigation menu is a bit more sophisticated and adds all the top-level Blade, Markdown, and HTML pages. +Blog posts and documentation pages are not added to the navigation menu, however, if you have an `index.md` in your +documentation source directory, a link to it will be added to the navigation menu. + +As the documentation sidebar and navigation menu are based on the same logic, they share many of the same options. + +### Priorities + +All navigation menu items have an internal priority value that determines its order in the navigation. +A lower value means that the item will be higher up in the menu. + +Hyde makes an effort to sort navigation menu items in a sensible way and thus automatically assigns some +default priorities for common use cases, for example, the index page defaults to a priority of `0`, +putting it first. The default for other pages is `999` which puts them last. You can specify an explicit +priority in the front matter, or the configuration file to override the inferred priority. + +## Reordering items in the config + +Reordering items in the configuration is as easy can be. + +While the syntax is the same for both the navigation menu and the sidebar, the place in which to do so differs. + +To change the main navigation, use the setting `navigation.order` in the `hyde.php` config. +To change the sidebar, use the setting `docs.sidebar_order` in the `docs.php` config. + +Keep in mind, that when specifying main navigation items, you should use the route key of the page. +For documentation pages, you should use the page identifier. (Learn more about route keys and page identifiers in the +[Core Concepts](core-concepts#paths-identifiers-and-route-keys) documentation) + +There are two ways two do this. + +The cleanest way is to use the list-style syntax. + +sidebar is as easy as can be. In the `docs` config, there is an array just for this. +If a page identifier is found here it will get priority calculated according to its position in the list, +plus an offset of 500. This offset allows you to pages earlier in the list using front matter. + +If a page does not exist in the list they get priority 999, which puts them last. +You can also use front matter to set a priority for a page. +The front matter value will always take precedence. + +Let's see an example: + +```php +// filepath: config/docs.php +// These are the default values in the config. It puts the readme.md first in order. +'sidebar_order' => [ + 'readme', // This is the first entry, so it gets the priority 500 + 0 + 'installation', // This gets priority 500 + 1 + 'getting-started', // And this gets priority 500 + 2 + // Any other pages not listed will get priority 999 +] +``` + +### Reordering Navigation Menu Items + +As Hyde makes an effort to organize the menu items in a sensible way, your project comes preconfigured to put what it thinks are your most +important pages first. This may of course not always match what you want, so thankfully it's easy to reorder the menu items! + +Simply update the `navigation.order` array in the Hyde config! The priorities set will determine the order of the menu items. +Lower values are higher in the menu, and any pages not listed will get priority 999, which puts them last. + +```php +// filepath config/hyde.php +'navigation' => [ + 'order' => [ + 'index' => 0, // _pages/index.md (or .blade.php) + 'posts' => 10, // _pages/posts.md (or .blade.php) + 'docs/index' => 100, // _docs/index.md + ] +] +``` + +## Reordering items with front matter + +You can also set the priority of a page directly in the front matter. This will override any dynamically inferred or +config defined priority. While this is useful for one-offs, it can make it harder to reorder items later on. +It's up to you which method you prefer to use. This setting can be used both for the navigation menu and the sidebar. + +```markdown +--- +navigation: + priority: 10 +--- +``` + +>info Tip: If you are using automatic subdirectory dropdowns, you can also set their priority in the config. Just use the directory name instead of the page identifier. + +### Adding Custom Navigation Menu Links + +You can easily add custom navigation menu links similar how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array. + +When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the +destination and label, both required. Third argument is the priority, which is optional, and defaults to 500. + +```php +// filepath config/hyde.php +use Hyde\Framework\Features\Navigation\NavItem; + +'navigation' => [ + 'custom' => [ + NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200), + ] +] +``` + +Simplified, this will then be rendered as follows: + +```html +GitHub +``` + +### Excluding Items (Blacklist) + +Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu. +To remove items from being automatically added, simply add the page's route key to the blacklist. +As you can see, the `404` page has already been filled in for you. + +```php +'navigation' => [ + 'exclude' => [ + '404' + ] +] +``` + +You can also specify that a page should be excluded by setting the page front matter. + +```markdown +--- +navigation: + hidden: true +--- +``` + +### Changing the menu item labels + +Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. +You can override the label using the `navigation.label` front matter property. + +From the Hyde config you can also override the label of navigation links using the by mapping the route key +to the desired title. Note that the front matter property will take precedence over the config property. + +```php +// filepath config/hyde.php +'navigation' => [ + 'labels' => [ + 'index' => 'Start', + 'docs/index' => 'Documentation', + ] +] +``` From 3af93b9fb27a8570e99c1132b34e5fd269cd9e4e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sun, 12 Nov 2023 15:39:27 +0100 Subject: [PATCH 5/6] Revert "Create navigation-menus.md" This reverts commit 73e569006f920846a7508235820773fbc6e69a07. --- docs/digging-deeper/navigation-menus.md | 176 ------------------------ 1 file changed, 176 deletions(-) delete mode 100644 docs/digging-deeper/navigation-menus.md diff --git a/docs/digging-deeper/navigation-menus.md b/docs/digging-deeper/navigation-menus.md deleted file mode 100644 index 979a08b7d22..00000000000 --- a/docs/digging-deeper/navigation-menus.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -navigation: - label: "Navigation Menus" - priority: 30 ---- - -# Navigation Menu & Sidebar - -## Introduction - -A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation. -Hyde is designed to automatically configure these menus for you based on the content you have in your project. -You will likely want to customize some parts of these menus, and thankfully, Hyde makes it easy to do so. - -## How navigation menus work - -To better understand how to customize the navigation menus, it's beneficial to have a high level understanding of how -they are generated by HydePHP. You can of course skip this section if you prefer to just dive in to the customization. - -### Discovery - -The sidebar works by creating a list of all the documentation pages. If your documentation is organized in subdirectories, -those will be used to create sidebar category groups. - -The main navigation menu is a bit more sophisticated and adds all the top-level Blade, Markdown, and HTML pages. -Blog posts and documentation pages are not added to the navigation menu, however, if you have an `index.md` in your -documentation source directory, a link to it will be added to the navigation menu. - -As the documentation sidebar and navigation menu are based on the same logic, they share many of the same options. - -### Priorities - -All navigation menu items have an internal priority value that determines its order in the navigation. -A lower value means that the item will be higher up in the menu. - -Hyde makes an effort to sort navigation menu items in a sensible way and thus automatically assigns some -default priorities for common use cases, for example, the index page defaults to a priority of `0`, -putting it first. The default for other pages is `999` which puts them last. You can specify an explicit -priority in the front matter, or the configuration file to override the inferred priority. - -## Reordering items in the config - -Reordering items in the configuration is as easy can be. - -While the syntax is the same for both the navigation menu and the sidebar, the place in which to do so differs. - -To change the main navigation, use the setting `navigation.order` in the `hyde.php` config. -To change the sidebar, use the setting `docs.sidebar_order` in the `docs.php` config. - -Keep in mind, that when specifying main navigation items, you should use the route key of the page. -For documentation pages, you should use the page identifier. (Learn more about route keys and page identifiers in the -[Core Concepts](core-concepts#paths-identifiers-and-route-keys) documentation) - -There are two ways two do this. - -The cleanest way is to use the list-style syntax. - -sidebar is as easy as can be. In the `docs` config, there is an array just for this. -If a page identifier is found here it will get priority calculated according to its position in the list, -plus an offset of 500. This offset allows you to pages earlier in the list using front matter. - -If a page does not exist in the list they get priority 999, which puts them last. -You can also use front matter to set a priority for a page. -The front matter value will always take precedence. - -Let's see an example: - -```php -// filepath: config/docs.php -// These are the default values in the config. It puts the readme.md first in order. -'sidebar_order' => [ - 'readme', // This is the first entry, so it gets the priority 500 + 0 - 'installation', // This gets priority 500 + 1 - 'getting-started', // And this gets priority 500 + 2 - // Any other pages not listed will get priority 999 -] -``` - -### Reordering Navigation Menu Items - -As Hyde makes an effort to organize the menu items in a sensible way, your project comes preconfigured to put what it thinks are your most -important pages first. This may of course not always match what you want, so thankfully it's easy to reorder the menu items! - -Simply update the `navigation.order` array in the Hyde config! The priorities set will determine the order of the menu items. -Lower values are higher in the menu, and any pages not listed will get priority 999, which puts them last. - -```php -// filepath config/hyde.php -'navigation' => [ - 'order' => [ - 'index' => 0, // _pages/index.md (or .blade.php) - 'posts' => 10, // _pages/posts.md (or .blade.php) - 'docs/index' => 100, // _docs/index.md - ] -] -``` - -## Reordering items with front matter - -You can also set the priority of a page directly in the front matter. This will override any dynamically inferred or -config defined priority. While this is useful for one-offs, it can make it harder to reorder items later on. -It's up to you which method you prefer to use. This setting can be used both for the navigation menu and the sidebar. - -```markdown ---- -navigation: - priority: 10 ---- -``` - ->info Tip: If you are using automatic subdirectory dropdowns, you can also set their priority in the config. Just use the directory name instead of the page identifier. - -### Adding Custom Navigation Menu Links - -You can easily add custom navigation menu links similar how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array. - -When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the -destination and label, both required. Third argument is the priority, which is optional, and defaults to 500. - -```php -// filepath config/hyde.php -use Hyde\Framework\Features\Navigation\NavItem; - -'navigation' => [ - 'custom' => [ - NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200), - ] -] -``` - -Simplified, this will then be rendered as follows: - -```html -GitHub -``` - -### Excluding Items (Blacklist) - -Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu. -To remove items from being automatically added, simply add the page's route key to the blacklist. -As you can see, the `404` page has already been filled in for you. - -```php -'navigation' => [ - 'exclude' => [ - '404' - ] -] -``` - -You can also specify that a page should be excluded by setting the page front matter. - -```markdown ---- -navigation: - hidden: true ---- -``` - -### Changing the menu item labels - -Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. -You can override the label using the `navigation.label` front matter property. - -From the Hyde config you can also override the label of navigation links using the by mapping the route key -to the desired title. Note that the front matter property will take precedence over the config property. - -```php -// filepath config/hyde.php -'navigation' => [ - 'labels' => [ - 'index' => 'Start', - 'docs/index' => 'Documentation', - ] -] -``` From 1dfbb072b7359ba74fdacb7ea32c8608832eab2d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sun, 12 Nov 2023 15:53:42 +0100 Subject: [PATCH 6/6] Update navigation documentation --- docs/digging-deeper/customization.md | 126 ++++++++++++++------------- 1 file changed, 66 insertions(+), 60 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index b0b2e74c68b..538f92301e1 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -202,57 +202,65 @@ If you don't want to have a footer on your site, you can set the `'footer'` conf ### Navigation Menu & Sidebar -One of my favourite features with Hyde is its automatic navigation menu and documentation sidebar generator. +A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation. +Hyde is designed to automatically configure these menus for you based on the content you have in your project. -#### How it works: +Still, you will likely want to customize some parts of these menus, and thankfully, Hyde makes it easy to do so. -The sidebar works by creating a list of all the documentation pages. +#### Customizing the navigation menu -The navigation menu is a bit more sophisticated, it adds all the top-level Blade and Markdown pages. -It also adds an automatic link to the docs if there is an `index.md` in the `_docs` directory. +- 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. -#### Reordering Sidebar Items +Learn more in the [Navigation Menu](navigation-menus) documentation. -Sadly, Hyde is not intelligent enough to determine what order items should be in (blame Dr Jekyll for this), -so you will probably want to set a custom order. +#### Customizing the documentation sidebar -Reordering items in the documentation sidebar is as easy as can be. In the `docs` config, there is an array just for this. -If a page identifier is found here it will get priority calculated according to its position in the list, -plus an offset of 500. This offset allows you to pages earlier in the list using front matter. +- 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. -If a page does not exist in the list they get priority 999, which puts them last. -You can also use front matter to set a priority for a page. -The front matter value will always take precedence. +Learn more in the [Documentation Pages](documentation-pages) documentation. -Let's see an example: +>info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. + +### Primer on priorities + +All navigation menu items have an internal priority value that determines its order in the navigation. +Lower values means that the item will be higher up in the menu. The default for pages is `999` which puts them last. +However, some pages are autoconfigured to have a lower priority, for example, the `index` page defaults to a priority of `0`, + +#### Basic syntax for changing the priorities + +The cleanest way is to use the list-style syntax where each item will get the priority calculated according to its position in the list, plus an offset of `500`. +The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. ```php -// filepath: config/docs.php -// These are the default values in the config. It puts the readme.md first in order. -'sidebar_order' => [ - 'readme', // This is the first entry, so it gets the priority 500 + 0 - 'installation', // This gets priority 500 + 1 - 'getting-started', // And this gets priority 500 + 2 - // Any other pages not listed will get priority 999 +[ + 'readme', // Gets priority 500 + 'installation', // Gets priority 501 + 'getting-started', // Gets priority 502 ] ``` -#### Reordering Navigation Menu Items +#### Explicit syntax for changing the priorities -As Hyde makes an effort to organize the menu items in a sensible way, your project comes preconfigured to put what it thinks are your most -important pages first. This may of course not always match what you want, so thankfully it's easy to reorder the menu items! +You can also specify explicit priorities by adding a value to the array key: + +```php +[ + 'readme' => 10, // Gets priority 10 + 'installation' => 15, // Gets priority 15 + 'getting-started' => 20, // Gets priority 20 +] +``` -Simply update the `navigation.order` array in the Hyde config! The priorities set will determine the order of the menu items. -Lower values are higher in the menu, and any pages not listed will get priority 999, which puts them last. +You can also combine these options if you want: ```php -// filepath config/hyde.php -'navigation' => [ - 'order' => [ - 'index' => 0, // _pages/index.md (or .blade.php) - 'posts' => 10, // _pages/posts.md (or .blade.php) - 'docs/index' => 100, // _docs/index.md - ] +[ + 'readme' => 10, // Gets priority 10 + 'installation', // Gets priority 500 + 'getting-started', // Gets priority 501 ] ``` @@ -263,36 +271,28 @@ It's up to you which method you prefer to use. This setting can be used both for ```markdown --- navigation: - priority: 10 + priority: 25 --- ``` ->info Tip: If you are using automatic subdirectory dropdowns, you can also set their priority in the config. Just use the directory name instead of the page identifier. - -#### Adding Custom Navigation Menu Links +#### Changing the menu item labels -You can easily add custom navigation menu links similar how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array. +Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. +You can override the label using the `navigation.label` front matter property. -When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the -destination and label, both required. Third argument is the priority, which is optional, and defaults to 500. +From the Hyde config you can also override the label of navigation links using the by mapping the route key +to the desired title. Note that the front matter property will take precedence over the config property. ```php // filepath config/hyde.php -use Hyde\Framework\Features\Navigation\NavItem; - 'navigation' => [ - 'custom' => [ - NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200), + 'labels' => [ + 'index' => 'Start', + 'docs/index' => 'Documentation', ] ] ``` -Simplified, this will then be rendered as follows: - -```html -GitHub -``` - #### Excluding Items (Blacklist) Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu. @@ -300,6 +300,7 @@ To remove items from being automatically added, simply add the page's route key As you can see, the `404` page has already been filled in for you. ```php +// filepath config/hyde.php 'navigation' => [ 'exclude' => [ '404' @@ -314,26 +315,31 @@ You can also specify that a page should be excluded by setting the page front ma navigation: hidden: true --- -``` -#### Changing the menu item labels -Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. -You can override the label using the `navigation.label` front matter property. +#### Adding Custom Navigation Menu Links -From the Hyde config you can also override the label of navigation links using the by mapping the route key -to the desired title. Note that the front matter property will take precedence over the config property. +You can easily add custom navigation menu links similar how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array. + +When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the +destination and label, both required. Third argument is the priority, which is optional, and defaults to 500. ```php // filepath config/hyde.php +use Hyde\Framework\Features\Navigation\NavItem; + 'navigation' => [ - 'labels' => [ - 'index' => 'Start', - 'docs/index' => 'Documentation', + 'custom' => [ + NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200), ] ] ``` +Simplified, this will then be rendered as follows: + +```html +GitHub +``` ## Blade Views