From 901b810ef1f0846b1cb4bc30780ba2a2f1d568c1 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 10:42:54 +0200 Subject: [PATCH 01/39] Create Claude draft --- context.php | 330 ++++++++++++++++++++++++++ docs/digging-deeper/navigation.md | 371 ++++++++---------------------- 2 files changed, 428 insertions(+), 273 deletions(-) create mode 100644 context.php diff --git a/context.php b/context.php new file mode 100644 index 00000000000..b338e14ca4d --- /dev/null +++ b/context.php @@ -0,0 +1,330 @@ + + /* + |-------------------------------------------------------------------------- + | Navigation Menu Configuration + |-------------------------------------------------------------------------- + | + | If you are looking to customize the main navigation menu, this is the place! + | + | All these settings uses Route Keys to identify the page you want to configure. + | A route key is simply the URL path to the page, without the file extension. + | So `_site/posts/hello-world.html` has the route key 'posts/hello-world'. + | + */ + + // OLD + + 'navigation' => [ + // This configuration sets the priorities used to determine the order of the menu. + // The default values have been added below for reference and easy editing. + // The array key is the page's route key, the value is the priority. + // Lower values show up first in the menu. The default is 999. + 'order' => [ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, + ], + + // In case you want to customize the labels for the menu items, you can do so here. + // Simply add the route key as the array key, and the label as the value. + 'labels' => [ + 'index' => 'Home', + 'docs/index' => 'Docs', + ], + + // These are the route keys of pages that should not show up in the navigation menu. + 'exclude' => [ + '404', + ], + + // Any extra links you want to add to the navigation menu can be added here. + // To get started quickly, you can uncomment the defaults here. + // See the documentation link above for more information. + 'custom' => [ + // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200), + ], + + // How should pages in subdirectories be displayed in the menu? + // You can choose between 'dropdown', 'flat', and 'hidden'. + 'subdirectories' => 'hidden', + ], + + + // NEW (creates an array exactly like the one above, but with a more fluent API that supports better autocomplete) + + 'navigation' => Navigation::configure() + ->setPagePriorities([ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, + ]) + ->setPageLabels([ + 'index' => 'Home', + 'docs/index' => 'Docs', + ]) + ->excludePages([ + '404', + ]) + ->addNavigationItems([ + // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), + ]) + ->setSubdirectoryDisplayMode('hidden'), + + // All of these options work in the yaml config (this is just an example, please use the same example data as above in the docs) + hyde: + navigation: + custom: + - destination: 'https://example.com' + label: 'Example' + priority: 100 + attributes: + class: 'example' + - destination: 'about' + label: 'About Us' + priority: 200 + attributes: + class: 'about' + id: 'about' + - destination: 'contact' + label: 'Contact' + priority: 300 + attributes: + target: '_blank' + rel: 'noopener noreferrer' + foo: 'bar' + + +// relevant code snippets + +|string $destination Route key, or an external URI. + * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. + * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. + * @param array $attributes Additional attributes for the navigation item. + * @return array{destination: string, label: ?string, priority: ?int, attributes: array} + */ + public static function item(string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): array + { + return compact('destination', 'label', 'priority', 'attributes'); + } + + /** + * Configuration helper method to define the navigation menu configuration with better IDE support. + * + * The builder is an array object that will be used by the framework to set the navigation menu configuration. + * + * @experimental This method is experimental and may change or be removed before the final release. + */ + public static function configure(): NavigationMenuConfigurationBuilder + { + return new NavigationMenuConfigurationBuilder(); + } +} + +|array $order + * @return $this + */ + public function setPagePriorities(array $order): static + { + $this['order'] = $order; + + return $this; + } + + /** + * Set the labels for the navigation items. + * + * Each key should be a route key, and the value should be the label to display. + * + * @param array $labels + * @return $this + */ + public function setPageLabels(array $labels): static + { + $this['labels'] = $labels; + + return $this; + } + + /** + * Exclude certain items from the navigation. + * + * Each item should be a route key for the page to exclude. + * + * @param array $exclude + * @return $this + */ + public function excludePages(array $exclude): static + { + $this['exclude'] = $exclude; + + return $this; + } + + /** + * Add custom items to the navigation. + * + * @example `[Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200, ['target' => '_blank'])]` + * + * @param array}> $custom + * @return $this + */ + public function addNavigationItems(array $custom): static + { + $this['custom'] = $custom; + + return $this; + } + + /** + * Set the display mode for pages in subdirectories. + * + * You can choose between 'dropdown', 'flat', and 'hidden'. The default is 'hidden'. + * + * @param 'dropdown'|'flat'|'hidden' $displayMode + * @return $this + */ + public function setSubdirectoryDisplayMode(string $displayMode): static + { + self::assertType(['dropdown', 'flat', 'hidden'], $displayMode); + + $this['subdirectory_display'] = $displayMode; + + return $this; + } + + /** + * Hide pages in subdirectories from the navigation. + * + * @experimental This method is experimental and may change or be removed before the final release. + * + * @return $this + */ + public function hideSubdirectoriesFromNavigation(): static + { + return $this->setSubdirectoryDisplayMode('hidden'); + } + + /** + * Get the instance as an array. + * + * @return array{order: array, labels: array, exclude: array, custom: array}>, subdirectory_display: string} + */ + public function toArray(): array + { + return $this->getArrayCopy(); + } + + /** @experimental May be moved to a separate helper class in the future. */ + protected static function assertType(array $types, string $value): void + { + if (! in_array($value, $types)) { + throw new TypeError('Value must be one of: '.implode(', ', $types)); + } + } +} + + +// The docs config has not been updated to use the builder api + + /* + |-------------------------------------------------------------------------- + | Sidebar Settings + |-------------------------------------------------------------------------- + | + | The Hyde Documentation Module comes with a fancy Sidebar that is + | automatically populated with links to your documentation pages. + | Here, you can configure its behavior, content, look and feel. + | + */ + + 'sidebar' => [ + // The title in the sidebar header + 'header' => env('SITE_NAME', 'HydePHP').' Docs', + + // When using a grouped sidebar, should the groups be collapsible? + 'collapsible' => true, + + // A string of Markdown to show in the footer. Set to `false` to disable. + 'footer' => '[Back to home page](../)', + + /* + |-------------------------------------------------------------------------- + | Sidebar Page Order + |-------------------------------------------------------------------------- + | + | In the generated Documentation pages the navigation links in the sidebar + | default to sort alphabetically. You can reorder the page identifiers + | in the list below, and the links will get sorted in that order. + | + | The items will get a priority of 500 plus the order its found in the list. + | Pages without a priority will fall back to the default priority of 999. + | + | You can also set explicit priorities in front matter or by specifying + | a value to the array key in the list to override the inferred value. + | + */ + + 'order' => [ + 'readme', + 'installation', + 'getting-started', + ], + + /* + |-------------------------------------------------------------------------- + | Table of Contents Settings + |-------------------------------------------------------------------------- + | + | The Hyde Documentation Module comes with a fancy Sidebar that, by default, + | has a Table of Contents included. Here, you can configure its behavior, + | content, look and feel. You can also disable the feature completely. + | + */ + + 'table_of_contents' => [ + 'enabled' => true, + 'min_heading_level' => 2, + 'max_heading_level' => 4, + ], + + ], \ No newline at end of file diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 1f037908a70..36482372801 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -37,331 +37,156 @@ Here's an overview of what you can customize in your navigation menus: - Item visibility: Choose to hide or show pages in the menu - Item grouping: Group pages together in dropdowns or sidebar categories -### Customization Methods +## Configuration Methods Hyde provides multiple ways to customize navigation menus to suit your needs: 1. Front matter data in Markdown and Blade page files, applicable to all menu types -2. Configuration in the `hyde` config file for main navigation items -3. Configuration in the `docs` config file for documentation sidebar items +2. Configuration in the `hyde.php` or `hyde.yml` config file for main navigation items +3. Configuration in the `docs.php` config file for documentation sidebar items -Keep in mind that front matter data overrides dynamically inferred or config-defined priorities. While useful for quick one-off changes on small sites, it can make reordering items later on more challenging as you can't see the entire structure at once. +The new builder pattern in the configuration allows for a more fluent and IDE-friendly way to customize navigation. However, the old array-based method still works, as the navigation builder is an `ArrayObject` and can be used as an array. -Additionally, general options for the entire navigation menus are also available in the `hyde` and `docs` config files. +### Using the Navigation Builder -## Front Matter Configuration - -Front matter options allow per-page customization of navigation menus. Here's a quick reference of available options: - -```yaml -navigation: - label: string # The displayed text in the navigation item link - priority: int # The page's priority for ordering (lower means higher up/first) - hidden: bool # Whether the page should be hidden from the navigation menu - group: string # Set main menu dropdown or sidebar group key -``` - -You only need to specify the keys you want to customize. - -### `label` - -Customizes the text appearing in the navigation menu link for the page. If not set anywhere else, Hyde will search for a title in the page content or generate one from the filename. - -```yaml -navigation: - label: "My Custom Label" -``` - -### `priority` - -Controls the order in which the page appears in the navigation menu. - -```yaml -navigation: - priority: 10 -``` - -### `hidden` - -Determines if the page appears in the navigation menu. - -```yaml -navigation: - hidden: true -``` - -**Tip:** You can also use `visible: false` to achieve the same effect. - -### `group` - -For the primary navigation menu, this groups pages together in dropdowns. For the sidebar, it groups pages under a common heading. - -```yaml -navigation: - group: "My Group" -``` - -**Note:** Sidebar group keys are normalized, so `My Group` and `my-group` are equivalent. - -## Config File Configuration - -Let's explore how to customize navigation menus using configuration files: - -- For the main navigation menu, use `navigation` setting in the `hyde.php` config file. -- For the sidebar, use `sidebar` setting in the `docs.php` config file. - -When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). - -### Changing Priorities - -The `navigation.order` and `sidebar.order` settings allow you to customize the order of pages in the navigation menus. - -#### Basic Priority Syntax - -A nice and simple way to define the order of pages, is to add their route keys as a simple list array. We'll then match that array order. - -It may be useful to know that we internally will assign a 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. +To use the new builder pattern, you can configure your navigation in the `hyde.php` file like this: ```php -// filepath: config/hyde.php -'navigation' => [ - 'order' => [ - 'home', // Priority: 500 - 'about', // Priority: 501 - 'contact', // Priority: 502 - ] -] -``` +use Hyde\Facades\Navigation; -```php -// filepath: config/docs.php -'sidebar' => [ - 'order' => [ - 'readme', // Priority: 500 - 'installation', // Priority: 501 - 'getting-started', // Priority: 502 - ] -] -``` +return [ + // ... + + 'navigation' => Navigation::configure() + ->setPagePriorities([ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, + ]) + ->setPageLabels([ + 'index' => 'Home', + 'docs/index' => 'Docs', + ]) + ->excludePages([ + '404', + ]) + ->addNavigationItems([ + Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), + ]) + ->setSubdirectoryDisplayMode('hidden'), +]; +``` + +### Using YAML Configuration + +You can also set the navigation configuration in the `hyde.yml` file. The structure remains the same as the array-based method: -#### Explicit Priority Syntax +```yaml +hyde: + navigation: + order: + index: 0 + posts: 10 + docs/index: 100 + labels: + index: Home + docs/index: Docs + exclude: + - 404 + custom: + - destination: 'https://github.com/hydephp/hyde' + label: 'GitHub' + priority: 200 + subdirectory_display: hidden +``` + +## Customization Options -You can also specify explicit priorities by adding a value to the array keys. We'll then use these exact values as the priorities. +Here's an overview of what you can customize in your navigation menus: -```php -// filepath: config/hyde.php -'navigation' => [ - 'order' => [ - 'home' => 10, - 'about' => 15, - 'contact' => 20, - ] -] -``` +- Item labels: The text displayed in menu links +- Item priorities: Control the order of link appearance +- Item visibility: Choose to hide or show pages in the menu +- Item grouping: Group pages together in dropdowns or sidebar categories -```php -// filepath: config/docs.php -'sidebar' => [ - 'order' => [ - 'readme' => 10, - 'installation' => 15, - 'getting-started' => 20, - ] -] -``` +### Setting Page Priorities -You could also combine these methods if desired: +Use the `setPagePriorities` method to define the order of pages in the navigation menu: ```php -// filepath: Applicable to both -[ - 'readme' => 10, // Priority: 10 - 'installation', // Priority: 500 - 'getting-started', // Priority: 501 -] +->setPagePriorities([ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, +]) ``` ### Changing Menu Item Labels -Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. - -If you're not happy with these, it's easy to override navigation link labels by mapping the route key to the desired title in the Hyde config: +Override navigation link labels using the `setPageLabels` method: ```php -// filepath: config/hyde.php -'navigation' => [ - 'labels' => [ - 'index' => 'Start', - 'docs/index' => 'Documentation', - ] -] +->setPageLabels([ + 'index' => 'Home', + 'docs/index' => 'Documentation', +]) ``` -**Note:** This feature is not yet supported for the sidebar. - -### Excluding Items (Blacklist) +### Excluding Items -When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. - -To exclude items from being added, simply add the page's route key to the navigation blacklist in the Hyde config: +Prevent links from being added to the main navigation menu using the `excludePages` method: ```php -// filepath: config/hyde.php -'navigation' => [ - 'exclude' => [ - '404' - ] -] +->excludePages([ + '404', +]) ``` ### Adding Custom Navigation Menu Links -You can easily add custom navigation menu links in the Hyde config: +Add custom navigation menu links using the `addNavigationItems` method: ```php -// filepath: config/hyde.php -use Hyde\Facades\Navigation; - -'navigation' => [ - 'custom' => [ - Navigation::item( - destination: 'https://github.com/hydephp/hyde', // Required - label: 'GitHub', // Optional, defaults to the destination value - priority: 200 // Optional, defaults to 500 - ), - ] -] +->addNavigationItems([ + Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), +]) ``` -**Tip:** While named arguments are used in the example for clarity, they are not required. - - ### Configure Subdirectory Display -You can configure how subdirectories should be displayed in the menu: +Set how subdirectories should be displayed in the menu using the `setSubdirectoryDisplayMode` method: ```php -// filepath: config/hyde.php -'navigation' => [ - 'subdirectory_display' => 'dropdown' -] +->setSubdirectoryDisplayMode('dropdown') ``` -**Supported Options:** -- `dropdown`: Pages in subdirectories are displayed in a dropdown menu -- `hidden`: Pages in subdirectories are not displayed at all the menus -- `flat`: Pages in subdirectories are displayed as individual items - -### Automatic Menu Groups +Supported options are 'dropdown', 'hidden', and 'flat'. -A handy feature HydePHP has is that it can automatically place pages in dropdowns based on subdirectory structures. - -#### Automatic Navigation Menu Dropdowns +## Front Matter Configuration -Enable this feature in the `hyde.php` config file by setting the `subdirectory_display` key to `dropdown`. +Front matter options allow per-page customization of navigation menus. These options remain unchanged: -```php -// filepath: config/hyde.php -'navigation' => [ - 'subdirectory_display' => 'dropdown', -], +```yaml +navigation: + label: string # The displayed text in the navigation item link + priority: int # The page's priority for ordering (lower means higher up/first) + hidden: bool # Whether the page should be hidden from the navigation menu + group: string # Set main menu dropdown or sidebar group key ``` -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 is always enabled for documentation pages. Simply place your pages in subdirectories to have them grouped in the sidebar. - -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. - -#### Dropdown Menu Notes - -- Dropdowns take priority over standard items. If you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu. -- Example: With this file structure: `_pages/foo.md`, `_pages/foo/bar.md`, `_pages/foo/baz.md`, the link to `foo` will be lost, so please keep this in mind when using this feature. - ## Numerical Prefix Navigation Ordering -HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. +The numerical prefix navigation ordering feature remains unchanged. You can still use numerical prefixes in filenames to control the order of navigation items. -This has the great benefit of matching the navigation menu layout with the file structure view, and works especially great with subdirectory-based navigation grouping. - -```shell -_pages/ - 01-home.md # Priority: 1 (saved to _site/index.html) - 02-about.md # Priority: 2 (saved to _site/about.html) - 03-contact.md # Priority: 3 (saved to _site/contact.html) -``` - -As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. - -### Important Notes - -1. The numerical prefix remains part of the page identifier but is stripped from the route key. - For example: `_pages/01-home.md` has route key `home` and page identifier `01-home`. -2. You can delimit the numerical prefix with either a dash or an underscore. - For example: Both `_pages/01-home.md` and `_pages/01_home.md` are valid. -3. Leading zeros are optional. `_pages/1-home.md` is equally valid. - -### Using Numerical Prefix Ordering in Subdirectories - -This feature integrates well with automatic subdirectory-based navigation grouping. Here are two useful tips: - -1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. -2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. - -Here is an example structure of how could organize a documentation site: - -```shell -_docs/ - 01-getting-started/ - 01-installation.md - 02-requirements.md - 03-configuration.md - 02-usage/ - 01-quick-start.md - 02-advanced-usage.md - 03-features/ - 01-feature-1.md - 02-feature-2.md -``` - -### Customization - -If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. +To disable this feature, you can use the following configuration: ```php -// filepath: config/hyde.php -'numerical_page_ordering' => false, +return [ + // ... + 'numerical_page_ordering' => false, +]; ``` -## Digging Deeper into the Internals - -While not essential, understanding the internal workings of the navigation system can be as beneficial as it's interesting. Here's a quick high-level overview of the [Navigation API](navigation-api). - -### Navigation Menu Classes - -The main navigation menu uses the `MainNavigationMenu` class, while the documentation sidebar uses the `DocumentationSidebar` class. Both extend the base `NavigationMenu` class: - -```php -use Hyde\Framework\Features\Navigation\MainNavigationMenu; -use Hyde\Framework\Features\Navigation\DocumentationSidebar; -use Hyde\Framework\Features\Navigation\NavigationMenu; -``` - -The base `NavigationMenu` class contains the main logic for menu generation, while child implementations contain extra logic for specific use cases. - -All navigation menus store items in their `$items` collection, containing instances of the `NavigationItem` class. Dropdowns are represented by `NavigationGroup` instances, which extend the `NavigationMenu` class and contain additional `NavigationItem` instances: - -```php -use Hyde\Framework\Features\Navigation\NavigationItem; -use Hyde\Framework\Features\Navigation\NavigationGroup; -``` - -## The Navigation API - -For advanced users and package developers, Hyde offers a Navigation API for programmatic interaction with site navigation. This API consists of a set of PHP classes allowing fluent interaction with navigation menus. +## Conclusion -For more detailed information about the API, refer to the [Navigation API](navigation-api) documentation. +The new builder pattern provides a more fluent and IDE-friendly way to configure navigation in HydePHP. However, the old array-based method and YAML configuration are still supported, giving you flexibility in how you choose to customize your site's navigation. \ No newline at end of file From d51c4af5e4cc2810b9616769c1d4178f81ce6f2b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 12:54:18 +0200 Subject: [PATCH 02/39] Revert "Create Claude draft" This reverts commit 901b810ef1f0846b1cb4bc30780ba2a2f1d568c1. --- context.php | 330 -------------------------- docs/digging-deeper/navigation.md | 371 ++++++++++++++++++++++-------- 2 files changed, 273 insertions(+), 428 deletions(-) delete mode 100644 context.php diff --git a/context.php b/context.php deleted file mode 100644 index b338e14ca4d..00000000000 --- a/context.php +++ /dev/null @@ -1,330 +0,0 @@ - - /* - |-------------------------------------------------------------------------- - | Navigation Menu Configuration - |-------------------------------------------------------------------------- - | - | If you are looking to customize the main navigation menu, this is the place! - | - | All these settings uses Route Keys to identify the page you want to configure. - | A route key is simply the URL path to the page, without the file extension. - | So `_site/posts/hello-world.html` has the route key 'posts/hello-world'. - | - */ - - // OLD - - 'navigation' => [ - // This configuration sets the priorities used to determine the order of the menu. - // The default values have been added below for reference and easy editing. - // The array key is the page's route key, the value is the priority. - // Lower values show up first in the menu. The default is 999. - 'order' => [ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, - ], - - // In case you want to customize the labels for the menu items, you can do so here. - // Simply add the route key as the array key, and the label as the value. - 'labels' => [ - 'index' => 'Home', - 'docs/index' => 'Docs', - ], - - // These are the route keys of pages that should not show up in the navigation menu. - 'exclude' => [ - '404', - ], - - // Any extra links you want to add to the navigation menu can be added here. - // To get started quickly, you can uncomment the defaults here. - // See the documentation link above for more information. - 'custom' => [ - // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200), - ], - - // How should pages in subdirectories be displayed in the menu? - // You can choose between 'dropdown', 'flat', and 'hidden'. - 'subdirectories' => 'hidden', - ], - - - // NEW (creates an array exactly like the one above, but with a more fluent API that supports better autocomplete) - - 'navigation' => Navigation::configure() - ->setPagePriorities([ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, - ]) - ->setPageLabels([ - 'index' => 'Home', - 'docs/index' => 'Docs', - ]) - ->excludePages([ - '404', - ]) - ->addNavigationItems([ - // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), - ]) - ->setSubdirectoryDisplayMode('hidden'), - - // All of these options work in the yaml config (this is just an example, please use the same example data as above in the docs) - hyde: - navigation: - custom: - - destination: 'https://example.com' - label: 'Example' - priority: 100 - attributes: - class: 'example' - - destination: 'about' - label: 'About Us' - priority: 200 - attributes: - class: 'about' - id: 'about' - - destination: 'contact' - label: 'Contact' - priority: 300 - attributes: - target: '_blank' - rel: 'noopener noreferrer' - foo: 'bar' - - -// relevant code snippets - -|string $destination Route key, or an external URI. - * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. - * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. - * @param array $attributes Additional attributes for the navigation item. - * @return array{destination: string, label: ?string, priority: ?int, attributes: array} - */ - public static function item(string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): array - { - return compact('destination', 'label', 'priority', 'attributes'); - } - - /** - * Configuration helper method to define the navigation menu configuration with better IDE support. - * - * The builder is an array object that will be used by the framework to set the navigation menu configuration. - * - * @experimental This method is experimental and may change or be removed before the final release. - */ - public static function configure(): NavigationMenuConfigurationBuilder - { - return new NavigationMenuConfigurationBuilder(); - } -} - -|array $order - * @return $this - */ - public function setPagePriorities(array $order): static - { - $this['order'] = $order; - - return $this; - } - - /** - * Set the labels for the navigation items. - * - * Each key should be a route key, and the value should be the label to display. - * - * @param array $labels - * @return $this - */ - public function setPageLabels(array $labels): static - { - $this['labels'] = $labels; - - return $this; - } - - /** - * Exclude certain items from the navigation. - * - * Each item should be a route key for the page to exclude. - * - * @param array $exclude - * @return $this - */ - public function excludePages(array $exclude): static - { - $this['exclude'] = $exclude; - - return $this; - } - - /** - * Add custom items to the navigation. - * - * @example `[Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200, ['target' => '_blank'])]` - * - * @param array}> $custom - * @return $this - */ - public function addNavigationItems(array $custom): static - { - $this['custom'] = $custom; - - return $this; - } - - /** - * Set the display mode for pages in subdirectories. - * - * You can choose between 'dropdown', 'flat', and 'hidden'. The default is 'hidden'. - * - * @param 'dropdown'|'flat'|'hidden' $displayMode - * @return $this - */ - public function setSubdirectoryDisplayMode(string $displayMode): static - { - self::assertType(['dropdown', 'flat', 'hidden'], $displayMode); - - $this['subdirectory_display'] = $displayMode; - - return $this; - } - - /** - * Hide pages in subdirectories from the navigation. - * - * @experimental This method is experimental and may change or be removed before the final release. - * - * @return $this - */ - public function hideSubdirectoriesFromNavigation(): static - { - return $this->setSubdirectoryDisplayMode('hidden'); - } - - /** - * Get the instance as an array. - * - * @return array{order: array, labels: array, exclude: array, custom: array}>, subdirectory_display: string} - */ - public function toArray(): array - { - return $this->getArrayCopy(); - } - - /** @experimental May be moved to a separate helper class in the future. */ - protected static function assertType(array $types, string $value): void - { - if (! in_array($value, $types)) { - throw new TypeError('Value must be one of: '.implode(', ', $types)); - } - } -} - - -// The docs config has not been updated to use the builder api - - /* - |-------------------------------------------------------------------------- - | Sidebar Settings - |-------------------------------------------------------------------------- - | - | The Hyde Documentation Module comes with a fancy Sidebar that is - | automatically populated with links to your documentation pages. - | Here, you can configure its behavior, content, look and feel. - | - */ - - 'sidebar' => [ - // The title in the sidebar header - 'header' => env('SITE_NAME', 'HydePHP').' Docs', - - // When using a grouped sidebar, should the groups be collapsible? - 'collapsible' => true, - - // A string of Markdown to show in the footer. Set to `false` to disable. - 'footer' => '[Back to home page](../)', - - /* - |-------------------------------------------------------------------------- - | Sidebar Page Order - |-------------------------------------------------------------------------- - | - | In the generated Documentation pages the navigation links in the sidebar - | default to sort alphabetically. You can reorder the page identifiers - | in the list below, and the links will get sorted in that order. - | - | The items will get a priority of 500 plus the order its found in the list. - | Pages without a priority will fall back to the default priority of 999. - | - | You can also set explicit priorities in front matter or by specifying - | a value to the array key in the list to override the inferred value. - | - */ - - 'order' => [ - 'readme', - 'installation', - 'getting-started', - ], - - /* - |-------------------------------------------------------------------------- - | Table of Contents Settings - |-------------------------------------------------------------------------- - | - | The Hyde Documentation Module comes with a fancy Sidebar that, by default, - | has a Table of Contents included. Here, you can configure its behavior, - | content, look and feel. You can also disable the feature completely. - | - */ - - 'table_of_contents' => [ - 'enabled' => true, - 'min_heading_level' => 2, - 'max_heading_level' => 4, - ], - - ], \ No newline at end of file diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 36482372801..1f037908a70 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -37,156 +37,331 @@ Here's an overview of what you can customize in your navigation menus: - Item visibility: Choose to hide or show pages in the menu - Item grouping: Group pages together in dropdowns or sidebar categories -## Configuration Methods +### Customization Methods Hyde provides multiple ways to customize navigation menus to suit your needs: 1. Front matter data in Markdown and Blade page files, applicable to all menu types -2. Configuration in the `hyde.php` or `hyde.yml` config file for main navigation items -3. Configuration in the `docs.php` config file for documentation sidebar items +2. Configuration in the `hyde` config file for main navigation items +3. Configuration in the `docs` config file for documentation sidebar items -The new builder pattern in the configuration allows for a more fluent and IDE-friendly way to customize navigation. However, the old array-based method still works, as the navigation builder is an `ArrayObject` and can be used as an array. +Keep in mind that front matter data overrides dynamically inferred or config-defined priorities. While useful for quick one-off changes on small sites, it can make reordering items later on more challenging as you can't see the entire structure at once. -### Using the Navigation Builder +Additionally, general options for the entire navigation menus are also available in the `hyde` and `docs` config files. -To use the new builder pattern, you can configure your navigation in the `hyde.php` file like this: +## Front Matter Configuration -```php -use Hyde\Facades\Navigation; +Front matter options allow per-page customization of navigation menus. Here's a quick reference of available options: + +```yaml +navigation: + label: string # The displayed text in the navigation item link + priority: int # The page's priority for ordering (lower means higher up/first) + hidden: bool # Whether the page should be hidden from the navigation menu + group: string # Set main menu dropdown or sidebar group key +``` -return [ - // ... - - 'navigation' => Navigation::configure() - ->setPagePriorities([ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, - ]) - ->setPageLabels([ - 'index' => 'Home', - 'docs/index' => 'Docs', - ]) - ->excludePages([ - '404', - ]) - ->addNavigationItems([ - Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), - ]) - ->setSubdirectoryDisplayMode('hidden'), -]; -``` - -### Using YAML Configuration - -You can also set the navigation configuration in the `hyde.yml` file. The structure remains the same as the array-based method: +You only need to specify the keys you want to customize. + +### `label` + +Customizes the text appearing in the navigation menu link for the page. If not set anywhere else, Hyde will search for a title in the page content or generate one from the filename. ```yaml -hyde: - navigation: - order: - index: 0 - posts: 10 - docs/index: 100 - labels: - index: Home - docs/index: Docs - exclude: - - 404 - custom: - - destination: 'https://github.com/hydephp/hyde' - label: 'GitHub' - priority: 200 - subdirectory_display: hidden -``` - -## Customization Options +navigation: + label: "My Custom Label" +``` -Here's an overview of what you can customize in your navigation menus: +### `priority` -- Item labels: The text displayed in menu links -- Item priorities: Control the order of link appearance -- Item visibility: Choose to hide or show pages in the menu -- Item grouping: Group pages together in dropdowns or sidebar categories +Controls the order in which the page appears in the navigation menu. + +```yaml +navigation: + priority: 10 +``` + +### `hidden` + +Determines if the page appears in the navigation menu. + +```yaml +navigation: + hidden: true +``` + +**Tip:** You can also use `visible: false` to achieve the same effect. + +### `group` + +For the primary navigation menu, this groups pages together in dropdowns. For the sidebar, it groups pages under a common heading. + +```yaml +navigation: + group: "My Group" +``` + +**Note:** Sidebar group keys are normalized, so `My Group` and `my-group` are equivalent. + +## Config File Configuration + +Let's explore how to customize navigation menus using configuration files: + +- For the main navigation menu, use `navigation` setting in the `hyde.php` config file. +- For the sidebar, use `sidebar` setting in the `docs.php` config file. + +When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). + +### Changing Priorities + +The `navigation.order` and `sidebar.order` settings allow you to customize the order of pages in the navigation menus. + +#### Basic Priority Syntax + +A nice and simple way to define the order of pages, is to add their route keys as a simple list array. We'll then match that array order. + +It may be useful to know that we internally will assign a 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', // Priority: 500 + 'about', // Priority: 501 + 'contact', // Priority: 502 + ] +] +``` + +```php +// filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme', // Priority: 500 + 'installation', // Priority: 501 + 'getting-started', // Priority: 502 + ] +] +``` + +#### Explicit Priority Syntax + +You can also specify explicit priorities by adding a value to the array keys. We'll then use these exact values as the priorities. -### Setting Page Priorities +```php +// filepath: config/hyde.php +'navigation' => [ + 'order' => [ + 'home' => 10, + 'about' => 15, + 'contact' => 20, + ] +] +``` -Use the `setPagePriorities` method to define the order of pages in the navigation menu: +```php +// filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme' => 10, + 'installation' => 15, + 'getting-started' => 20, + ] +] +``` + +You could also combine these methods if desired: ```php -->setPagePriorities([ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, -]) +// filepath: Applicable to both +[ + 'readme' => 10, // Priority: 10 + 'installation', // Priority: 500 + 'getting-started', // Priority: 501 +] ``` ### Changing Menu Item Labels -Override navigation link labels using the `setPageLabels` method: +Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. + +If you're not happy with these, it's easy to override navigation link labels by mapping the route key to the desired title in the Hyde config: ```php -->setPageLabels([ - 'index' => 'Home', - 'docs/index' => 'Documentation', -]) +// filepath: config/hyde.php +'navigation' => [ + 'labels' => [ + 'index' => 'Start', + 'docs/index' => 'Documentation', + ] +] ``` -### Excluding Items +**Note:** This feature is not yet supported for the sidebar. + +### Excluding Items (Blacklist) -Prevent links from being added to the main navigation menu using the `excludePages` method: +When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. + +To exclude items from being added, simply add the page's route key to the navigation blacklist in the Hyde config: ```php -->excludePages([ - '404', -]) +// filepath: config/hyde.php +'navigation' => [ + 'exclude' => [ + '404' + ] +] ``` ### Adding Custom Navigation Menu Links -Add custom navigation menu links using the `addNavigationItems` method: +You can easily add custom navigation menu links in the Hyde config: ```php -->addNavigationItems([ - Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), -]) +// filepath: config/hyde.php +use Hyde\Facades\Navigation; + +'navigation' => [ + 'custom' => [ + Navigation::item( + destination: 'https://github.com/hydephp/hyde', // Required + label: 'GitHub', // Optional, defaults to the destination value + priority: 200 // Optional, defaults to 500 + ), + ] +] ``` +**Tip:** While named arguments are used in the example for clarity, they are not required. + + ### Configure Subdirectory Display -Set how subdirectories should be displayed in the menu using the `setSubdirectoryDisplayMode` method: +You can configure how subdirectories should be displayed in the menu: ```php -->setSubdirectoryDisplayMode('dropdown') +// filepath: config/hyde.php +'navigation' => [ + 'subdirectory_display' => 'dropdown' +] ``` -Supported options are 'dropdown', 'hidden', and 'flat'. +**Supported Options:** +- `dropdown`: Pages in subdirectories are displayed in a dropdown menu +- `hidden`: Pages in subdirectories are not displayed at all the menus +- `flat`: Pages in subdirectories are displayed as individual items -## Front Matter Configuration +### Automatic Menu Groups -Front matter options allow per-page customization of navigation menus. These options remain unchanged: +A handy feature HydePHP has is that it can automatically place pages in dropdowns based on subdirectory structures. -```yaml -navigation: - label: string # The displayed text in the navigation item link - priority: int # The page's priority for ordering (lower means higher up/first) - hidden: bool # Whether the page should be hidden from the navigation menu - group: string # Set main menu dropdown or sidebar group key +#### Automatic Navigation Menu Dropdowns + +Enable this feature in the `hyde.php` config file by setting the `subdirectory_display` key to `dropdown`. + +```php +// filepath: config/hyde.php +'navigation' => [ + 'subdirectory_display' => '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 is always enabled for documentation pages. Simply place your pages in subdirectories to have them grouped in the sidebar. + +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. + +#### Dropdown Menu Notes + +- Dropdowns take priority over standard items. If you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu. +- Example: With this file structure: `_pages/foo.md`, `_pages/foo/bar.md`, `_pages/foo/baz.md`, the link to `foo` will be lost, so please keep this in mind when using this feature. + ## Numerical Prefix Navigation Ordering -The numerical prefix navigation ordering feature remains unchanged. You can still use numerical prefixes in filenames to control the order of navigation items. +HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. -To disable this feature, you can use the following configuration: +This has the great benefit of matching the navigation menu layout with the file structure view, and works especially great with subdirectory-based navigation grouping. + +```shell +_pages/ + 01-home.md # Priority: 1 (saved to _site/index.html) + 02-about.md # Priority: 2 (saved to _site/about.html) + 03-contact.md # Priority: 3 (saved to _site/contact.html) +``` + +As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. + +### Important Notes + +1. The numerical prefix remains part of the page identifier but is stripped from the route key. + For example: `_pages/01-home.md` has route key `home` and page identifier `01-home`. +2. You can delimit the numerical prefix with either a dash or an underscore. + For example: Both `_pages/01-home.md` and `_pages/01_home.md` are valid. +3. Leading zeros are optional. `_pages/1-home.md` is equally valid. + +### Using Numerical Prefix Ordering in Subdirectories + +This feature integrates well with automatic subdirectory-based navigation grouping. Here are two useful tips: + +1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. +2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. + +Here is an example structure of how could organize a documentation site: + +```shell +_docs/ + 01-getting-started/ + 01-installation.md + 02-requirements.md + 03-configuration.md + 02-usage/ + 01-quick-start.md + 02-advanced-usage.md + 03-features/ + 01-feature-1.md + 02-feature-2.md +``` + +### Customization + +If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. ```php -return [ - // ... - 'numerical_page_ordering' => false, -]; +// filepath: config/hyde.php +'numerical_page_ordering' => false, ``` -## Conclusion +## Digging Deeper into the Internals + +While not essential, understanding the internal workings of the navigation system can be as beneficial as it's interesting. Here's a quick high-level overview of the [Navigation API](navigation-api). + +### Navigation Menu Classes + +The main navigation menu uses the `MainNavigationMenu` class, while the documentation sidebar uses the `DocumentationSidebar` class. Both extend the base `NavigationMenu` class: + +```php +use Hyde\Framework\Features\Navigation\MainNavigationMenu; +use Hyde\Framework\Features\Navigation\DocumentationSidebar; +use Hyde\Framework\Features\Navigation\NavigationMenu; +``` + +The base `NavigationMenu` class contains the main logic for menu generation, while child implementations contain extra logic for specific use cases. + +All navigation menus store items in their `$items` collection, containing instances of the `NavigationItem` class. Dropdowns are represented by `NavigationGroup` instances, which extend the `NavigationMenu` class and contain additional `NavigationItem` instances: + +```php +use Hyde\Framework\Features\Navigation\NavigationItem; +use Hyde\Framework\Features\Navigation\NavigationGroup; +``` + +## The Navigation API + +For advanced users and package developers, Hyde offers a Navigation API for programmatic interaction with site navigation. This API consists of a set of PHP classes allowing fluent interaction with navigation menus. -The new builder pattern provides a more fluent and IDE-friendly way to configure navigation in HydePHP. However, the old array-based method and YAML configuration are still supported, giving you flexibility in how you choose to customize your site's navigation. \ No newline at end of file +For more detailed information about the API, refer to the [Navigation API](navigation-api) documentation. From 3f9f9f8cfff988e7a8980a5447efce7e9127cd36 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:06:37 +0200 Subject: [PATCH 03/39] Remove hard line breaks from sections --- docs/creating-content/documentation-pages.md | 90 +++++++------------- 1 file changed, 29 insertions(+), 61 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index aed6f445be6..689e8bebdcf 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -8,23 +8,17 @@ navigation: ## Introduction to Hyde Documentation Pages -Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. -Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. +Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. -Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a -responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, -labels, and even groups, of the sidebar items to suit your needs. +Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and even groups, of the sidebar items to suit your needs. -Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated -"Docs" link will be added to your site's main navigation menu, pointing to your documentation page. +Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. -If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, -saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). +If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). ### Best Practices and Hyde Expectations -Since Hyde does a lot of things automatically, there are some things you may need -to keep in mind when creating blog posts so that you don't get unexpected results. +Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating blog posts so that you don't get unexpected results. #### Filenames @@ -78,13 +72,11 @@ navigation: ## Dynamic Content Generation -Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. -If you are not happy with the results you can customize them in the config or with front matter. +Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter. ### Front Matter reference -Before we look at how to override things, here is an overview of the relevant content Hyde generates, -and where the data is from as well as where it can be overridden. +Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden. | Property | Description | Dynamic Data Source | Override in | |---------------------------------|--------------------------------------------------------|-------------------------------------|----------------------| @@ -97,29 +89,26 @@ and where the data is from as well as where it can be overridden. ## Sidebar -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. +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) page as well to learn more about the fundamentals and terminology. +Since this feature shares a lot of similarities and implementation details with the navigation menu, I recommend you read the [navigation menu documentation](navigation) 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. -The default priority is 999. You can override the priority using the following front matter: +The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: ```yaml navigation: priority: 5 ``` -You can also change the order in the Docs configuration file. -See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
+You can also change the order in the Docs configuration file. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
_I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._ ### Sidebar labels The sidebar items are labelled with the `label` property. The default label is the filename of the file. + You can change it with the following front matter: ```yaml @@ -129,12 +118,9 @@ navigation: ### Sidebar grouping -Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. -The Hyde docs for instance use this. +Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. 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, 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. +The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set 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 @@ -185,13 +171,12 @@ This can be useful to create redirects or other items that should not be shown i ## Customization -Please see the [customization page](customization) for in-depth information on how to customize Hyde, -including the documentation pages. Here is a high level overview for quick reference though. +Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though. ### Output directory -If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, -for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. +If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. + The path is relative to the site output, typically `_site`. ```php @@ -210,8 +195,7 @@ By default, a link to the documentation page is added to the navigation menu whe ### Sidebar header name -By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". -You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. +By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. ```php 'title' => 'API Documentation', @@ -219,8 +203,7 @@ You can change this in the Docs configuration file. Tip: The header will link to ### Sidebar page order -To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. -Link items without an entry here will fall back to the default priority of 999, putting them last. +To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last. ```php 'sidebar' => [ @@ -236,9 +219,7 @@ See [the chapter in the customization page](customization#navigation-menu--sideb ### Automatic sidebar group labels -When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. -If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. -The array key is the directory name, and the value is the label. +When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label. Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself! @@ -254,8 +235,7 @@ Please note that this option is not added to the config file by default, as it's 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. +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. ```php 'sidebar' => [ @@ -269,9 +249,7 @@ You can also disable the feature completely. ### Using flattened output paths -If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. -This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. -Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. +If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. If you set this to false, Hyde will match the directory structure of the source files (just like all other pages). @@ -285,8 +263,7 @@ If you set this to false, Hyde will match the directory structure of the source ### Introduction -The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator -that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget. +The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget. >info Tip: The HydeSearch plugin is what powers the search feature on this site! Why not [try it out](search)? @@ -305,16 +282,13 @@ The search works by generating a JSON search index which the JavaScript plugin l Two ways to access the search are added, one is a full page search screen that will be saved to `docs/search.html`. -The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. -Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. +The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config. ### Hiding pages from indexing -If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. -You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how -navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. +If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. ```php // filepath: config/docs.php @@ -332,13 +306,9 @@ The Realtime Compiler that powers the `php hyde serve` command will automaticall ### Introduction -Hyde can automatically add links to documentation pages that take the user -to a GitHub page (or similar) to edit the page. This makes it great for open-source projects -looking to allow others to contribute to the documentation in a quick and easy manner. +Hyde can automatically add links to documentation pages that take the user to a GitHub page (or similar) to edit the page. This makes it great for open-source projects looking to allow others to contribute to the documentation in a quick and easy manner. -The feature is automatically enabled when you specify a base URL in the Docs configuration file. -Hyde expects this to be a GitHub path, but it will probably work with other methods as well, -if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! +The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well, if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! >info Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out! @@ -363,8 +333,7 @@ Changing the label is easy, just change the following config setting: #### Changing the position -By default, the button will be shown in both the documentation page footer. -You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` +By default, the button will be shown in both the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` ```php // Filepath: config/docs.php @@ -373,8 +342,7 @@ You can change this by setting the following config setting to `'header'`, `'foo #### Adding a button icon -This is not included out of the box, but is easy to add with some CSS! -Just target the `.edit-page-link` class. +This is not included out of the box, but is easy to add with some CSS! Just target the `.edit-page-link` class. ```css // filepath e.g. app.css From 7a85697a90b4c4fc066a5ba0ea4975fc3694234c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:07:26 +0200 Subject: [PATCH 04/39] Remove extra newlines --- docs/creating-content/documentation-pages.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 689e8bebdcf..68bf8361e8a 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -34,7 +34,6 @@ Since Hyde does a lot of things automatically, there are some things you may nee Like most of HydePHP, the Hyde Documentation module is highly customizable. Much of the frontend is composed using Blade templates and components, which you can customize to your heart's content. Since there are so many components, it's hard to list them all here in the documentation, so I encourage you to check out the [source code](https://github.com/hydephp/framework/tree/master/resources/views/components/docs) to see how it's all put together and find the customizations you are looking for. - ## Creating Documentation Pages You can create a Documentation page by adding a file to the `_docs` directory where the filename ends in `.md`. @@ -69,7 +68,6 @@ navigation: --- ``` - ## Dynamic Content Generation Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter. @@ -168,7 +166,6 @@ This can be useful to create redirects or other items that should not be shown i >info The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header.
- ## Customization Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though. @@ -258,7 +255,6 @@ If you set this to false, Hyde will match the directory structure of the source 'flattened_output_paths' => true, ``` - ## Search Feature ### Introduction @@ -301,7 +297,6 @@ If you have a large page on your documentation site, like a changelog, you may w The Realtime Compiler that powers the `php hyde serve` command will automatically generate a fresh search index each time the browser requests it. - ## Automatic "Edit Page" Button ### Introduction From 467b99191848153bf7ec4af1c1024ca7d12ec72f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:08:37 +0200 Subject: [PATCH 05/39] Cleanup line --- 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 68bf8361e8a..ce0daea81e7 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -10,7 +10,7 @@ navigation: Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. -Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and even groups, of the sidebar items to suit your needs. +Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and groups of the sidebar items to suit your needs. Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. From ac511dbb872f148b676a86c2f6d5eb521c1bab2d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:09:55 +0200 Subject: [PATCH 06/39] Shorten line --- 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 ce0daea81e7..65f708c2c8e 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -309,7 +309,7 @@ The feature is automatically enabled when you specify a base URL in the Docs con ### Configuration -As an example configuration, let's take a practical example of how HydePHP.com uses this feature. +Here's an example configuration from the official HydePHP.com documentation: ```php // Filepath: config/docs.php From accc2f7c36a0783424083ae0b877d08bea2d4da6 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 14:31:23 +0200 Subject: [PATCH 07/39] Clarify that lower priority values result in higher placement in the sidebar Matches writing style, and is more intuitive --- 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 ed64817e624..d9c498e01a9 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -93,7 +93,7 @@ Since this feature shares a lot of similarities and implementation details with ### Sidebar ordering -The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: +The sidebar is sorted/ordered by the `priority` property. The lower the priority value, the higher up in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: ```yaml navigation: From cc0d2e3ef0eedf94a02e448d665eec1a8dce9f01 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 14:32:57 +0200 Subject: [PATCH 08/39] Clean up section --- docs/creating-content/documentation-pages.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index d9c498e01a9..c3aa6d2f3d3 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -100,8 +100,7 @@ navigation: priority: 5 ``` -You can also change the order in the Docs configuration file. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
-_I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._ +You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. ### Sidebar labels From 0df917bd7eed259c1797cd1f9960bdfaf68e54a9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 14:34:50 +0200 Subject: [PATCH 09/39] Reformat table --- docs/creating-content/documentation-pages.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index c3aa6d2f3d3..8e98b4722ce 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -77,13 +77,13 @@ Hyde makes documentation pages easy to create by automatically generating dynami Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden. -| Property | Description | Dynamic Data Source | Override in | -|---------------------------------|--------------------------------------------------------|-------------------------------------|----------------------| -| `title` (string) | The title of the page used in the HTML `` tag | The first H1 heading (`# Foo`) | Front matter | -| `navigation.label` (string) | The label for the page shown in the sidebar | The page basename | Front matter, config | -| `navigation.priority` (integer) | The priority of the page used for ordering the sidebar | Defaults to 999 | Front matter, config | -| `navigation.hidden` (boolean) | Hides the page from the sidebar | _none_ | Front matter, config | -| `navigation.group` (string) | The group the page belongs to in the sidebar | Subdirectory, if nested | Front matter | +| Property | Description | Dynamic Data Source | Override in | +|---------------------------------|--------------------------------------------------------|--------------------------------|----------------------| +| `title` (string) | The title of the page used in the HTML `<title>` tag | The first H1 heading (`# Foo`) | Front matter | +| `navigation.label` (string) | The label for the page shown in the sidebar | The page basename | Front matter, config | +| `navigation.priority` (integer) | The priority of the page used for ordering the sidebar | Defaults to 999 | Front matter, config | +| `navigation.hidden` (boolean) | Hides the page from the sidebar | _none_ | Front matter, config | +| `navigation.group` (string) | The group the page belongs to in the sidebar | Subdirectory, if nested | Front matter | ## Sidebar From ab46ba42448864011e1a540aca972f13178f7891 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:35:16 +0200 Subject: [PATCH 10/39] Clarify that label is generated not literal --- 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 8e98b4722ce..6c1844014cb 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -104,7 +104,7 @@ You can also change the order in the `config/docs.php` configuration file, which ### Sidebar labels -The sidebar items are labelled with the `label` property. The default label is the filename of the file. +The sidebar items are labelled with the `label` property. The default label is generated from the filename of the file. You can change it with the following front matter: From ad504acffba78e30e05e835eb5e9153274c66176 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:39:41 +0200 Subject: [PATCH 11/39] Improve grouping documentation wording --- docs/creating-content/documentation-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 6c1844014cb..b1e75ad3bf2 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -115,9 +115,8 @@ navigation: ### Sidebar grouping -Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. The Hyde docs for instance use this. +Sidebar grouping allows you to group items in the sidebar under category headings. This is useful for creating a sidebar with a lot of items. The official HydePHP.com docs, for instance, use this feature. -The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set 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 @@ -132,6 +131,7 @@ The sidebar footer contains, by default, a link to your site homepage. You can c ``` You can also set the option to `false` to disable it entirely. +The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when documentation pages are organized in subdirectories. Once activated, Hyde will switch to a slightly more compact sidebar layout with pages sorted into labeled groups. Any pages without the group information will be put in the "Other" group. #### Using Front Matter From 5aa2fa59a06fbf9f6f2ed0fd29475d02aa449550 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:40:44 +0200 Subject: [PATCH 12/39] Fix wrong term used for sidebars --- 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 b1e75ad3bf2..2b9d87d78db 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -150,7 +150,7 @@ 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. +>info Tip: When using subdirectory-based grouping, you can set their priority using the directory name as the array key. ### Hiding items From cff03ac0513db462bf7ce087b44d2455e0996c25 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:41:07 +0200 Subject: [PATCH 13/39] Improve wording to be clearer --- 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 2b9d87d78db..bb6b10d5af6 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -150,7 +150,7 @@ 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 grouping, you can set their priority using the directory name as the array key. +>info Tip: When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file. ### Hiding items From c3fe8fb30ec3490acaa9bc820ab119c2c24ad1f9 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:41:40 +0200 Subject: [PATCH 14/39] Remove unnecessary line break --- 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 bb6b10d5af6..6d94081a09c 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -163,7 +163,7 @@ navigation: This can be useful to create redirects or other items that should not be shown in the sidebar. ->info The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header. <br> +>info The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header. ## Customization From 9a2b2ef92c0a75327f0b3a218f8f0fa8799e7223 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:43:13 +0200 Subject: [PATCH 15/39] Fix punctuation --- 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 6d94081a09c..429c52fdf02 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -146,7 +146,7 @@ navigation: You can also automatically group your documentation pages by placing source files in sub-directories. -For example, putting a Markdown file in `_docs/getting-started/`, is equivalent to adding the same front matter seen above. +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. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. From a7c6f8fd872a714df24de5fd084b57fbef99f2fe Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:43:23 +0200 Subject: [PATCH 16/39] Clarify wording --- 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 429c52fdf02..a41b0051a9d 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -148,7 +148,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. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. +>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 would overwrite each other. >info Tip: When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file. From 87eec33dc43d08702dc59e04fe7e7159e7dcc04e Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:43:59 +0200 Subject: [PATCH 17/39] Fix section order --- docs/creating-content/documentation-pages.md | 28 ++++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index a41b0051a9d..9781b605969 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -117,20 +117,6 @@ navigation: Sidebar grouping allows you to group items in the sidebar under category headings. This is useful for creating a sidebar with a lot of items. The official HydePHP.com docs, for instance, use this feature. - -### Sidebar footer customization - -The sidebar footer contains, by default, a link to your site homepage. You can change this in the `config/docs.php` file. - -```php -// filepath: config/docs.php - -'sidebar' => [ - 'footer' => 'My **Markdown** Footer Text', -], -``` - -You can also set the option to `false` to disable it entirely. The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when documentation pages are organized in subdirectories. Once activated, Hyde will switch to a slightly more compact sidebar layout with pages sorted into labeled groups. Any pages without the group information will be put in the "Other" group. #### Using Front Matter @@ -197,6 +183,20 @@ By default, the site title shown in the sidebar header is generated from the con 'title' => 'API Documentation', ``` +### Sidebar footer customization + +The sidebar footer contains, by default, a link to your site homepage. You can change this in the `config/docs.php` file. + +```php +// filepath: config/docs.php + +'sidebar' => [ + 'footer' => 'My **Markdown** Footer Text', +], +``` + +You can also set the option to `false` to disable it entirely. + ### Sidebar page order To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last. From 3fb32ab31fec7aaa72f81059d121613ef121de99 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:50:30 +0200 Subject: [PATCH 18/39] Fix inline code formatting --- docs/creating-content/documentation-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 9781b605969..4e93ca87311 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -8,13 +8,13 @@ navigation: ## Introduction to Hyde Documentation Pages -Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. +Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the `_docs/` directory, and Hyde takes care of the rest. Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and groups of the sidebar items to suit your needs. Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. -If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). +If you have a Torchlight API token in your `.env` file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). ### Best Practices and Hyde Expectations From 79ef5b2c65fc3a83f592089c20d03dd29852bb94 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:50:42 +0200 Subject: [PATCH 19/39] Fix wrong page type name --- 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 4e93ca87311..d346b4b5356 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -18,7 +18,7 @@ If you have a Torchlight API token in your `.env` file, Hyde will even enable sy ### Best Practices and Hyde Expectations -Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating blog posts so that you don't get unexpected results. +Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating documentation pages so that you don't get unexpected results. #### Filenames From 591ae52148af9ef461f228b86f721a44a1308eea Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:57:29 +0200 Subject: [PATCH 20/39] Fix grammar --- 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 d346b4b5356..14b6931f2dd 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -12,7 +12,7 @@ Welcome to the Hyde Documentation Pages, where creating professional-looking doc Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and groups of the sidebar items to suit your needs. -Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. +Additionally, if you have an `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. If you have a Torchlight API token in your `.env` file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). From 3d3932d004744b8e94a1ba1de43c2323f2839331 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:26:48 +0200 Subject: [PATCH 21/39] Remove word that isn't to be there --- 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 3b32dec349a..708ed7e3d42 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -327,7 +327,7 @@ Changing the label is easy, just change the following config setting: #### Changing the position -By default, the button will be shown in both the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` +By default, the button will be shown in the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` ```php // Filepath: config/docs.php From 3f5a4dd3a74aceb80955a32fa83db4a153268afb Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:27:07 +0200 Subject: [PATCH 22/39] Add missing important word --- 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 708ed7e3d42..362dce28406 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -283,7 +283,7 @@ The second method is a button added to the documentation pages, similar to how A ### Hiding pages from indexing -If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. +If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will not be added to the search index JSON file. ```php // filepath: config/docs.php From 4b5c86de32cb0b79fb52b4491545a71f3224b443 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:27:13 +0200 Subject: [PATCH 23/39] Use American English --- 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 362dce28406..7c809614f51 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -277,7 +277,7 @@ The search works by generating a JSON search index which the JavaScript plugin l Two ways to access the search are added, one is a full page search screen that will be saved to `docs/search.html`. -The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. +The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialog using the keyboard shortcut `/`. >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config. From f3c494e0a92818506fefb3e6c777f00a69485a74 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:27:36 +0200 Subject: [PATCH 24/39] Split out subordinate clause to separate sentence --- 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 7c809614f51..1c566e85cd0 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -302,7 +302,7 @@ The Realtime Compiler that powers the `php hyde serve` command will automaticall Hyde can automatically add links to documentation pages that take the user to a GitHub page (or similar) to edit the page. This makes it great for open-source projects looking to allow others to contribute to the documentation in a quick and easy manner. -The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well, if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! +The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well. If not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! >info Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out! From dc69f6ab6b58df53a9dd2af7469139d0499c6b3d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:28:00 +0200 Subject: [PATCH 25/39] Use APA style headings --- docs/creating-content/documentation-pages.md | 44 ++++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 1c566e85cd0..185a6539b2f 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -29,7 +29,7 @@ Since Hyde does a lot of things automatically, there are some things you may nee - You should always have an `index.md` file in the `_docs/` directory - Your page will be stored in `_site/docs/<identifier>.html` unless you [change it in the config](#output-directory) -### Advanced usage and customization +### Advanced Usage and Customization Like most of HydePHP, the Hyde Documentation module is highly customizable. Much of the frontend is composed using Blade templates and components, which you can customize to your heart's content. Since there are so many components, it's hard to list them all here in the documentation, so I encourage you to check out the [source code](https://github.com/hydephp/framework/tree/master/resources/views/components/docs) to see how it's all put together and find the customizations you are looking for. @@ -51,7 +51,7 @@ This will create the following file saved as `_docs/page-title.md` ``` -### Front Matter is optional +### Front Matter Is Optional You don't need to use [front matter](blog-posts#supported-front-matter-properties) to create a documentation page. @@ -73,7 +73,7 @@ navigation: Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter. -### Front Matter reference +### Front Matter Reference Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden. @@ -91,7 +91,7 @@ The sidebar is automatically generated from the files in the `_docs` directory. Since this feature shares a lot of similarities and implementation details with the navigation menu, I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology. -### Sidebar ordering +### Sidebar Ordering The sidebar is sorted/ordered by the `priority` property. The lower the priority value, the higher up in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: @@ -102,7 +102,7 @@ navigation: You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. -### Sidebar labels +### Sidebar Labels The sidebar items are labelled with the `label` property. The default label is generated from the filename of the file. @@ -113,7 +113,7 @@ navigation: label: "My Custom Sidebar Label" ``` -### Sidebar grouping +### Sidebar Grouping Sidebar grouping allows you to group items in the sidebar under category headings. This is useful for creating a sidebar with a lot of items. The official HydePHP.com docs, for instance, use this feature. @@ -128,7 +128,7 @@ navigation: group: "Getting Started" ``` -#### Automatic subdirectory-based grouping +#### Automatic Subdirectory-Based Grouping You can also automatically group your documentation pages by placing source files in sub-directories. @@ -155,7 +155,7 @@ This can be useful to create redirects or other items that should not be shown i Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though. -### Output directory +### Output Directory If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. @@ -171,11 +171,11 @@ The path is relative to the site output, typically `_site`. Note that you need to take care as to not set it to something that may conflict with other parts, such as media or posts directories. -### Automatic navigation menu +### Automatic Navigation Menu By default, a link to the documentation page is added to the navigation menu when an index.md file is found in the `_docs` directory. Please see [the customization page](customization#navigation-menu--sidebar) for more information. -### Sidebar header name +### Sidebar Header Name By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. @@ -183,7 +183,7 @@ By default, the site title shown in the sidebar header is generated from the con 'title' => 'API Documentation', ``` -### Sidebar footer customization +### Sidebar Footer Customization The sidebar footer contains, by default, a link to your site homepage. You can change this in the `config/docs.php` file. @@ -197,7 +197,7 @@ The sidebar footer contains, by default, a link to your site homepage. You can c You can also set the option to `false` to disable it entirely. -### Sidebar page order +### Sidebar Page Order To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last. @@ -213,7 +213,7 @@ To quickly arrange the order of items in the sidebar, you can reorder the page i See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br> -### Automatic sidebar group labels +### Automatic Sidebar Group Labels When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label. @@ -227,7 +227,7 @@ Please note that this option is not added to the config file by default, as it's ], ``` -### Table of contents settings +### Table of Contents Settings Hyde automatically generates a table of contents for the page and adds it to the sidebar. @@ -243,7 +243,7 @@ In the `config/docs.php` file you can configure the behaviour, content, and the ], ``` -### Using flattened output paths +### Using Flattened Output Paths If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. @@ -271,7 +271,7 @@ The search feature is enabled by default. You can disable it by removing the `Do ], ``` -### Using the search +### Using the Search The search works by generating a JSON search index which the JavaScript plugin loads asynchronously. @@ -281,7 +281,7 @@ The second method is a button added to the documentation pages, similar to how A >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config. -### Hiding pages from indexing +### Hiding Pages from Indexing If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will not be added to the search index JSON file. @@ -292,7 +292,7 @@ If you have a large page on your documentation site, like a changelog, you may w ] ``` -### Live search with the realtime compiler +### Live Search with the Realtime Compiler The Realtime Compiler that powers the `php hyde serve` command will automatically generate a fresh search index each time the browser requests it. @@ -316,7 +316,7 @@ Here's an example configuration from the official HydePHP.com documentation: 'source_file_location_base' => 'https://github.com/hydephp/docs/blob/master/', ``` -#### Changing the button text +#### Changing the Button Text Changing the label is easy, just change the following config setting: @@ -325,7 +325,7 @@ Changing the label is easy, just change the following config setting: 'edit_source_link_text' => 'Edit Source on GitHub', ``` -#### Changing the position +#### Changing the Position By default, the button will be shown in the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` @@ -334,7 +334,7 @@ By default, the button will be shown in the documentation page footer. You can c 'edit_source_link_position' => 'header', ``` -#### Adding a button icon +#### Adding a Button Icon This is not included out of the box, but is easy to add with some CSS! Just target the `.edit-page-link` class. @@ -343,6 +343,6 @@ This is not included out of the box, but is easy to add with some CSS! Just targ .edit-page-link::before {content: "✏ "} ``` -#### Changing the Blade view +#### Changing the Blade View You can also publish the `edit-source-button.blade.php` view and change it to your liking. From 7021d23d5e65507b6513456f63feaef27e5fc93c Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:34:46 +0200 Subject: [PATCH 26/39] Fix clarity --- 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 e9ae8e50818..04832cdb3b9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -107,8 +107,8 @@ navigation: Let's explore how to customize navigation menus using configuration files: -- For the main navigation menu, use `navigation` setting in the `hyde.php` config file. -- For the sidebar, use `sidebar` setting in the `docs.php` config file. +- For the main navigation menu, use the `navigation` setting in the `hyde.php` config file. +- For the sidebar, use the `sidebar` setting in the `docs.php` config file. When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). From 1eb578ce29a1de6d03b703464b5b5a774afb09d1 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:34:59 +0200 Subject: [PATCH 27/39] Fix title formatting --- 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 04832cdb3b9..a25c4329b8f 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -181,7 +181,7 @@ You could also combine these methods if desired: ] ``` -### Changing Menu item Labels +### Changing Menu Item Labels Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. From 14c5ac64e24340959210be825b763b929775f671 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:35:07 +0200 Subject: [PATCH 28/39] Use shorter synonym --- 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 a25c4329b8f..bd0cfe13260 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -201,7 +201,7 @@ If you're not happy with these, it's easy to override navigation link labels by ### Excluding Items (Blacklist) -When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. +When you have many pages, it may be useful to prevent links from being added to the main navigation menu. To exclude items from being added, simply add the page's route key to the navigation blacklist in the Hyde config: From 18fafba70484ded8328de00b272120b4698c2960 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:35:38 +0200 Subject: [PATCH 29/39] Remove comma from coupled clauses --- 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 bd0cfe13260..561281a3bac 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -20,7 +20,7 @@ This documentation will guide you through the customization process. To learn ev ### Internal Structure Overview -Internally, both navigation menu types extend the same base class, and thus share core functionality. This means the configuration process is similar for both types, making the documentation applicable to both. +Internally, both navigation menu types extend the same base class and thus share core functionality. This means the configuration process is similar for both types, making the documentation applicable to both. For a deeper understanding of the internal workings, refer to the [Digging Deeper](#digging-deeper-into-the-internals) section. From fcc030d65aa0b115c5a19ead2683df738ba51342 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:35:49 +0200 Subject: [PATCH 30/39] Reword line to be more fluent --- 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 561281a3bac..8019adf378e 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -33,7 +33,7 @@ All navigation menu items have an internal priority value determining their orde Here's an overview of what you can customize in your navigation menus: - Item labels: The text displayed in menu links -- Item priorities: Control the order of link appearance +- Item priorities: Control the order in which links appear - Item visibility: Choose to hide or show pages in the menu - Item grouping: Group pages together in dropdowns or sidebar categories From 714e941f0d4e07b08946f025d6fa8eab954de367 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:40:46 +0200 Subject: [PATCH 31/39] Use plural wording to match other pluralized terms in sentence --- 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 8019adf378e..5772e667c58 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -183,7 +183,7 @@ You could also combine these methods if desired: ### Changing Menu Item Labels -Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. +Hyde makes a few attempts to find suitable labels for the navigation menu items to automatically create helpful titles. If you're not happy with these, it's easy to override navigation link labels by mapping the route key to the desired title in the Hyde config: From 1bea0eff74c4b698c6d3ebf0141822903d6d486a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:40:55 +0200 Subject: [PATCH 32/39] Add missing infix --- 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 5772e667c58..4f9f4407567 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -248,7 +248,7 @@ You can configure how subdirectories should be displayed in the menu: **Supported Options:** - `dropdown`: Pages in subdirectories are displayed in a dropdown menu -- `hidden`: Pages in subdirectories are not displayed at all the menus +- `hidden`: Pages in subdirectories are not displayed at all in the menus - `flat`: Pages in subdirectories are displayed as individual items ### Automatic Menu Groups From d269f6aa981fcd063d93e79057b18f14efe334c8 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:19 +0200 Subject: [PATCH 33/39] Add comma between independent clauses --- 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 4f9f4407567..1c729c6bf28 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -266,7 +266,7 @@ Enable this feature in the `hyde.php` config file by setting the `subdirectory_d ], ``` -Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". +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 From 74c4924e24c44134f00d9a5adf62102cc64b070e Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:27 +0200 Subject: [PATCH 34/39] Fix typo should be a comma --- 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 1c729c6bf28..cad3ff23fd3 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -294,7 +294,7 @@ _pages/ 03-contact.md # Priority: 3 (saved to _site/contact.html) ``` -As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. +As you can see, Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. ### Important Notes From c00ab1b394d3337b43eb687ba1b11a968a8213c6 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:33 +0200 Subject: [PATCH 35/39] Add missing word --- 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 cad3ff23fd3..6dbfcca6c9a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -311,7 +311,7 @@ This feature integrates well with automatic subdirectory-based navigation groupi 1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. 2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. -Here is an example structure of how could organize a documentation site: +Here is an example structure of how you could organize a documentation site: ```shell _docs/ From 8129241d413a1d92d1f08e1ee6de895937a5a22d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:49 +0200 Subject: [PATCH 36/39] Remove comma from coupled clauses --- 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 6dbfcca6c9a..532c40ab24a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -118,7 +118,7 @@ The `navigation.order` and `sidebar.order` settings allow you to customize the o #### Basic Priority Syntax -A nice and simple way to define the order of pages, is to add their route keys as a simple list array. We'll then match that array order. +A nice and simple way to define the order of pages is to add their route keys as a simple list array. We'll then match that array order. It may be useful to know that we internally will assign a 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. From 312135ee71eefc64e64ab3c7dc911adc6a605e3a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:42:00 +0200 Subject: [PATCH 37/39] Change word order to be more fluent --- 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 532c40ab24a..1e8c73bce68 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -26,7 +26,7 @@ For a deeper understanding of the internal workings, refer to the [Digging Deepe ### Understanding Priorities -All navigation menu items have an internal priority value determining their order. Lower values place items higher in the menu. The default priority for pages is `999`, placing them last unless you specify a value. Some pages, like the `index` page, are by default configured with the lowest priority of `0`. +All navigation menu items have an internal priority value determining their order. Lower values place items higher in the menu. The default priority for pages is `999`, placing them last unless you specify a value. Some pages, like the `index` page, are configured by default with the lowest priority of `0`. ### Customization Options From e46b837feec20ec8673068ded7ef346e22cd158f Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:42:38 +0200 Subject: [PATCH 38/39] Split out coupled clause to standalone sentence --- 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 1e8c73bce68..b79b2f39478 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -285,7 +285,7 @@ For example: `_docs/getting-started/installation.md` will be placed in a group c HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. -This has the great benefit of matching the navigation menu layout with the file structure view, and works especially great with subdirectory-based navigation grouping. +This has the great benefit of matching the navigation menu layout with the file structure view. It also works especially well with subdirectory-based navigation grouping. ```shell _pages/ From a5df67f53181ebc8277d9f25fa9e675a19a0c08a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:42:54 +0200 Subject: [PATCH 39/39] Reword to pluralize feature in introduction --- 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 b79b2f39478..95e926b45c9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -8,7 +8,7 @@ navigation: ## Introduction -HydePHP offers an automatic navigation menu and documentation sidebar generation feature, designed to take the pain out of creating navigation menus. +HydePHP offers automatic navigation menu and documentation sidebar generation features, designed to take the pain out of creating navigation menus. While Hyde does its best to configure these menus automatically based on understanding your project files, you may want to customize them further. There are two types of navigation menus in Hyde: