Merge pull request #44 from hydephp/upcoming

Upcoming documentation
hydephp · Dec 11, 2023 · e6d86df · e6d86df
2 parents a70e5bd + ad1126f
commit e6d86df
Show file tree

Hide file tree

Showing 7 changed files with 265 additions and 95 deletions.
diff --git a/_docs/architecture-concepts/architecture-concepts.md b/_docs/architecture-concepts/architecture-concepts.md
@@ -8,7 +8,7 @@ navigation:
 
 ## Introduction
 
-These chapters are written for power users and contributors. If you're just looking to get a site up and running,
+These chapters are written for power users and package contributors. If you're just looking to get a site up and running,
 you can safely skip this section. The documentation here will cover advanced topics under the presumption that
 the reader has a basic to intermediate understanding of programming, as well as PHP, object-oriented design,
 and to some extent Laravel, as the articles are heavily driven by code examples.

diff --git a/_docs/creating-content/documentation-pages.md b/_docs/creating-content/documentation-pages.md
@@ -140,6 +140,20 @@ The feature is enabled automatically when one or more of your documentation page
 in the front matter. 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
+
+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.
+
 #### Using Front Matter
 
 To enable sidebar grouping, you can add the following front matter to your documentation pages:
@@ -199,14 +213,12 @@ By default, a link to the documentation page is added to the navigation menu whe
 ### Sidebar header name
 
 By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs".
-You can change this in the Docs configuration file.
+You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists.
 
 ```php
 'title' => 'API Documentation',
 ```
 
->info Tip: The header will link to the docs/index page, if it exists.
-
 ### Sidebar page order
 
 To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order.
@@ -222,6 +234,22 @@ Link items without an entry here will have fall back to the default priority of
 
 See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br>
 
+### Automatic sidebar group labels
+
+When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names.
+If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file.
+The array key is the directory name, and the value is the label.
+
+Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself!
+
+```php
+// Filepath: config/docs.php
+
+'sidebar_group_labels' => [
+    'questions-and-answers' => 'Questions & Answers',
+],
+```
+
 ### Table of contents settings
 
 In the `config/docs.php` file you can configure the behavior, content, and the look and feel of the sidebar table of contents.
@@ -296,6 +324,7 @@ navigation menu items are hidden. The page will still be accessible as normal bu
 
 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

diff --git a/_docs/digging-deeper/customization.md b/_docs/digging-deeper/customization.md
@@ -56,7 +56,7 @@ In some cases, the same options can be set in the front matter of a page or in a
 ### A note on file paths
 
 When Hyde references files, especially when passing filenames between components, the file path is almost always
-relative to the root of the project. Specifying absolute paths yourself will likely lead to unforeseen problems.
+relative to the root of the project. Specifying absolute paths yourself could lead to unforeseen problems.
 
 
 ## Configuration Files Overview
@@ -202,57 +202,65 @@ If you don't want to have a footer on your site, you can set the `'footer'` conf
 
 ### Navigation Menu & Sidebar
 
-One of my favourite features with Hyde is its automatic navigation menu and documentation sidebar generator.
+A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation.
+Hyde is designed to automatically configure these menus for you based on the content you have in your project.
 
-#### How it works:
+Still, you will likely want to customize some parts of these menus, and thankfully, Hyde makes it easy to do so.
 
-The sidebar works by creating a list of all the documentation pages.
+#### Customizing the navigation menu
 
