From 34698113bdb241a34514a9822d98a0ea18b191af Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 21:48:22 +0100 Subject: [PATCH 01/64] Add missing closing code block tag --- docs/digging-deeper/customization.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index f797b6e9be3..705cab9933a 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -315,6 +315,7 @@ You can also specify that a page should be excluded by setting the page front ma navigation: hidden: true --- +``` #### Adding Custom Navigation Menu Links From bfe999eda6240e952eb5d9e41db06fef3c2adfd4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 21:51:02 +0100 Subject: [PATCH 02/64] Create navigation.md --- docs/digging-deeper/navigation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/digging-deeper/navigation.md diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md new file mode 100644 index 00000000000..59368f27977 --- /dev/null +++ b/docs/digging-deeper/navigation.md @@ -0,0 +1 @@ +# Navigation From 2f7cab8a3d0c845ada95bbb8c4a7a925917befe5 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 21:51:13 +0100 Subject: [PATCH 03/64] Add front matter --- docs/digging-deeper/navigation.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 59368f27977..879f32b5c66 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -1 +1,7 @@ +--- +navigation: + label: "Navigation" + priority: 26 +--- + # Navigation From 08297506855aa842c8923f176863793331958060 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 21:52:11 +0100 Subject: [PATCH 04/64] Offset navigation priorities --- docs/digging-deeper/advanced-markdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/advanced-markdown.md b/docs/digging-deeper/advanced-markdown.md index 826b6e14920..149b7f53b06 100644 --- a/docs/digging-deeper/advanced-markdown.md +++ b/docs/digging-deeper/advanced-markdown.md @@ -1,7 +1,7 @@ --- navigation: label: "Advanced Markdown" - priority: 26 + priority: 27 --- # Advanced Markdown From 6716b5c636de7e875e268fabf7eec29f598c9f3b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 22:10:42 +0100 Subject: [PATCH 05/64] Update title --- docs/digging-deeper/navigation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 879f32b5c66..b5818755acb 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -1,7 +1,7 @@ --- navigation: - label: "Navigation" + label: "Navigation Menus" priority: 26 --- -# Navigation +# Navigation Menus From 7454bd6005f3f4593d835e362e89607623add879 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 22:16:37 +0100 Subject: [PATCH 06/64] Add introduction section --- docs/digging-deeper/navigation.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index b5818755acb..cef11b746db 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -5,3 +5,19 @@ navigation: --- # Navigation Menus + +## 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. + +There are two types of navigation menus in Hyde: + +- **Primary Navigation Menu**: This is the main navigation menu that appears on most pages your site. +- **Documentation Sidebar**: This is a sidebar that appears on documentation pages and contains links to other documentation pages. + +HydePHP automatically generates all of these menus for you based on the content in your project, +and does its best to automatically configure them in the way that you most likely want them to be. + +Of course, this won't always be perfect, so thankfully Hyde makes it a breeze to customize these menus to your liking. +Keep on reading to learn how! To learn even more about the sidebars, visit the [Documentation Pages](documentation-pages) documentation. From aa6717629b024af524e2e26f83bb8fc1a0977f42 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 22:16:43 +0100 Subject: [PATCH 07/64] Fix broken link --- 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 705cab9933a..c2765f93caa 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -212,7 +212,7 @@ Still, you will likely want to customize some parts of these menus, and thankful - 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. -Learn more in the [Navigation Menu](navigation-menus) documentation. +Learn more in the [Navigation Menu](navigation) documentation. #### Customizing the documentation sidebar From c38ca91914d25c404a348d0b988fe7abcc4fa816 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 22:29:46 +0100 Subject: [PATCH 08/64] Add primer on the internals --- docs/digging-deeper/navigation.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index cef11b746db..a75aec1be6f 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -21,3 +21,12 @@ and does its best to automatically configure them in the way that you most likel Of course, this won't always be perfect, so thankfully Hyde makes it a breeze to customize these menus to your liking. Keep on reading to learn how! To learn even more about the sidebars, visit the [Documentation Pages](documentation-pages) documentation. + +## Quick primer on the internals + +It may be beneficial to understand the internal workings of the navigation menus in order to take full advantage of the options. + +In short, both navigation menu types extend the same class (meaning they share the same base code), this means that the way +they are configured are very similar, making the documentation here applicable to both types of menus. + +See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! From 5ceef9307bdfee6c7cd1bb5325490d3ea530fc4f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 22:29:53 +0100 Subject: [PATCH 09/64] Add internals deep dive --- docs/digging-deeper/navigation.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index a75aec1be6f..324ad1c7b42 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -30,3 +30,30 @@ In short, both navigation menu types extend the same class (meaning they share t they are configured are very similar, making the documentation here applicable to both types of menus. See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! + +## Digging deeper into the internals + +While not required to know, you may find it interesting to learn more about how the navigation is handled internally. +The best way to learn about this is to look at the source code, so here is a high level overview with details on where to look in the source code. + +The main navigation menu is the `NavigationMenu` class, and the documentation sidebar is the `DocumentationSidebar` class. +Both extend the same `BaseNavigationMenu` class: + +```php +use Hyde\Framework\Features\Navigation\NavigationMenu; +use Hyde\Framework\Features\Navigation\DocumentationSidebar; +use \Hyde\Framework\Features\Navigation\BaseNavigationMenu; +``` + +Within the `BaseNavigationMenu` class, you will find the main logic for how the menus are generated, +while the child implementations contain the extra logic tailored for their specific use cases. + +All the navigation menus store the menu items in their `$items` array containing instances of the `NavItem` class. + +The `NavItem` class is a simple class that contains the label and URL of the menu item, and is used to represent each item in the menu. +Dropdowns are represented by `DropdownNavItem` instances, which extend the `NavItem` class and contain an array of additional `NavItem` instances. + +```php +use Hyde\Framework\Features\Navigation\NavItem; +use Hyde\Framework\Features\Navigation\DropdownNavItem; +``` From aa4d3bb3dae11aa2f1132d02a331abfa8bf35a13 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 22:30:02 +0100 Subject: [PATCH 10/64] Add high level overview of option types --- docs/digging-deeper/navigation.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 324ad1c7b42..dbcae1ce836 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -31,6 +31,15 @@ they are configured are very similar, making the documentation here applicable t See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! +## What to customize? + +Here is a quick overview of what you might want to customize in your navigation menus: + +- Navigation menu item labels - the text that appears in the menu links +- Navigation menu item priority - control the order in which the links appear +- Navigation menu item visibility - control if pages may show up in the menus +- Navigation menu item grouping - group pages together in dropdowns + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From c0f748f1124e69a8e2115eaf7623ade037347cf0 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 8 Feb 2024 22:31:25 +0100 Subject: [PATCH 11/64] Improve grammar and wording --- docs/digging-deeper/navigation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index dbcae1ce836..122c23d365f 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -13,10 +13,10 @@ Hyde is designed to automatically configure these menus for you based on the con There are two types of navigation menus in Hyde: -- **Primary Navigation Menu**: This is the main navigation menu that appears on most pages your site. +- **Primary Navigation Menu**: This is the main navigation menu that appears on most pages of your site. - **Documentation Sidebar**: This is a sidebar that appears on documentation pages and contains links to other documentation pages. -HydePHP automatically generates all of these menus for you based on the content in your project, +HydePHP automatically generates all of these menus for you based on the content of your project, and does its best to automatically configure them in the way that you most likely want them to be. Of course, this won't always be perfect, so thankfully Hyde makes it a breeze to customize these menus to your liking. @@ -24,7 +24,7 @@ Keep on reading to learn how! To learn even more about the sidebars, visit the [ ## Quick primer on the internals -It may be beneficial to understand the internal workings of the navigation menus in order to take full advantage of the options. +It may be beneficial to understand the internal workings of the navigation menus to take full advantage of the options. In short, both navigation menu types extend the same class (meaning they share the same base code), this means that the way they are configured are very similar, making the documentation here applicable to both types of menus. @@ -43,7 +43,7 @@ Here is a quick overview of what you might want to customize in your navigation ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. -The best way to learn about this is to look at the source code, so here is a high level overview with details on where to look in the source code. +The best way to learn about this is to look at the source code, so here is a high-level overview with details on where to look in the source code. The main navigation menu is the `NavigationMenu` class, and the documentation sidebar is the `DocumentationSidebar` class. Both extend the same `BaseNavigationMenu` class: @@ -59,7 +59,7 @@ while the child implementations contain the extra logic tailored for their speci All the navigation menus store the menu items in their `$items` array containing instances of the `NavItem` class. -The `NavItem` class is a simple class that contains the label and URL of the menu item, and is used to represent each item in the menu. +The `NavItem` class is a simple class that contains the label and URL of the menu item and is used to represent each item in the menu. Dropdowns are represented by `DropdownNavItem` instances, which extend the `NavItem` class and contain an array of additional `NavItem` instances. ```php From 3aecc7d1ba4bd349d2f9251253a09b3738b971e9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 10:46:48 +0100 Subject: [PATCH 12/64] Add additional background section --- docs/digging-deeper/navigation.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 122c23d365f..fe136d1e160 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -40,6 +40,16 @@ Here is a quick overview of what you might want to customize in your navigation - Navigation menu item visibility - control if pages may show up in the menus - Navigation menu item grouping - group pages together in dropdowns +## How and where to customize? + +Hyde provides a few different ways to customize the navigation menus, depending on what you prefer. + +To customize how a page is represented in navigation, you can either set the `navigation` front matter data in the page's markdown file, +or configure it in the config file. Main navigation items are in the `hyde` config file, while documentation sidebar items are in the `docs` config file. +General options for the entire navigation menus are also available in the `hyde` and `docs` config files. + +Now that you know the basics, let's dive into the details of how to customize the navigation menus! + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From c3143a9bed3c413f6e8bdc433350e57c21bbb55a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 10:51:46 +0100 Subject: [PATCH 13/64] Add overview section --- docs/digging-deeper/navigation.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index fe136d1e160..35a1b0429f0 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -50,6 +50,21 @@ General options for the entire navigation menus are also available in the `hyde` Now that you know the basics, let's dive into the details of how to customize the navigation menus! +## Front matter configuration + +The front matter options allow you to customize the navigation menus on a per-page basis. The following options are available: + +Here is a quick reference of the available options. The full documentation of each option is below. +You don't need to specify all the keys, only the ones you want to customize. + +```yaml +navigation: + 'label' => 'string', # The text to display + 'priority' => 'int', # Order is also supported + 'hidden' => 'bool', # Visible is also supported (but obviously invert the value) + 'group' => 'string', # Category is also supported +``` + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From 9d304d3febc28d2b3a12ec23fc88af4daf803b69 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 11:06:04 +0100 Subject: [PATCH 14/64] Formatting --- docs/digging-deeper/navigation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 35a1b0429f0..638cd64ded3 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -52,8 +52,7 @@ Now that you know the basics, let's dive into the details of how to customize th ## Front matter configuration -The front matter options allow you to customize the navigation menus on a per-page basis. The following options are available: - +The front matter options allow you to customize the navigation menus on a per-page basis. Here is a quick reference of the available options. The full documentation of each option is below. You don't need to specify all the keys, only the ones you want to customize. From 15ced66433b2606b4f964413ead8ab57d437d681 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 11:06:45 +0100 Subject: [PATCH 15/64] Formatting --- docs/digging-deeper/navigation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 638cd64ded3..533abb7c1cb 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -58,10 +58,10 @@ You don't need to specify all the keys, only the ones you want to customize. ```yaml navigation: - 'label' => 'string', # The text to display - 'priority' => 'int', # Order is also supported - 'hidden' => 'bool', # Visible is also supported (but obviously invert the value) - 'group' => 'string', # Category is also supported + label: string # The text to display + priority: int # Order is also supported + hidden: bool # Visible is also supported (but obviously invert the value) + group: string # Category is also supported ``` ## Digging deeper into the internals From f53ada05426b40fc7212175c4818bfd77eac08d9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 11:08:56 +0100 Subject: [PATCH 16/64] Document all the front matter options --- docs/digging-deeper/navigation.md | 39 +++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 533abb7c1cb..f14048a5525 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -64,6 +64,45 @@ navigation: group: string # Category is also supported ``` +### `label` + +The `label` option allows you to customize the text that appears in the navigation menu for the page. + +```yaml +navigation: + label: "My Custom Label" +``` + +### `priority` + +The `priority` option allows you to control the order in which the page appears in the navigation menu. You can also use `order` instead of `priority`. + +```yaml +navigation: + priority: 10 +``` + +### `hidden` + +The `hidden` option allows you to control if the page appears in the navigation menu. You can also use `visible` instead of `hidden`, but obviously invert the value. + +```yaml +navigation: + hidden: true +``` + +### `group` + +The `group` option has a slightly different meaning depending on the type of navigation menu. +For the primary navigation menu, it allows you to group pages together in dropdowns. +For the sidebar, it allows you to group pages together in the sidebar under a common heading. +You can also use `category` instead of `group`. + +```yaml +navigation: + group: "My Group" +``` + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From dc81e5f529d6ffee63b97ded6046396dd06fde7d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 12:46:17 +0100 Subject: [PATCH 17/64] Add configuration documentation redirect --- docs/redirects/configuration.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/redirects/configuration.md diff --git a/docs/redirects/configuration.md b/docs/redirects/configuration.md new file mode 100644 index 00000000000..10f2c14af44 --- /dev/null +++ b/docs/redirects/configuration.md @@ -0,0 +1,10 @@ +--- +navigation: + hidden: true +--- + + + +Redirecting you to [customization](customization) + + From 48fed8d7413e9d63f163c00ffaf2abb55818bc15 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:03:52 +0100 Subject: [PATCH 18/64] Begin section --- docs/digging-deeper/navigation.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index f14048a5525..a56e420a94c 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -103,6 +103,17 @@ navigation: group: "My Group" ``` +## Config file configuration + +Next up, let's look at how to customize the navigation menus using the config files. + +- 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. +- When customizing the sidebar, can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page. + + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From 1fa5c7d4add6b7da92914ad58bd87da8d5c54acb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:13:55 +0100 Subject: [PATCH 19/64] Increase subheading levels --- docs/digging-deeper/navigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index a56e420a94c..046bf950fe2 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -22,7 +22,7 @@ and does its best to automatically configure them in the way that you most likel Of course, this won't always be perfect, so thankfully Hyde makes it a breeze to customize these menus to your liking. Keep on reading to learn how! To learn even more about the sidebars, visit the [Documentation Pages](documentation-pages) documentation. -## Quick primer on the internals +### Quick primer on the internals It may be beneficial to understand the internal workings of the navigation menus to take full advantage of the options. @@ -31,7 +31,7 @@ they are configured are very similar, making the documentation here applicable t See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! -## What to customize? +### What to customize? Here is a quick overview of what you might want to customize in your navigation menus: @@ -40,7 +40,7 @@ Here is a quick overview of what you might want to customize in your navigation - Navigation menu item visibility - control if pages may show up in the menus - Navigation menu item grouping - group pages together in dropdowns -## How and where to customize? +### How and where to customize? Hyde provides a few different ways to customize the navigation menus, depending on what you prefer. From b74be43b8c81e18c02b30ec730762518353895bd Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:28:56 +0100 Subject: [PATCH 20/64] Move priorities primer to new page --- docs/digging-deeper/customization.md | 6 ------ docs/digging-deeper/navigation.md | 6 ++++++ 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index c2765f93caa..616a2e5ffbe 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -223,12 +223,6 @@ Learn more in the [Documentation Pages](documentation-pages) documentation. >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`. diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 046bf950fe2..ce1b3f0eb48 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -31,6 +31,12 @@ they are configured are very similar, making the documentation here applicable t See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! +### 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`, + ### What to customize? Here is a quick overview of what you might want to customize in your navigation menus: From d9c285e01130141f1c7aee9a85042b7de6dc144e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:36:21 +0100 Subject: [PATCH 21/64] Move context to new page --- docs/digging-deeper/customization.md | 4 +--- docs/digging-deeper/navigation.md | 4 ++++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 616a2e5ffbe..84ae1518e18 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -258,9 +258,7 @@ You can also combine these options if you want: ] ``` -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. +You can also set the priority of a page directly in the front matter. ```markdown --- diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index ce1b3f0eb48..99f34e4b211 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -50,6 +50,10 @@ Here is a quick overview of what you might want to customize in your navigation Hyde provides a few different ways to customize the navigation menus, depending on what you prefer. +Specifying the data in the front matter 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 as you can't see the whole picture at once. +It's up to you which method you prefer to use. + To customize how a page is represented in navigation, you can either set the `navigation` front matter data in the page's markdown file, or configure it in the config file. Main navigation items are in the `hyde` config file, while documentation sidebar items are in the `docs` config file. General options for the entire navigation menus are also available in the `hyde` and `docs` config files. From fc620d2269b1df0b484088b1f755da934a63e7d8 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:36:42 +0100 Subject: [PATCH 22/64] Add new heading --- docs/digging-deeper/navigation.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 99f34e4b211..d218f2cd143 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -123,6 +123,10 @@ Next up, let's look at how to customize the navigation menus using the config fi - 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. +### `navigation.order` and `sidebar_order` + +The `navigation.order` and `sidebar_order` settings allow you to customize the order of the pages in the navigation menus. + ## Digging deeper into the internals From 92f40f4c01af8587853e0346d5a3efa54f5b3338 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:36:52 +0100 Subject: [PATCH 23/64] Add new basic syntax documentation --- docs/digging-deeper/navigation.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index d218f2cd143..0f5345562d4 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -127,6 +127,33 @@ Next up, let's look at how to customize the navigation menus using the config fi 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 + +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/hyde.php + +'navigation' => [ + 'order' => [ + 'home', // Gets priority 500 + 'about', // Gets priority 501 + 'contact', // Gets priority 502 + ] +] +``` + +```php +// filepath: config/docs.php + +'sidebar_order' => [ + 'readme', // Gets priority 500 + 'installation', // Gets priority 501 + 'getting-started', // Gets priority 502 +] +``` + ## Digging deeper into the internals From 96f5bb25754f3db3e566ae4f4123939ed72ed04b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:40:58 +0100 Subject: [PATCH 24/64] Document explicit syntax --- docs/digging-deeper/navigation.md | 36 +++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 0f5345562d4..063b0c6a256 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -154,6 +154,42 @@ The offset is added to make it easier to place pages earlier in the list using f ] ``` +#### Explicit syntax for changing the priorities + +You can also specify explicit priorities by adding a value to the array key: + +```php +// filepath: config/hyde.php + +'navigation' => [ + 'order' => [ + 'home' => 10, // Gets priority 10 + 'about' => 15, // Gets priority 15 + 'contact' => 20, // Gets priority 20 + ] +] +``` + +```php +// filepath: config/docs.php + +'sidebar_order' => [ + 'readme' => 10, // Gets priority 10 + 'installation' => 15, // Gets priority 15 + 'getting-started' => 20, // Gets priority 20 +] +``` + +You can of course also combine these methods if you want: + +```php +// filepath: Applicable to both +[ + 'readme' => 10, // Gets priority 10 + 'installation', // Gets priority 500 + 'getting-started', // Gets priority 501 +] +``` ## Digging deeper into the internals From 10ddfe0c5c88c944d74638fe16c43308d04c8387 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:43:08 +0100 Subject: [PATCH 25/64] Remove overlapping documentation --- docs/digging-deeper/customization.md | 44 ---------------------------- 1 file changed, 44 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 84ae1518e18..d29c21084f6 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -223,50 +223,6 @@ Learn more in the [Documentation Pages](documentation-pages) documentation. >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. -#### 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 -[ - 'readme', // Gets priority 500 - 'installation', // Gets priority 501 - 'getting-started', // Gets priority 502 -] -``` - -#### Explicit syntax for changing the priorities - -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 -] -``` - -You can also combine these options if you want: - -```php -[ - 'readme' => 10, // Gets priority 10 - 'installation', // Gets priority 500 - 'getting-started', // Gets priority 501 -] -``` - -You can also set the priority of a page directly in the front matter. - -```markdown ---- -navigation: - priority: 25 ---- -``` - #### 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. From e0d0b6f6caedf66a0c52d547121998efe6b16c90 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:43:13 +0100 Subject: [PATCH 26/64] Update link --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index f3ab7ce538a..d0580aeb31b 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -105,7 +105,7 @@ of these items. You can do this in two ways, either in the config or with front Hyde automatically generates a table of contents for the page and adds it to the sidebar. The behaviour of this can be changed in the configuration file. -See [the customization page](customization#navigation-menu--sidebar) for more details. +See the [navigation menu documentation](navigation) for more details. ### Sidebar ordering From fe27b8fbe31b42b2c1821870b69c89e812fb0654 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:44:17 +0100 Subject: [PATCH 27/64] Clarify section --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index d0580aeb31b..f0fef6f5137 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -137,7 +137,7 @@ Sidebar grouping allows you to group items in the sidebar into categories. This The Hyde docs for instance use this. The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set -in the front matter. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. +in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. Any pages without the group front matter will get put in the "Other" group. ### Sidebar footer customization From 3950586ceded07e4bfa9850a44696ac2b42b4ab1 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:45:08 +0100 Subject: [PATCH 28/64] Note overrides --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index f0fef6f5137..e75a5b8a67e 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -169,7 +169,7 @@ You can also automatically group your documentation pages by placing source file For example, putting a Markdown file in `_docs/getting-started/`, is equivalent to adding the same front matter seen above. ->info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. +>info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. ### Hiding items From fc6a0fc1f9f25525cf5371bbf7c1e921d31898a2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:57:49 +0100 Subject: [PATCH 29/64] Move label config documentation --- docs/digging-deeper/customization.md | 18 ------------------ docs/digging-deeper/navigation.md | 17 +++++++++++++++++ 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index d29c21084f6..1fde8c50778 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -223,24 +223,6 @@ Learn more in the [Documentation Pages](documentation-pages) documentation. >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. -#### 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', - ] -] -``` - #### 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. diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 063b0c6a256..24d39be5a59 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -191,6 +191,23 @@ You can of course also combine these methods if you want: ] ``` +#### 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. + +From the Hyde config you can override the label of navigation links using the by mapping the route key to the desired title. +This is not yet supported for the sidebar, but will be in the future. + +```php +// filepath config/hyde.php +'navigation' => [ + 'labels' => [ + 'index' => 'Start', + 'docs/index' => 'Documentation', + ] +] +``` + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From 4f484cde825728b0a371b6977ae3ceb8caeb2201 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:58:34 +0100 Subject: [PATCH 30/64] Cleaner heading --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 24d39be5a59..99bf0c890f3 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -123,7 +123,7 @@ Next up, let's look at how to customize the navigation menus using the config fi - 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. -### `navigation.order` and `sidebar_order` +### Changing the priorities The `navigation.order` and `sidebar_order` settings allow you to customize the order of the pages in the navigation menus. From 87d452ea3b0e9919ef08097a123853d858327acc Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 18:59:24 +0100 Subject: [PATCH 31/64] Move documentation --- docs/digging-deeper/customization.md | 24 ------------------------ docs/digging-deeper/navigation.md | 14 ++++++++++++++ 2 files changed, 14 insertions(+), 24 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 1fde8c50778..29ac62f6a86 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -223,30 +223,6 @@ Learn more in the [Documentation Pages](documentation-pages) documentation. >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. -#### 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 -// filepath config/hyde.php -'navigation' => [ - 'exclude' => [ - '404' - ] -] -``` - -You can also specify that a page should be excluded by setting the page front matter. - -```markdown ---- -navigation: - hidden: true ---- -``` - #### 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. diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 99bf0c890f3..f80cc5fc779 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -208,6 +208,20 @@ This is not yet supported for the sidebar, but will be in the future. ] ``` +#### 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. + +```php +// filepath config/hyde.php +'navigation' => [ + 'exclude' => [ + '404' + ] +] +``` + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From 89f491f84a6a932e166ce5f3ef986b76200550d3 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:05:51 +0100 Subject: [PATCH 32/64] Move documentation --- docs/digging-deeper/customization.md | 24 ------------------------ docs/digging-deeper/navigation.md | 24 ++++++++++++++++++++++++ 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 29ac62f6a86..36915affca4 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -223,30 +223,6 @@ Learn more in the [Documentation Pages](documentation-pages) documentation. >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. -#### 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 -``` - #### Automatic navigation menu dropdowns HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories. diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index f80cc5fc779..d69819e1dd9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -222,6 +222,30 @@ To remove items from being automatically added, simply add the page's route key ] ``` +#### 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 +``` + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From c43b1261902a5f6ba91de8e0c891d132797ed377 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:09:54 +0100 Subject: [PATCH 33/64] Lower heading levels --- docs/digging-deeper/navigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index d69819e1dd9..56dff3757d5 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -191,7 +191,7 @@ You can of course also combine these methods if you want: ] ``` -#### Changing the menu item labels +### 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. @@ -208,7 +208,7 @@ This is not yet supported for the sidebar, but will be in the future. ] ``` -#### Excluding Items (Blacklist) +### 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. @@ -222,7 +222,7 @@ To remove items from being automatically added, simply add the page's route key ] ``` -#### Adding Custom Navigation Menu Links +### 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. From 901545b6ae62e897dbee27f17029c34a46654e15 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:11:51 +0100 Subject: [PATCH 34/64] Document subdirectory handling --- docs/digging-deeper/navigation.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 56dff3757d5..ad9297c935b 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -246,6 +246,21 @@ Simplified, this will then be rendered as follows: GitHub ``` +### Configure subdirectory handling + +Within the Hyde config you can configure how subdirectories should be displayed in the menu. + +``` +// filepath config/hyde.php +'navigation' => [ + 'subdirectories' => 'dropdown' +] +``` + +Dropdown means that pages in subdirectories will be displayed in a dropdown menu, +while `flat` means that pages in subdirectories will be displayed as individual items in the menu. +Hidden means that pages in subdirectories will not be displayed in the menu at all. + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From ff616bae16b479c3f298367c21004cc8042b7d2e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:14:12 +0100 Subject: [PATCH 35/64] Move subdirectory docs --- docs/digging-deeper/customization.md | 23 ----------------------- docs/digging-deeper/navigation.md | 24 ++++++++++++++++++++++++ 2 files changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 36915affca4..c66bbcd9e78 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -223,29 +223,6 @@ Learn more in the [Documentation Pages](documentation-pages) documentation. >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. -#### Automatic navigation menu dropdowns - -HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories. - -For pages that can be in the main site menu, ths feature needs to be enabled in the `hyde.php` config file. - -```php -// filepath config/hyde.php - -'navigation' => [ - 'subdirectories' => 'dropdown', -], -``` - -Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". - -#### Automatic documentation sidebar grouping - -This feature works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups. -This feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped. - -For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". - ## Additional Advanced Options The following configuration options in the `confg/hyde.php` file are intended for advanced users and diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index ad9297c935b..dccd324bee7 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -261,6 +261,30 @@ Dropdown means that pages in subdirectories will be displayed in a dropdown menu while `flat` means that pages in subdirectories will be displayed as individual items in the menu. Hidden means that pages in subdirectories will not be displayed in the menu at all. +### Automatic navigation menu dropdowns + +HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories. + +For pages that can be in the main site menu, ths feature needs to be enabled in the `hyde.php` config file. + +```php +// filepath config/hyde.php + +'navigation' => [ + 'subdirectories' => 'dropdown', +], +``` + +Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". + +### Automatic documentation sidebar grouping + +This feature works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups. +This feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped. + +For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". + + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From e795f65a6297b357fe63380a6859df504eb503c2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:15:20 +0100 Subject: [PATCH 36/64] Adjust headings --- docs/digging-deeper/navigation.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index dccd324bee7..dead688c020 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -261,10 +261,12 @@ Dropdown means that pages in subdirectories will be displayed in a dropdown menu while `flat` means that pages in subdirectories will be displayed as individual items in the menu. Hidden means that pages in subdirectories will not be displayed in the menu at all. -### Automatic navigation menu dropdowns +### Automatic menu groups HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories. +#### Automatic navigation menu dropdowns + For pages that can be in the main site menu, ths feature needs to be enabled in the `hyde.php` config file. ```php @@ -277,7 +279,7 @@ For pages that can be in the main site menu, ths feature needs to be enabled in Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". -### Automatic documentation sidebar grouping +#### Automatic documentation sidebar grouping This feature works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups. This feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped. From 9fdae5e9a8305e9bc6f533621dec0ac0c7d32ccb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:17:03 +0100 Subject: [PATCH 37/64] Formatting --- docs/digging-deeper/navigation.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index dead688c020..966904f0f74 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -56,13 +56,14 @@ It's up to you which method you prefer to use. To customize how a page is represented in navigation, you can either set the `navigation` front matter data in the page's markdown file, or configure it in the config file. Main navigation items are in the `hyde` config file, while documentation sidebar items are in the `docs` config file. -General options for the entire navigation menus are also available in the `hyde` and `docs` config files. +General options for the entire navigation menus are also available in the `hyde` and `docs` config files. Now that you know the basics, let's dive into the details of how to customize the navigation menus! + ## Front matter configuration -The front matter options allow you to customize the navigation menus on a per-page basis. +The front matter options allow you to customize the navigation menus on a per-page basis. Here is a quick reference of the available options. The full documentation of each option is below. You don't need to specify all the keys, only the ones you want to customize. @@ -113,6 +114,7 @@ navigation: group: "My Group" ``` + ## Config file configuration Next up, let's look at how to customize the navigation menus using the config files. @@ -195,7 +197,7 @@ You can of course also combine these methods if you want: Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. -From the Hyde config you can override the label of navigation links using the by mapping the route key to the desired title. +From the Hyde config you can override the label of navigation links using the by mapping the route key to the desired title. This is not yet supported for the sidebar, but will be in the future. ```php @@ -257,8 +259,8 @@ Within the Hyde config you can configure how subdirectories should be displayed ] ``` -Dropdown means that pages in subdirectories will be displayed in a dropdown menu, -while `flat` means that pages in subdirectories will be displayed as individual items in the menu. +Dropdown means that pages in subdirectories will be displayed in a dropdown menu, +while `flat` means that pages in subdirectories will be displayed as individual items in the menu. Hidden means that pages in subdirectories will not be displayed in the menu at all. ### Automatic menu groups @@ -298,7 +300,7 @@ Both extend the same `BaseNavigationMenu` class: ```php use Hyde\Framework\Features\Navigation\NavigationMenu; use Hyde\Framework\Features\Navigation\DocumentationSidebar; -use \Hyde\Framework\Features\Navigation\BaseNavigationMenu; +use Hyde\Framework\Features\Navigation\BaseNavigationMenu; ``` Within the `BaseNavigationMenu` class, you will find the main logic for how the menus are generated, From 59dc515478a933fbc31d880b92f7298f642130cd Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:23:31 +0100 Subject: [PATCH 38/64] Revert "Update link" This reverts commit e0d0b6f6caedf66a0c52d547121998efe6b16c90. --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index e75a5b8a67e..4ef4602fbe1 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -105,7 +105,7 @@ of these items. You can do this in two ways, either in the config or with front Hyde automatically generates a table of contents for the page and adds it to the sidebar. The behaviour of this can be changed in the configuration file. -See the [navigation menu documentation](navigation) for more details. +See [the customization page](customization#navigation-menu--sidebar) for more details. ### Sidebar ordering From adb7289baa5d4b3ccb5ca811bbb38a5a9a2b8e20 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:25:43 +0100 Subject: [PATCH 39/64] Merge duplicated section --- docs/creating-content/documentation-pages.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 4ef4602fbe1..740db78b57a 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -100,13 +100,6 @@ and where the data is from as well as where it can be overridden. The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings. -### Table of contents - -Hyde automatically generates a table of contents for the page and adds it to the sidebar. - -The behaviour of this can be changed in the configuration file. -See [the customization page](customization#navigation-menu--sidebar) for more details. - ### Sidebar ordering The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. @@ -252,6 +245,8 @@ Please note that this option is not added to the config file by default, as it's ### Table of contents settings +Hyde automatically generates a table of contents for the page and adds it to the sidebar. + In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents. You can also disable the feature completely. From afa8fc48595092d846c53ae2aeff2706827e6635 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:26:45 +0100 Subject: [PATCH 40/64] New introduction section --- docs/creating-content/documentation-pages.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 740db78b57a..2dfe2ab7cde 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -100,6 +100,9 @@ and where the data is from as well as where it can be overridden. The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings. +Since this feature shares a lot of similarities and implementation details with the navigation menu, +I recommend you read the [navigation menu documentation](navigation-menu) page as well to learn more about the fundamentals and terminology. + ### Sidebar ordering The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. From 9bc1dbc6be107d760fcfca0f5522ad8ce54b7653 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:27:59 +0100 Subject: [PATCH 41/64] Move helper note --- docs/creating-content/documentation-pages.md | 2 ++ docs/digging-deeper/customization.md | 2 -- docs/digging-deeper/navigation.md | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 2dfe2ab7cde..7d6170b3501 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -167,6 +167,8 @@ For example, putting a Markdown file in `_docs/getting-started/`, is equivalent >info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. +>info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. + ### Hiding items You can hide items from the sidebar by adding the `hidden` property to the front matter: diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index c66bbcd9e78..858e9d240c5 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -221,8 +221,6 @@ Learn more in the [Navigation Menu](navigation) documentation. Learn more in the [Documentation Pages](documentation-pages) documentation. ->info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. - ## Additional Advanced Options The following configuration options in the `confg/hyde.php` file are intended for advanced users and diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 966904f0f74..0d62fab87ac 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -288,6 +288,7 @@ This feature is enabled by default, so you only need to place your pages in subd For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". +>info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. ## Digging deeper into the internals From b6a5a260544ab30ab70c03bf440bdb18d8485ab2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:30:49 +0100 Subject: [PATCH 42/64] Fix grammar and spelling --- docs/digging-deeper/navigation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 0d62fab87ac..2b6a7915f14 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -27,14 +27,14 @@ Keep on reading to learn how! To learn even more about the sidebars, visit the [ It may be beneficial to understand the internal workings of the navigation menus to take full advantage of the options. In short, both navigation menu types extend the same class (meaning they share the same base code), this means that the way -they are configured are very similar, making the documentation here applicable to both types of menus. +they are configured is very similar, making the documentation here applicable to both types of menus. See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! ### 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. +All navigation menu items have an internal priority value that determines their order in the navigation. +Lower values mean 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`, ### What to customize? @@ -50,7 +50,7 @@ Here is a quick overview of what you might want to customize in your navigation Hyde provides a few different ways to customize the navigation menus, depending on what you prefer. -Specifying the data in the front matter will override any dynamically inferred or config defined priority. +Specifying the data in the front matter 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 as you can't see the whole picture at once. It's up to you which method you prefer to use. @@ -226,10 +226,10 @@ To remove items from being automatically added, simply add the page's route key ### 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. +You can easily add custom navigation menu links similar to 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`. +destination and label, both required. The third argument is the priority, which is optional, and defaults to `500`. ```php // filepath config/hyde.php @@ -269,7 +269,7 @@ HydePHP has a neat feature to automatically place pages in dropdowns based on su #### Automatic navigation menu dropdowns -For pages that can be in the main site menu, ths feature needs to be enabled in the `hyde.php` config file. +For pages that can be in the main site menu, this feature needs to be enabled in the `hyde.php` config file. ```php // filepath config/hyde.php @@ -283,7 +283,7 @@ Now if you create a page called `_pages/about/contact.md` it will automatically #### Automatic documentation sidebar grouping -This feature works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups. +This feature works similarly to the automatic navigation menu dropdowns, but instead places the sidebar items in named groups. This feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped. For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". From d0032971cc7e6c62d2092936e879f2fb02bede89 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:33:30 +0100 Subject: [PATCH 43/64] Formatting --- docs/digging-deeper/navigation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 2b6a7915f14..08e9e15a68c 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -290,6 +290,7 @@ For example: `_docs/getting-started/installation.md` will be placed in a group c >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. + ## Digging deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. From bbfc980db8e1b8b3a2d66f4628a74ecb0d0fb4e6 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 19:53:48 +0100 Subject: [PATCH 44/64] Fix wrong documentation link --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 7d6170b3501..a1ff0967fba 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -101,7 +101,7 @@ The sidebar is automatically generated from the files in the `_docs` directory. of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings. Since this feature shares a lot of similarities and implementation details with the navigation menu, -I recommend you read the [navigation menu documentation](navigation-menu) page as well to learn more about the fundamentals and terminology. +I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology. ### Sidebar ordering From d4dbda008db158ff5279f246f53b3b482b5843fe Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 20:02:16 +0100 Subject: [PATCH 45/64] Formatting --- docs/digging-deeper/navigation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 08e9e15a68c..051ca1661e7 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -182,7 +182,7 @@ You can also specify explicit priorities by adding a value to the array key: ] ``` -You can of course also combine these methods if you want: +**You can of course also combine these methods if you want:** ```php // filepath: Applicable to both @@ -252,7 +252,7 @@ Simplified, this will then be rendered as follows: Within the Hyde config you can configure how subdirectories should be displayed in the menu. -``` +```php // filepath config/hyde.php 'navigation' => [ 'subdirectories' => 'dropdown' From 339ee849e14689373a18281accf264e7d07e2875 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 23:36:07 +0100 Subject: [PATCH 46/64] Update workflow name for merged jobs --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 97566040352..9a50e8b0115 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -8,7 +8,7 @@ on: jobs: - build-documentation-preview: + build-and-deploy-documentation-preview: # We could add a check to only rerun if docs have changed since last run on the PR # But this would require a state storage, and the current version is good enough. if: "! contains(github.event.pull_request.labels.*.name, 'pause-pages')" From ffbeb3c2899bc0e8e2204d428d7701e3b96e06ab Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 23:36:28 +0100 Subject: [PATCH 47/64] Remove legacy upload job --- .../deploy-documentation-preview.yml | 30 ------------------- 1 file changed, 30 deletions(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 9a50e8b0115..e96e202efc1 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -100,33 +100,3 @@ jobs: with: name: 'preview-docs' path: '_site/dev-docs-preview' - - - upload-generated-site: - - runs-on: ubuntu-latest - needs: - - build-documentation-preview - - steps: - - uses: actions/checkout@v3 - with: - ref: 'gh-pages' - - - name: Reset output directories - run: | - rm -rf pr-${{ github.event.pull_request.number }}/dev-docs-preview - mkdir -p pr-${{ github.event.pull_request.number }}/dev-docs-preview - - - name: Download documentation artifact - uses: actions/download-artifact@v3 - with: - name: preview-docs - path: pr-${{ github.event.pull_request.number }}/dev-docs-preview - - - name: Commit changes - uses: EndBug/add-and-commit@v9 - with: - pull: 'origin gh-pages' - add: 'pr-${{ github.event.pull_request.number }}/dev-docs-preview' - message: 'Upload documentation preview for PR ${{ github.event.pull_request.number }}' From 4ef2467fcd9dea54f5b39babaf78623891601d7c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 23:37:08 +0100 Subject: [PATCH 48/64] Remove artifact upload --- .github/workflows/deploy-documentation-preview.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index e96e202efc1..e4bb1378bef 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -94,9 +94,3 @@ jobs: - name: Compile the static site run: php hyde build - - - name: Upload artifacts - uses: actions/upload-artifact@v1 - with: - name: 'preview-docs' - path: '_site/dev-docs-preview' From 93c2a17811c20b958d9a615ce5d00dcc01fb7146 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 23:45:33 +0100 Subject: [PATCH 49/64] Deploy to the new preview server --- .../deploy-documentation-preview.yml | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index e4bb1378bef..3ef9c374e63 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -94,3 +94,26 @@ jobs: - name: Compile the static site run: php hyde build + + - name: Package the static site + run: zip -r site.zip _site + + - name: Sign the artifact + run: openssl dgst -sha256 -sign ${{ secrets.CI_PREVIEW_SIGNING_RSA_PRIVATE_KEY }} -out signature.bin site.zip + + - name: Upload the artifact + run: | + repository="develop" + bearerToken="${{ secrets.CI_SERVER_TOKEN }}" + pullRequest="${{ github.event.pull_request.number }}" + signature=$(openssl base64 -in signature.bin) + artifact="site.zip" + + curl -X POST \ + -H 'Content-Type: multipart/form-data' \ + -H "Authorization: Bearer $bearerToken" \ + -F 'repository=$repository \ + -F 'pullRequest=$pullRequest' \ + -F 'artifact=@$artifact' \ + -F 'signature=$signature' \ + https://ci.hydephp.com/api/deployment-previews From 8f891456b47d30d766f4f72f2f24726ffaf56fa2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 23:48:16 +0100 Subject: [PATCH 50/64] Update environment --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 3ef9c374e63..7cf44f81c2a 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -15,7 +15,7 @@ jobs: environment: name: pr-documentation-${{ github.event.pull_request.number }} - url: https://hydephp.github.io/develop/pr-${{ github.event.pull_request.number }}/dev-docs-preview + url: https://ci.hydephp.com/previews/develop/${{ github.event.pull_request.number }} runs-on: ubuntu-latest From 23c60d1dbb9ec696a20609543b0540aeae0d2ee6 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 23:49:02 +0100 Subject: [PATCH 51/64] Write to temporary file --- .github/workflows/deploy-documentation-preview.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 7cf44f81c2a..eb728999dd2 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -99,7 +99,10 @@ jobs: run: zip -r site.zip _site - name: Sign the artifact - run: openssl dgst -sha256 -sign ${{ secrets.CI_PREVIEW_SIGNING_RSA_PRIVATE_KEY }} -out signature.bin site.zip + run: | + echo ${{ secrets.CI_PREVIEW_SIGNING_RSA_PRIVATE_KEY }} > private.pem + openssl dgst -sha256 -sign private.pem -out signature.bin site.zip + unlink private.pem - name: Upload the artifact run: | From 43ab519b1cd897a7af438a8736478c782aac94f5 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 9 Feb 2024 23:50:28 +0100 Subject: [PATCH 52/64] Add quotes --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index eb728999dd2..7c232c290f7 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -100,7 +100,7 @@ jobs: - name: Sign the artifact run: | - echo ${{ secrets.CI_PREVIEW_SIGNING_RSA_PRIVATE_KEY }} > private.pem + echo '${{ secrets.CI_PREVIEW_SIGNING_RSA_PRIVATE_KEY }}' > private.pem openssl dgst -sha256 -sign private.pem -out signature.bin site.zip unlink private.pem From b209afb002e81402432a8f4d9bf27c18a2d30120 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 11:28:29 +0100 Subject: [PATCH 53/64] Add quotes --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 7c232c290f7..1551e118f84 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -109,7 +109,7 @@ jobs: repository="develop" bearerToken="${{ secrets.CI_SERVER_TOKEN }}" pullRequest="${{ github.event.pull_request.number }}" - signature=$(openssl base64 -in signature.bin) + signature="$(openssl base64 -in signature.bin)" artifact="site.zip" curl -X POST \ From eca83ea0a5e1aadfd7618a4c8e17d60de32dd875 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 11:30:15 +0100 Subject: [PATCH 54/64] Add missing quote --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 1551e118f84..b3d7e6520d1 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -115,7 +115,7 @@ jobs: curl -X POST \ -H 'Content-Type: multipart/form-data' \ -H "Authorization: Bearer $bearerToken" \ - -F 'repository=$repository \ + -F 'repository=$repository' \ -F 'pullRequest=$pullRequest' \ -F 'artifact=@$artifact' \ -F 'signature=$signature' \ From 9f009f41c26e3fd26a9b533adfb3a0a7591e4acb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 11:31:43 +0100 Subject: [PATCH 55/64] Replace quotes --- .github/workflows/deploy-documentation-preview.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index b3d7e6520d1..dddebf96582 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -113,10 +113,10 @@ jobs: artifact="site.zip" curl -X POST \ - -H 'Content-Type: multipart/form-data' \ + -H "Content-Type: multipart/form-data" \ -H "Authorization: Bearer $bearerToken" \ - -F 'repository=$repository' \ - -F 'pullRequest=$pullRequest' \ - -F 'artifact=@$artifact' \ - -F 'signature=$signature' \ + -F "repository=$repository" \ + -F "pullRequest=$pullRequest" \ + -F "artifact=@$artifact" \ + -F "signature=$signature" \ https://ci.hydephp.com/api/deployment-previews From 339699df46dc1d2cfdefcedd1defcfb2e46d45a2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 11:34:31 +0100 Subject: [PATCH 56/64] Update Curl to fail with body --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index dddebf96582..790441d46cd 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -112,7 +112,7 @@ jobs: signature="$(openssl base64 -in signature.bin)" artifact="site.zip" - curl -X POST \ + curl -X POST --fail-with-body \ -H "Content-Type: multipart/form-data" \ -H "Authorization: Bearer $bearerToken" \ -F "repository=$repository" \ From e5e9ad5f2c4313ddd74df553f1197f370879e082 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 11:37:27 +0100 Subject: [PATCH 57/64] Update environment URL --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 790441d46cd..4cbc7a4b77b 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -87,7 +87,7 @@ jobs: - name: Configure environment variables run: | echo 'SITE_NAME="HydePHP Documentation Preview"' >> .env - echo 'SITE_URL="https://hydephp.github.io/develop/pr-${{ github.event.pull_request.number }}/dev-docs-preview"' >> .env + echo 'SITE_URL="https://ci.hydephp.com/previews/develop/${{ github.event.pull_request.number }}"' >> .env - name: Move documentation files run: rm -rf _docs && mv -f docs _docs From 2d1921345faa50163477cd5000cc3150da1836ae Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 11:37:44 +0100 Subject: [PATCH 58/64] Add workflow path to triggers --- .github/workflows/deploy-documentation-preview.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 4cbc7a4b77b..bc1815c6b3f 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -5,6 +5,7 @@ on: branches: [ "master" ] paths: - 'docs/**' + - '.github/workflows/deploy-documentation-preview.yml' jobs: From 9dfa94f6762de7477eb0bab56c18532be4ec2f5c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 12:01:36 +0100 Subject: [PATCH 59/64] Output preview documentation pages to site root --- .github/workflows/deploy-documentation-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index bc1815c6b3f..8a80af23d3a 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -50,7 +50,7 @@ jobs: - name: Update configuration files run: | echo "output_directories:" >> hyde.yml - echo " Hyde\Pages\DocumentationPage: dev-docs-preview" >> hyde.yml + echo " Hyde\Pages\DocumentationPage: ''" >> hyde.yml sed -i "s/'header' => env('SITE_NAME', 'HydePHP').' Docs'/'header' => 'PR #${{ github.event.pull_request.number }} - Docs'/g" config/docs.php - name: Remove published article component From 4ce2a6f4876b4f886276a7438a2ef67fac41bc25 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 12:39:57 +0100 Subject: [PATCH 60/64] Use runner PHP --- .github/workflows/deploy-documentation-preview.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 8a80af23d3a..1b223a7562e 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -22,9 +22,10 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: shivammathur/setup-php@v2 - with: - php-version: "8.1" +# Disabled as it should not be necessary, and it takes a long time to run +# - uses: shivammathur/setup-php@v2 +# with: +# php-version: "8.1" - name: Cache Composer packages id: composer-cache From 936ea05744b31da3fdd15d816b02d53a38ec3e90 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 14:48:31 +0100 Subject: [PATCH 61/64] Remove commented code --- .github/workflows/deploy-documentation-preview.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 1b223a7562e..b5ecb8758f5 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -22,10 +22,6 @@ jobs: steps: - uses: actions/checkout@v3 -# Disabled as it should not be necessary, and it takes a long time to run -# - uses: shivammathur/setup-php@v2 -# with: -# php-version: "8.1" - name: Cache Composer packages id: composer-cache From 1fe148e6ae7b1436b53bd4788a375058d5da42a2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 14:48:47 +0100 Subject: [PATCH 62/64] Remove old todo Not worth it anymore with the faster deployment server --- .github/workflows/deploy-documentation-preview.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index b5ecb8758f5..539639f1bd2 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -10,8 +10,6 @@ on: jobs: build-and-deploy-documentation-preview: - # We could add a check to only rerun if docs have changed since last run on the PR - # But this would require a state storage, and the current version is good enough. if: "! contains(github.event.pull_request.labels.*.name, 'pause-pages')" environment: From 7cfaef5af68d18470d161845c1652ee18b5aa09f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 14:50:57 +0100 Subject: [PATCH 63/64] Normalize whitespace --- .github/workflows/deploy-documentation-preview.yml | 2 +- .github/workflows/hyde-stan.yml | 1 - docs/architecture-concepts/the-hydekernel.md | 2 +- docs/digging-deeper/customization.md | 4 ++-- docs/digging-deeper/updating-hyde.md | 2 +- 5 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index 539639f1bd2..cb118a7665a 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -107,7 +107,7 @@ jobs: pullRequest="${{ github.event.pull_request.number }}" signature="$(openssl base64 -in signature.bin)" artifact="site.zip" - + curl -X POST --fail-with-body \ -H "Content-Type: multipart/form-data" \ -H "Authorization: Bearer $bearerToken" \ diff --git a/.github/workflows/hyde-stan.yml b/.github/workflows/hyde-stan.yml index fcb4b436964..34f4b1bcfda 100644 --- a/.github/workflows/hyde-stan.yml +++ b/.github/workflows/hyde-stan.yml @@ -21,4 +21,3 @@ jobs: - name: Run HydeFront linter run: php packages/hydefront/.github/scripts/post-build.php - diff --git a/docs/architecture-concepts/the-hydekernel.md b/docs/architecture-concepts/the-hydekernel.md index 0bb6b2d4c63..1e600e1e18f 100644 --- a/docs/architecture-concepts/the-hydekernel.md +++ b/docs/architecture-concepts/the-hydekernel.md @@ -26,7 +26,7 @@ The HydeKernel is stored as a singleton in a static property in its own class an Commonly, you'll use the `Hyde` facade which forwards calls to the singleton instance. You can also use the `hyde()` function to get the Kernel, and call methods on it. -Since the instance is also bound into the Laravel Application Service Container you can also use Dependency Injection by type-hinting the `HydeKernel::class`. +Since the instance is also bound into the Laravel Application Service Container you can also use Dependency Injection by type-hinting the `HydeKernel::class`. Here are some examples of how you can call methods on the Kernel. All methods call the same method on the same instance, so it's just a matter of preference. diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 858e9d240c5..e737a9f5c76 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -223,12 +223,12 @@ Learn more in the [Documentation Pages](documentation-pages) documentation. ## Additional Advanced Options -The following configuration options in the `confg/hyde.php` file are intended for advanced users and +The following configuration options in the `confg/hyde.php` file are intended for advanced users and should only be modified if you fully understand their impact. The code examples show the default values. ### `media_extensions` -This option allows you to specify file extensions considered as media files, which will be copied to the output directory. +This option allows you to specify file extensions considered as media files, which will be copied to the output directory. To add more extensions, either append them to the existing array or override the entire array. ```php diff --git a/docs/digging-deeper/updating-hyde.md b/docs/digging-deeper/updating-hyde.md index 0acb3d6ce11..b904b337724 100644 --- a/docs/digging-deeper/updating-hyde.md +++ b/docs/digging-deeper/updating-hyde.md @@ -27,7 +27,7 @@ hence why version controlling your site is helpful when updating versions as you be helpful to version control the compiled HTML, so you can view a diff of the changes. Be sure to test that your site can be built and that it looks as expected after updating before deploying the changes to your live site. -We of course have extensive tests in place run on each single code commit to ensure all code is functional, however, +We of course have extensive tests in place run on each single code commit to ensure all code is functional, however, it is still possible that some edge cases slip through. This means that a bug fix may impact an edge case that you depend on. Obligatory related XKCD: [https://xkcd.com/1172](https://xkcd.com/1172) From d4fdd49acdbecda7ceb8337105285d557bc7514f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 10 Feb 2024 14:51:16 +0100 Subject: [PATCH 64/64] Format Markdown --- docs/architecture-concepts/the-hydekernel.md | 1 + docs/digging-deeper/customization.md | 5 +++++ docs/digging-deeper/updating-hyde.md | 2 ++ docs/extensions/extensions.md | 1 + docs/extensions/ui-kit.md | 3 +++ 5 files changed, 12 insertions(+) diff --git a/docs/architecture-concepts/the-hydekernel.md b/docs/architecture-concepts/the-hydekernel.md index 1e600e1e18f..55d2c494c2d 100644 --- a/docs/architecture-concepts/the-hydekernel.md +++ b/docs/architecture-concepts/the-hydekernel.md @@ -43,6 +43,7 @@ hyde()->version(); The Kernel instance is constructed in `bootstrap.php`, and is available globally as `$hyde`. + ## The kernel lifecycle Whenever we talk about the kernel being "booted" we are talking about the kernel's role in the autodiscovery process. diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index e737a9f5c76..a1282434c58 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -221,6 +221,7 @@ Learn more in the [Navigation Menu](navigation) documentation. Learn more in the [Documentation Pages](documentation-pages) documentation. + ## Additional Advanced Options The following configuration options in the `confg/hyde.php` file are intended for advanced users and @@ -281,6 +282,7 @@ use \Hyde\Framework\Services\AssetService; 'hydefront_cdn_url' => AssetService::HYDEFRONT_CDN_URL, ``` + ## Blade Views Hyde uses the Laravel Blade templating engine. Most parts of the included templates have been extracted into components to be customized easily. @@ -294,12 +296,14 @@ php hyde publish:views The files will then be available in the `resources/views/vendor/hyde` directory. + ## Frontend Styles Hyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template for you to get up and running quickly. If you want to customize these, you are free to do so. Please see the [Managing Assets](managing-assets) page to learn more. + ## Markdown Configuration Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML, and @@ -362,6 +366,7 @@ arbitrary PHP code specified in Markdown to be executed. It's easy to enable how See the [Blade in Markdown](advanced-markdown#blade-support) documentation for more information on how to use this feature. + ## YAML Configuration The settings in the `config/hyde.php` file can also be set by using a `hyde.yml` file in the root of your project directory. diff --git a/docs/digging-deeper/updating-hyde.md b/docs/digging-deeper/updating-hyde.md index b904b337724..f12d23790a4 100644 --- a/docs/digging-deeper/updating-hyde.md +++ b/docs/digging-deeper/updating-hyde.md @@ -13,6 +13,7 @@ This guide will help you update your HydePHP project to the latest version. When updating an existing installation, first ensure that you have a backup of your project in case anything goes wrong. The recommended way to do this is to use Git as that allows you to smoothly roll back any changes. + ## Version compatibility HydePHP follows [semantic versioning](https://semver.org/), so you can expect that minor and patch releases will be backwards compatible. @@ -32,6 +33,7 @@ it is still possible that some edge cases slip through. This means that a bug fi Obligatory related XKCD: [https://xkcd.com/1172](https://xkcd.com/1172) + ## Methods ### Which method? diff --git a/docs/extensions/extensions.md b/docs/extensions/extensions.md index 28bf3100648..db3095658b6 100644 --- a/docs/extensions/extensions.md +++ b/docs/extensions/extensions.md @@ -29,6 +29,7 @@ The [HydePHP UI Kit](https://github.com/hydephp/ui-kit) is a set of minimalistic The [GitHub Action for HydePHP](https://github.com/hydephp/action) is hands-down the easiest way to build and deploy your Hyde site to GitHub Pages. - Learn more at https://github.com/hydephp/action and see the documentation at https://hydephp.github.io/action + ## Integrations with third-party tools ### Torchlight diff --git a/docs/extensions/ui-kit.md b/docs/extensions/ui-kit.md index b632c0719cc..84ebe97d178 100644 --- a/docs/extensions/ui-kit.md +++ b/docs/extensions/ui-kit.md @@ -4,12 +4,14 @@ The HydePHP UI Kit is a collection of minimalistic and un-opinionated TailwindCS indented to be used with HydePHP. Note that these components may require CSS classes not present in the bundled app.css file and that you may need to recompile the CSS file using the included Laravel Mix configuration. + ## Screenshot Here are some of the components you can use to build your next project! As you can see, all components support both light and dark mode out of the box, just like the rest of HydePHP. ![Components Screenshot](https://raw.githubusercontent.com/hydephp/ui-kit/art/header-large-min.png) + ## Components Please make sure you're familiar with [Laravel Blade](https://laravel.com/docs/blade) before using the HydePHP UI Kit. @@ -159,6 +161,7 @@ You can get surprisingly far when you combine the components. Take this newslett ![Newsletter Screenshot](https://raw.githubusercontent.com/hydephp/ui-kit/art/newsletter-signup-example-min.png) + ## GitHub Repository You can find the source code for the UI Kit on GitHub at [hydephp/ui-kit](https://github.com/hydephp/ui-kit).