-The navigation menu is a bit more sophisticated, it adds all the top-level Blade and Markdown pages.
-It also adds an automatic link to the docs if there is an `index.md` in the `_docs` directory.
+- To customize the navigation menu, use the setting `navigation.order` in the `hyde.php` config.
+- When customizing the navigation menu, you should use the [route key](core-concepts#route-keys) of the page.
 
-#### Reordering Sidebar Items
+Learn more in the [Navigation Menu](navigation-menus) documentation.
 
-Sadly, Hyde is not intelligent enough to determine what order items should be in (blame Dr Jekyll for this),
-so you will probably want to set a custom order.
+#### Customizing the documentation sidebar
 
-Reordering items in the documentation sidebar is as easy as can be. In the `docs` config, there is an array just for this.
-If a page identifier is found here it will get priority calculated according to its position in the list,
-plus an offset of 500. This offset allows you to pages earlier in the list using front matter.
+- To customize the sidebar, use the setting `sidebar_order` in the `docs.php` config.
+- When customizing the sidebar, can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page.
 
-If a page does not exist in the list they get priority 999, which puts them last.
-You can also use front matter to set a priority for a page.
-The front matter value will always take precedence.
+Learn more in the [Documentation Pages](documentation-pages) documentation.
 
-Let's see an example:
+>info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key.
+
+### Primer on priorities
+
+All navigation menu items have an internal priority value that determines its order in the navigation.
+Lower values means that the item will be higher up in the menu. The default for pages is `999` which puts them last.
+However, some pages are autoconfigured to have a lower priority, for example, the `index` page defaults to a priority of `0`,
+
+#### Basic syntax for changing the priorities
+
+The cleanest way is to use the list-style syntax where each item will get the priority calculated according to its position in the list, plus an offset of `500`.
+The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings.
 
 ```php
-// filepath: config/docs.php
-// These are the default values in the config. It puts the readme.md first in order.
-'sidebar_order' => [
-    'readme', // This is the first entry, so it gets the priority 500 + 0
-    'installation', // This gets priority 500 + 1
-    'getting-started', // And this gets priority 500 + 2
-    // Any other pages not listed will get priority 999
+[
+    'readme', // Gets priority 500
+    'installation', // Gets priority 501
+    'getting-started', // Gets priority 502
 ]
 ```
 
-#### Reordering Navigation Menu Items
+#### Explicit syntax for changing the priorities
+
+You can also specify explicit priorities by adding a value to the array key:
 
-As Hyde makes an effort to organize the menu items in a sensible way, your project comes preconfigured to put what it thinks are your most
-important pages first. This may of course not always match what you want, so thankfully it's easy to reorder the menu items!
+```php
+[
+    'readme' => 10, // Gets priority 10
+    'installation' => 15, // Gets priority 15
+    'getting-started' => 20, // Gets priority 20
+]
+```
 
-Simply update the `navigation.order` array in the Hyde config! The priorities set will determine the order of the menu items.
-Lower values are higher in the menu, and any pages not listed will get priority 999, which puts them last.
+You can also combine these options if you want:
 
 ```php
-// filepath config/hyde.php
-'navigation' => [
-    'order' => [
-        'index' => 0, // _pages/index.md (or .blade.php)
-        'posts' => 10, // _pages/posts.md (or .blade.php)
-        'docs/index' => 100, // _docs/index.md
-    ]
+[
+    'readme' => 10, // Gets priority 10
+    'installation', // Gets priority 500
+    'getting-started', // Gets priority 501
 ]
 ```
 
@@ -263,43 +271,36 @@ It's up to you which method you prefer to use. This setting can be used both for
 ```markdown
 ---
 navigation:
-    priority: 10
+    priority: 25
 ---
 ```
 
->info Tip: If you are using automatic subdirectory dropdowns, you can also set their priority in the config. Just use the directory name instead of the page identifier.
-
-#### Adding Custom Navigation Menu Links
+#### Changing the menu item labels
 
-You can easily add custom navigation menu links similar how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array.
+Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles.
+You can override the label using the `navigation.label` front matter property.
 
-When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the
-destination and label, both required. Third argument is the priority, which is optional, and defaults to 500.
+From the Hyde config you can also override the label of navigation links using the by mapping the route key
+to the desired title. Note that the front matter property will take precedence over the config property.
 
 ```php
 // filepath config/hyde.php
-use Hyde\Framework\Features\Navigation\NavItem;
-
 'navigation' => [
-    'custom' => [
-        NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
+    'labels' => [
+        'index' => 'Start',
+        'docs/index' => 'Documentation',
     ]
 ]
 ```
 
-Simplified, this will then be rendered as follows:
-
-```html
-<a href="https://github.com/hydephp/hyde">GitHub</a>
-```
-
 #### Excluding Items (Blacklist)
 
 Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu.
 To remove items from being automatically added, simply add the page's route key to the blacklist.
 As you can see, the `404` page has already been filled in for you.
 
 ```php
+// filepath config/hyde.php
 'navigation' => [
     'exclude' => [
         '404'
@@ -314,26 +315,54 @@ You can also specify that a page should be excluded by setting the page front ma
 navigation:
     hidden: true
 ---
-```
 
-#### Changing the menu item labels
+#### Adding Custom Navigation Menu Links
 
-Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles.
-You can override the label using the `navigation.label` front matter property.
+You can easily add custom navigation menu links similar how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array.
 
-From the Hyde config you can also override the label of navigation links using the by mapping the route key
-to the desired title. Note that the front matter property will take precedence over the config property.
+When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the
+destination and label, both required. Third argument is the priority, which is optional, and defaults to 500.
 
 ```php
 // filepath config/hyde.php
+use Hyde\Framework\Features\Navigation\NavItem;
+
 'navigation' => [
-    'labels' => [
-        'index' => 'Start',
-        'docs/index' => 'Documentation',
+    'custom' => [
+        NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
     ]
 ]
 ```
 
+Simplified, this will then be rendered as follows:
+
+```html
+<a href="https://github.com/hydephp/hyde">GitHub</a>
+```
+
+#### Automatic navigation menu dropdowns 
+
+HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories.
+
+For pages that can be in the main site menu, ths feature needs to be enabled in the `hyde.php` config file.
+
+```php
+// filepath config/hyde.php
+
+'navigation' => [
+    'subdirectories' => 'dropdown',
+],
+```
+
+Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About".
+
+#### Automatic documentation sidebar grouping
+
+This feature works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups. 
+This feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped.
+
+For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started".
+
 
 ## Blade Views
 
@@ -348,14 +377,12 @@ php hyde publish:views
 
 The files will then be available in the `resources/views/vendor/hyde` directory.
 
-
 ## Frontend Styles
 
 Hyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template
 for you to get up and running quickly. If you want to customize these, you are free to do so.
 Please see the [Managing Assets](managing-assets) page to learn more.
 
-
 ## Markdown Configuration
 
 Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML, and
@@ -418,7 +445,6 @@ arbitrary PHP code specified in Markdown to be executed. It's easy to enable how
 
 See the [Blade in Markdown](advanced-markdown#blade-support) documentation for more information on how to use this feature.
 
-
 ## YAML Configuration
 
 The settings in the `config/hyde.php` file can also be set by using a `hyde.yml` file in the root of your project directory.

diff --git a/_docs/digging-deeper/troubleshooting.md b/_docs/digging-deeper/troubleshooting.md
@@ -90,6 +90,7 @@ You can read more about some of these in the [Core Concepts](core-concepts#paths
 | RSS feed not being generated                       | The RSS feed requires that you have set a site URL in the Hyde config or the `.env` file. Also check that you have blog posts, and that they are enabled. | Check your configuration files.                                                                                                                                                                   |                                                                                                                                                         |
 | Sitemap not being generated                        | The sitemap requires that you have set a site URL in the Hyde config or the `.env` file.                                                                  | Check your configuration files.                                                                                                                                                                   |                                                                                                                                                         |
 | Unable to do literally anything                    | If everything is broken, you may be missing a Composer package or your configuration files could be messed up.                                            | Run `composer install` and/or `composer update`. If you can run HydeCLI commands, update your configs with `php hyde publish:configs`, or copy them manually from GitHub or the vendor directory. |
+| Namespaced Yaml config (``hyde.yml) not working    | When using namedspaced Yaml configuration, you must begin the file with `hyde:`, even if you just want to use another file for example `docs:`.           | Make sure the file starts with `hyde:` (You don't need to specify any options, as long as it's present). See [`#1475`](https://github.com/hydephp/develop/issues/1475)                            |
 
 ### Extra troubleshooting information
 

diff --git a/_docs/extensions/extensions.md b/_docs/extensions/extensions.md
@@ -0,0 +1,35 @@
+---
+navigation:
+    label: "Extensions & Integrations"
+    priority: 80
+---
+
+# Extensions & Integrations
+
+## HydePHP - Extensible by design
+
+HydePHP is designed to be extensible, and comes with a number of built-in extensions and integrations,
+as well as support for third-party extensions and integrations.
+
+
+## First party extensions & integrations
+
+### Realtime Compiler
+
+The Hyde Realtime Compiler is included with Hyde installations and is what powers the `php hyde serve` command.
+- Learn more about the [Realtime Compiler](realtime-compiler) in the documentation.
+
+
+## Integrations with third-party tools
+
+### Torchlight
+
+Torchlight is an amazing API for syntax highlighting, and is supported natively by HydePHP.
+- Learn more about [Torchlight](third-party-integrations#torchlight) in the documentation.
+
+
+## Contribute
+
+Have an idea for an extension or integration? Let me know! I'd love to hear from you. Get in touch on
+[GitHub](https://github.com/hydephp/hyde) or send me a DM on [Twitter](https://twitter.com/CodeWithCaen).
+You may also want to look at the [Extension API](extensions-api) documentation to learn how to create extensions.