From bf423082080a003b196c2e0723ac07168de85e33 Mon Sep 17 00:00:00 2001 From: caendesilva Date: Thu, 8 Feb 2024 21:32:14 +0000 Subject: [PATCH] Upload documentation preview for PR 1540 --- pr-1540/dev-docs-preview/README.html | 4 +- .../advanced-customization.html | 4 +- .../dev-docs-preview/advanced-features.html | 4 +- .../dev-docs-preview/advanced-markdown.html | 4 +- .../architecture-concepts.html | 4 +- pr-1540/dev-docs-preview/autodiscovery.html | 4 +- .../dev-docs-preview/automatic-routing.html | 4 +- pr-1540/dev-docs-preview/blog-posts.html | 4 +- pr-1540/dev-docs-preview/build-tasks.html | 4 +- pr-1540/dev-docs-preview/collections.html | 4 +- .../dev-docs-preview/compile-and-deploy.html | 4 +- .../dev-docs-preview/console-commands.html | 4 +- pr-1540/dev-docs-preview/core-concepts.html | 4 +- pr-1540/dev-docs-preview/customization.html | 6 +- .../dev-docs-preview/directory-structure.html | 4 +- .../dev-docs-preview/documentation-pages.html | 4 +- .../dynamic-data-discovery.html | 4 +- pr-1540/dev-docs-preview/extensions-api.html | 4 +- pr-1540/dev-docs-preview/extensions.html | 4 +- pr-1540/dev-docs-preview/front-matter.html | 4 +- pr-1540/dev-docs-preview/getting-started.html | 4 +- pr-1540/dev-docs-preview/hyde-pages.html | 4 +- pr-1540/dev-docs-preview/in-memory-pages.html | 4 +- pr-1540/dev-docs-preview/index.html | 4 +- pr-1540/dev-docs-preview/installation.html | 4 +- pr-1540/dev-docs-preview/managing-assets.html | 4 +- pr-1540/dev-docs-preview/navigation.html | 73 +++++++++++++++++-- pr-1540/dev-docs-preview/page-models.html | 4 +- pr-1540/dev-docs-preview/quickstart.html | 4 +- .../dev-docs-preview/realtime-compiler.html | 4 +- pr-1540/dev-docs-preview/search.html | 4 +- pr-1540/dev-docs-preview/search.json | 2 +- pr-1540/dev-docs-preview/static-pages.html | 4 +- pr-1540/dev-docs-preview/the-hydekernel.html | 4 +- .../third-party-integrations.html | 4 +- pr-1540/dev-docs-preview/troubleshooting.html | 4 +- pr-1540/dev-docs-preview/ui-kit.html | 4 +- pr-1540/dev-docs-preview/updating-hyde.html | 4 +- 38 files changed, 139 insertions(+), 82 deletions(-) diff --git a/pr-1540/dev-docs-preview/README.html b/pr-1540/dev-docs-preview/README.html index 71616490d7e..6f6f0b15cf3 100644 --- a/pr-1540/dev-docs-preview/README.html +++ b/pr-1540/dev-docs-preview/README.html @@ -156,7 +156,7 @@

- Navigation + Navigation Menus
  • @@ -392,7 +392,7 @@

    Hyde Documentation

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/advanced-customization.html b/pr-1540/dev-docs-preview/advanced-customization.html index 660b112ff40..81e42e0a562 100644 --- a/pr-1540/dev-docs-preview/advanced-customization.html +++ b/pr-1540/dev-docs-preview/advanced-customization.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -567,7 +567,7 @@

    Custom output directory

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/advanced-features.html b/pr-1540/dev-docs-preview/advanced-features.html index 0b9cdb009ec..d8a5781bdb2 100644 --- a/pr-1540/dev-docs-preview/advanced-features.html +++ b/pr-1540/dev-docs-preview/advanced-features.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -414,7 +414,7 @@

    Table of Contents

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/advanced-markdown.html b/pr-1540/dev-docs-preview/advanced-markdown.html index fc17bf44669..78684fd4906 100644 --- a/pr-1540/dev-docs-preview/advanced-markdown.html +++ b/pr-1540/dev-docs-preview/advanced-markdown.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -575,7 +575,7 @@

    Tailwind Typography Prose Classes

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/architecture-concepts.html b/pr-1540/dev-docs-preview/architecture-concepts.html index fc9a3730738..710cc1012fb 100644 --- a/pr-1540/dev-docs-preview/architecture-concepts.html +++ b/pr-1540/dev-docs-preview/architecture-concepts.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -413,7 +413,7 @@

    Behind the magic

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/autodiscovery.html b/pr-1540/dev-docs-preview/autodiscovery.html index 91abfc79f1a..2e39efbb5ea 100644 --- a/pr-1540/dev-docs-preview/autodiscovery.html +++ b/pr-1540/dev-docs-preview/autodiscovery.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -513,7 +513,7 @@

    Deep dive into lazy-booting

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/automatic-routing.html b/pr-1540/dev-docs-preview/automatic-routing.html index a5fa59d1e2e..379d7f358ea 100644 --- a/pr-1540/dev-docs-preview/automatic-routing.html +++ b/pr-1540/dev-docs-preview/automatic-routing.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -450,7 +450,7 @@

    Using the x-link component

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/blog-posts.html b/pr-1540/dev-docs-preview/blog-posts.html index 5f094f06ddb..1578cf86c5c 100644 --- a/pr-1540/dev-docs-preview/blog-posts.html +++ b/pr-1540/dev-docs-preview/blog-posts.html @@ -232,7 +232,7 @@

    - Navigation + Navigation Menus

  • @@ -629,7 +629,7 @@

    Using images in posts

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/build-tasks.html b/pr-1540/dev-docs-preview/build-tasks.html index 73237a78921..6cf0e0f2045 100644 --- a/pr-1540/dev-docs-preview/build-tasks.html +++ b/pr-1540/dev-docs-preview/build-tasks.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -541,7 +541,7 @@

    Programmatic registration

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/collections.html b/pr-1540/dev-docs-preview/collections.html index fdbf1aebb15..43344c0a091 100644 --- a/pr-1540/dev-docs-preview/collections.html +++ b/pr-1540/dev-docs-preview/collections.html @@ -156,7 +156,7 @@

    - Navigation + Navigation Menus

  • @@ -630,7 +630,7 @@

    Implementing it in a Blade view

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/compile-and-deploy.html b/pr-1540/dev-docs-preview/compile-and-deploy.html index eef9a0e06ce..b5798bc1a1a 100644 --- a/pr-1540/dev-docs-preview/compile-and-deploy.html +++ b/pr-1540/dev-docs-preview/compile-and-deploy.html @@ -191,7 +191,7 @@

    - Navigation + Navigation Menus

  • @@ -480,7 +480,7 @@

    GitHub Pages - CI/CD

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/console-commands.html b/pr-1540/dev-docs-preview/console-commands.html index bd7dd9f91cd..951e5e629b6 100644 --- a/pr-1540/dev-docs-preview/console-commands.html +++ b/pr-1540/dev-docs-preview/console-commands.html @@ -254,7 +254,7 @@

    - Navigation + Navigation Menus

  • @@ -846,7 +846,7 @@

    Options

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/core-concepts.html b/pr-1540/dev-docs-preview/core-concepts.html index 91799c6f235..7b96339a737 100644 --- a/pr-1540/dev-docs-preview/core-concepts.html +++ b/pr-1540/dev-docs-preview/core-concepts.html @@ -275,7 +275,7 @@

    - Navigation + Navigation Menus

  • @@ -838,7 +838,7 @@

    Route Keys

    Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

    Back to PR diff --git a/pr-1540/dev-docs-preview/customization.html b/pr-1540/dev-docs-preview/customization.html index 3adcd02f49a..383332ff7b5 100644 --- a/pr-1540/dev-docs-preview/customization.html +++ b/pr-1540/dev-docs-preview/customization.html @@ -310,7 +310,7 @@

    - Navigation + Navigation Menus

  • @@ -611,7 +611,7 @@

    Customizing the navigation menuTo 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 of the page.
    • -

    Learn more in the Navigation Menu documentation.

    +

    Learn more in the Navigation Menu documentation.

    Customizing the documentation sidebar

    • To customize the sidebar, use the setting sidebar_order in the docs.php config.
      • @@ -919,7 +919,7 @@

      Namespaced YAML Configuration

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/directory-structure.html b/pr-1540/dev-docs-preview/directory-structure.html index e7c146204a5..7ae0922add3 100644 --- a/pr-1540/dev-docs-preview/directory-structure.html +++ b/pr-1540/dev-docs-preview/directory-structure.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus
    • @@ -393,7 +393,7 @@

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/documentation-pages.html b/pr-1540/dev-docs-preview/documentation-pages.html index a1e156ffb7c..b21fc5fd501 100644 --- a/pr-1540/dev-docs-preview/documentation-pages.html +++ b/pr-1540/dev-docs-preview/documentation-pages.html @@ -292,7 +292,7 @@

      - Navigation + Navigation Menus

    • @@ -782,7 +782,7 @@

      Changing the Blade view

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/dynamic-data-discovery.html b/pr-1540/dev-docs-preview/dynamic-data-discovery.html index 396e42b9257..07bed0fd310 100644 --- a/pr-1540/dev-docs-preview/dynamic-data-discovery.html +++ b/pr-1540/dev-docs-preview/dynamic-data-discovery.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -483,7 +483,7 @@

      Injecting the data into the page

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/extensions-api.html b/pr-1540/dev-docs-preview/extensions-api.html index b952c19fd06..eb0a281a8b8 100644 --- a/pr-1540/dev-docs-preview/extensions-api.html +++ b/pr-1540/dev-docs-preview/extensions-api.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -550,7 +550,7 @@

      Telling the world about your extension

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/extensions.html b/pr-1540/dev-docs-preview/extensions.html index d69138eedf7..3d15d34441f 100644 --- a/pr-1540/dev-docs-preview/extensions.html +++ b/pr-1540/dev-docs-preview/extensions.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -454,7 +454,7 @@

      Contribute

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/front-matter.html b/pr-1540/dev-docs-preview/front-matter.html index 09dfd689e82..bf0ee45350d 100644 --- a/pr-1540/dev-docs-preview/front-matter.html +++ b/pr-1540/dev-docs-preview/front-matter.html @@ -172,7 +172,7 @@

      - Navigation + Navigation Menus

    • @@ -454,7 +454,7 @@

      Front Matter in Blade

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/getting-started.html b/pr-1540/dev-docs-preview/getting-started.html index 24c649b6943..54d4eb2298f 100644 --- a/pr-1540/dev-docs-preview/getting-started.html +++ b/pr-1540/dev-docs-preview/getting-started.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -393,7 +393,7 @@

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/hyde-pages.html b/pr-1540/dev-docs-preview/hyde-pages.html index 5977433841b..25648761627 100644 --- a/pr-1540/dev-docs-preview/hyde-pages.html +++ b/pr-1540/dev-docs-preview/hyde-pages.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -1300,7 +1300,7 @@

      getBladeView()

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/in-memory-pages.html b/pr-1540/dev-docs-preview/in-memory-pages.html index 3598f9776ba..088b2167373 100644 --- a/pr-1540/dev-docs-preview/in-memory-pages.html +++ b/pr-1540/dev-docs-preview/in-memory-pages.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -439,7 +439,7 @@

      API Reference

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/index.html b/pr-1540/dev-docs-preview/index.html index f445e475282..38e89a1bab5 100644 --- a/pr-1540/dev-docs-preview/index.html +++ b/pr-1540/dev-docs-preview/index.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -431,7 +431,7 @@

      To learn more, head over to the quickstart page.

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/installation.html b/pr-1540/dev-docs-preview/installation.html index cf0283c04d4..44b6611b475 100644 --- a/pr-1540/dev-docs-preview/installation.html +++ b/pr-1540/dev-docs-preview/installation.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -393,7 +393,7 @@

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/managing-assets.html b/pr-1540/dev-docs-preview/managing-assets.html index b9daa31cb54..d47d9fea735 100644 --- a/pr-1540/dev-docs-preview/managing-assets.html +++ b/pr-1540/dev-docs-preview/managing-assets.html @@ -226,7 +226,7 @@

      - Navigation + Navigation Menus

    • @@ -557,7 +557,7 @@

      Setting a featured image for blog posts

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/navigation.html b/pr-1540/dev-docs-preview/navigation.html index 47e6052a5d8..5cc5f6bf528 100644 --- a/pr-1540/dev-docs-preview/navigation.html +++ b/pr-1540/dev-docs-preview/navigation.html @@ -3,13 +3,13 @@ -HydePHP Documentation Preview - Navigation +HydePHP Documentation Preview - Navigation Menus - - + + @@ -156,11 +156,25 @@

      - Navigation + Navigation Menus Table of contents - + +

    • Advanced Markdown @@ -292,10 +306,53 @@

      -

      Navigation

      +

      Navigation Menus

      - +

      Introduction

      +

      A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation. +Hyde is designed to automatically configure these menus for you based on the content you have in your project.

      +

      There are two types of navigation menus in Hyde:

      +
        +
      • +Primary Navigation Menu: This is the main navigation menu that appears on most pages of your site.
        • +
      • +Documentation Sidebar: This is a sidebar that appears on documentation pages and contains links to other documentation pages.
        • +
      +

      HydePHP automatically generates all of these menus for you based on the content of your project, +and does its best to automatically configure them in the way that you most likely want them to be.

      +

      Of course, this won't always be perfect, so thankfully Hyde makes it a breeze to customize these menus to your liking. +Keep on reading to learn how! To learn even more about the sidebars, visit the Documentation Pages documentation.

      +

      Quick primer on the internals

      +

      It may be beneficial to understand the internal workings of the navigation menus to take full advantage of the options.

      +

      In short, both navigation menu types extend the same class (meaning they share the same base code), this means that the way +they are configured are very similar, making the documentation here applicable to both types of menus.

      +

      See the Digging Deeper section of this page if you want the full scoop on the internals!

      +

      What to customize?

      +

      Here is a quick overview of what you might want to customize in your navigation menus:

      +
        +
      • Navigation menu item labels - the text that appears in the menu links
        • +
      • Navigation menu item priority - control the order in which the links appear
        • +
      • Navigation menu item visibility - control if pages may show up in the menus
        • +
      • Navigation menu item grouping - group pages together in dropdowns
        • +
      +

      Digging deeper into the internals

      +

      While not required to know, you may find it interesting to learn more about how the navigation is handled internally. +The best way to learn about this is to look at the source code, so here is a high-level overview with details on where to look in the source code.

      +

      The main navigation menu is the NavigationMenu class, and the documentation sidebar is the DocumentationSidebar class. +Both extend the same BaseNavigationMenu class:

      +
      use Hyde\Framework\Features\Navigation\NavigationMenu;
+use Hyde\Framework\Features\Navigation\DocumentationSidebar;
+use \Hyde\Framework\Features\Navigation\BaseNavigationMenu;
+
      +

      Within the BaseNavigationMenu class, you will find the main logic for how the menus are generated, +while the child implementations contain the extra logic tailored for their specific use cases.

      +

      All the navigation menus store the menu items in their $items array containing instances of the NavItem class.

      +

      The NavItem class is a simple class that contains the label and URL of the menu item and is used to represent each item in the menu. +Dropdowns are represented by DropdownNavItem instances, which extend the NavItem class and contain an array of additional NavItem instances.

      +
      use Hyde\Framework\Features\Navigation\NavItem;
+use Hyde\Framework\Features\Navigation\DropdownNavItem;
+

    • @@ -501,7 +501,7 @@

      Page Models as Data Containers

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/quickstart.html b/pr-1540/dev-docs-preview/quickstart.html index 69d417dd4a7..c3538c5468b 100644 --- a/pr-1540/dev-docs-preview/quickstart.html +++ b/pr-1540/dev-docs-preview/quickstart.html @@ -198,7 +198,7 @@

      - Navigation + Navigation Menus

    • @@ -486,7 +486,7 @@

      Further reading

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/realtime-compiler.html b/pr-1540/dev-docs-preview/realtime-compiler.html index d39d16a10da..f59b7a4e10a 100644 --- a/pr-1540/dev-docs-preview/realtime-compiler.html +++ b/pr-1540/dev-docs-preview/realtime-compiler.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -493,7 +493,7 @@

      Source code

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/search.html b/pr-1540/dev-docs-preview/search.html index d184b10b608..572be2f7dd2 100644 --- a/pr-1540/dev-docs-preview/search.html +++ b/pr-1540/dev-docs-preview/search.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -404,7 +404,7 @@

      Search the documentation site

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/search.json b/pr-1540/dev-docs-preview/search.json index be55a5afda5..0b62828f516 100644 --- a/pr-1540/dev-docs-preview/search.json +++ b/pr-1540/dev-docs-preview/search.json @@ -1 +1 @@ -[{"slug":"README","title":"Hyde Documentation","content":"Hyde Documentation\n\nThis is the source for the HydePHP Documentation. Updates here are automatically propagated to the HydePHP.com website.\n\nThis document is not propagated to the website. It is only for the GitHub development repository.","destination":"README.html"},{"slug":"index","title":"Elegant and Powerful Static Site Generator","content":"Elegant and Powerful Static Site Generator\n\n.images-inline img { display: inline; margin: 4px 2px;}\n\nLatest Version on Packagist\nTotal Downloads on Packagist\nTest Coverage\nScrutinizer Code Quality\nPsalm Type Coverage\nLicense MIT\n{.images-inline .not-prose}\n\nAbout HydePHP\n\nHydePHP is a Static Site Generator focused on writing content, not markup. With Hyde, it is easy to create static\nwebsites, blogs, and documentation pages using Markdown and (optionally) Laravel's Blade.\n\nOperated entirely through the command-line, HydePHP provides developers with a fast and efficient way to create high-quality websites with ease.\nUnlike traditional web development frameworks, sites compiled with HydePHP don't require any server to run,\nmaking it an ideal choice for building lightweight and fast-loading websites.\n\nCompared with other static site builders, Hyde is blazingly fast and seriously simple to get started with, yet it has the\nfull power of Laravel waiting for you when you need it, as Hyde is powered by Laravel Zero, a stripped-down version of\nthe robust and popular Laravel Framework, optimized for console applications.\n\nHyde makes creating websites easy and fun by taking care of the boring stuff, like routing, writing boilerplate, and\nendless configuration. Instead, when you create a new Hyde project, everything you need to get started is already there\n-- including precompiled TailwindCSS, well-crafted Blade templates, and easy-to-use asset management.\n\nHyde was inspired by JekyllRB and is designed for developers who are comfortable writing posts in Markdown, and it requires\nvirtually no configuration out of the box as it favours convention over configuration and is preconfigured with sensible defaults.\n\nInstallation\n\nHydePHP is a command-line interface (CLI) application that is installed on a per-project basis.\n\nTo use HydePHP, your system must have PHP version 8.1 or later installed, along with Composer, and access to a terminal.\n\nThe recommended method of installation is using Composer.\n\ncomposer create-project hyde\/hyde\n\nOnce installed, you can access the HydeCLI from the project root using the hyde command.\n\nphp hyde info\n\nUsage\n\nCreating static websites with HydePHP is incredibly easy. First you need some content. You can just drop Markdown files\nin any of the source directories, or let Hyde scaffold the files for you using one of the many commands.\n\nphp hyde make:post \"My First Post\"\nphp hyde make:page \"About Me\"\n\nOnce you have some content, you can run the build command to compile the content into beautiful static HTML.\n\nphp hyde build\n\nAnd that's it, your amazing website is ready to be shared with the world!\n\nTo learn more, head over to the quickstart page.","destination":"index.html"},{"slug":"advanced-features","title":"Advanced Features in HydePHP","content":"Advanced Features in HydePHP\n\nPreface\n\nHydePHP is a simple, yet powerful, static site generator. It is designed to be easy to use and easy to extend.\n\nThis section of the documentation will cover some of the more advanced (but optional) features of the framework.\n\nPrerequisites\n\nTo fully understand the features described in these chapters, it may be beneficial to first skim through the\nArchitecture Concepts chapters, or at the very least, the Core Concepts page.\n\nYou are also expected to have a basic understanding of PHP, and object-oriented programming principles.\n\nHaving some familiarity with Laravel will also be beneficial, as HydePHP is built on top of the Laravel framework.\n\nTable of Contents\n\n[Blade]: @foreach(glob(DocumentationPage::path('advanced-features\/*.md')) as $file) {{ Hyde::makeTitle(basename($file, '.md')) }} @endforeach","destination":"advanced-features.html"},{"slug":"build-tasks","title":"Custom Build Tasks","content":"Custom Build Tasks\n\nIntroduction\n\nThe Build Task API offers a simple way to hook into the build process.\nThe build tasks are very powerful and allow for limitless customizability.\n\nThe built-in Hyde features like sitemap generation and RSS feeds are created using tasks like these.\nMaybe you want to create your own, to for example upload the site to FTP or copy the files to a public directory?\nYou can also overload the built-in tasks to customize them to your needs.\n\nGood to know before you start\n\nTypes of tasks\n\nThere are two types, PreBuildTasks and PostBuildTasks. As the names suggest, PreBuildTasks are executed before the site is built, and PostBuildTasks are executed after the site is built.\n\nTo choose which type of task you want to create, you extend either the PreBuildTask or PostBuildTask class.\nBoth of these have the exact same helpers and API available, so the only difference between them is when they are executed. The classes are otherwise identical.\n\nAbout these examples\n\nFor most of these examples we will focus on the PostBuildTasks as they are the most common.\n\nFor all these examples we assume you put the file in the App\/Actions directory, but you can put them anywhere.\n\nInteracting with output\n\nIn a way, build tasks are like micro-commands, as they can interact directly with the build commands I\/O. Please take a look at the Laravel Console Documentation for the full list of available methods.\n\nIn addition, there are some extra helpers available in the base BuildTask class that allow you to fluently format output to the console, which you will see in the examples below.\n\nCreating build tasks\n\nMinimal example\n\nHere is a minimal example to give you an idea of what we are working with.\n\nclass SimpleBuildTask extends PostBuildTask\n{\n public function handle(): void\n {\n \/\/\n }\n}\n\nAs you can see, at their core, build tasks are simple classes containing a handle() method,\nwhich as I'm sure you have guessed, is the method that is executed when the task is run by the build command.\n\nIf you want the task to run before the build, you would extend the PreBuildTask class instead.\n\nAutomatic output\n\nWhen running the build command, you will see the following output added after the build is complete.\n\n Generic build task... Done in 0.26ms\n\nAs you can see, some extra output including execution time tracking is added for us. We can of course customize all of this if we want, as you will learn a bit further down.\n\nFull example\n\nHere is a full example, with all the namespaces included, as well as the most common fluent output helpers.\n\ninfo('Hello World!');\n }\n\n public function printFinishMessage(): void\n {\n $this->line('Goodbye World!');\n }\n}\n\nYou can see a full API reference further below. But in short, the $message property is the message that runs before the task is executed, and the printFinishMessage() method is the message that runs after the task is executed.\n\nRunning this task will produce the following output:\n\n$ php hyde build\n Say hello... Hello World!\n Goodbye World!\n\nAs you can see, there is no execution time tracking here, since we overrode the printFinishMessage() method that normally prints this. You can of course call the withExecutionTime() method to add this back in. See more in the API reference below.\n\nRegistering the tasks\n\nThere are a few ways to register these tasks so Hyde can find them.\n\nThey are shown here in order of presumed convenience, but you are free to choose whichever you prefer. The latter options are more suited for extension developers.\n\nAutodiscovery registration\n\nThe easiest way to register build tasks is to not do it -- just let Hyde do it for you!\n\nAny classes that end in BuildTask.php that are stored in app\/Actions will be autoloaded and registered to run automatically.\n\nFor example: app\/Actions\/ExampleBuildTask.php.\n\nConfig file registration\n\nIf you want, you can also register build tasks of any namespace in the convenient build_tasks array which is in the main configuration file, config\/hyde.php.\n\n\/\/ filepath config\/hyde.php\n'build_tasks' => [\n \\App\\Actions\\SimpleTask::class,\n \\MyPackage\\Tasks\\MyBuildTask::class,\n],\n\nProgrammatic registration\n\ninfo This option assumes you are familiar with Laravel's service container and service providers.\n\nIf you are developing an extension, you can either instruct users register your tasks with the config option above,\nor you can register the extensions programmatically, I recommend you do this in the boot method of a service provider.\n\nThe build tasks are registered in an internal array of the BuildService class, which is bound as a singleton in the underlying Laravel service container.\nTo actually register your task, provide the fully qualified class name of the task to the BuildTaskService::registerTask() method.\n\nHere is an example of how to do this using a service provider. Though you could technically do it anywhere using the app() helper,\njust as long as it's done early enough in the application lifecycle, so it's registered before the build command is executed.\n\nclass MyServiceProvider extends ServiceProvider\n{\n public function boot(): void\n {\n $this->app->make(\\Hyde\\Framework\\Services\\BuildTaskService::class)\n ->registerTask(\\MyPackage\\Tasks\\MyBuildTask::class);\n }\n}","destination":"build-tasks.html"},{"slug":"hyde-pages","title":"HydePage API Reference","content":"# HydePage API Reference\n\nwarning This article covers advanced information, and you are expected to already be familiar with Page Models and OOP\n\n## Abstract\n\nThis page contains the full API references for the built-in HydePage classes. Most users will not need to know about\nthe inner workings of classes, but if you're interested in extending HydePHP, or just curious, this page is for you.\nIt is especially useful if you're looking to implement your own page classes, or if you are creating advanced Blade templates.\n\n### About the reference\n\nThis document is heavily based around the actual source code, as I believe the best way to understand the code is to read it.\nHowever, large parts of the code are simplified for brevity and illustration. The code is not meant to be copy-pasted, but\nrather used as a reference so that you know what to look for in the actual source code, if you want to dig deeper.\n\n#### Inheritance\n\nSince all HydePages extend the base HydePage class, those shared methods are only listed once,\nunder the HydePage class documentation which is conveniently located just below this section.\n\n### Table of Contents\n\nClass Description\n\nHydePage The base class for all Hyde pages.\nBaseMarkdownPage The base class for all Markdown pages.\nInMemoryPage Extendable class for in-memory pages.\nBladePage Class for Blade pages.\nMarkdownPage Class for Markdown pages.\nMarkdownPost Class for Markdown posts.\nDocumentationPage Class for documentation pages.\nHtmlPage Class for HTML pages.\n\n## HydePage\n\nThe base class for all Hyde pages. All other page classes extend this class.\n\nUnlike other frameworks, you generally don't instantiate pages yourself in Hyde. Instead, the page models act as\nblueprints defining information for Hyde to know how to parse a file, and what data around it should be generated.\n\nTo get a parsed file instance, you'd typically just create a source file, and you can then access the parsed file\nfrom the HydeKernel's page index.\n\nIn Blade views, you can always access the current page instance being rendered using the $page variable.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nHydePage Hyde\\Pages\\Concerns Open in GitHub Live API Docs\n\n### Base Structure\n\n\/**\n * The base class for all Hyde pages. Here simplified for the sake of brevity.\n *\/\nabstract class HydePage\n{\n \/**\n * The directory in which source files are stored. Relative to the project root.\n *\/\n public static string $sourceDirectory;\n\n \/**\n * The output subdirectory to store compiled HTML. Relative to the _site output directory.\n *\/\n public static string $outputDirectory;\n\n \/**\n * The file extension of the source files.\n *\/\n public static string $fileExtension;\n\n \/**\n * The default template to use for rendering the page.\n *\/\n public static string $template;\n\n \/**\n * The page instance identifier.\n *\/\n public readonly string $identifier;\n\n \/**\n * The page instance route key.\n *\/\n public readonly string $routeKey;\n\n \/**\n * The parsed front matter.\n *\/\n public FrontMatter $matter;\n\n \/**\n * The generated page metadata.\n *\/\n public PageMetadataBag $metadata;\n\n \/**\n * The generated page navigation data.\n *\/\n public NavigationData $navigation;\n}\n\n### Methods\n\nwarning Heads up! The following methods are defined in the HydePage class, and are thus available to all page classes. Since the HydePage class is abstract, you cannot instantiate it directly, and many of the static methods are also only callable from the child classes.\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/hyde-page-methods'))->toHtml($page::class) }}\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/interacts-with-front-matter-methods'))->toHtml($page::class) }}\n\n## BaseMarkdownPage\n\nThe base class for all Markdown-based page models, with additional helpers tailored for Markdown pages.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nBaseMarkdownPage Hyde\\Pages\\Concerns Open in GitHub Live API Docs\n\n### Base Structure\n\n\/**\n * The base class for all Markdown-based page models. Here simplified for the sake of brevity.\n *\/\nabstract class BaseMarkdownPage extends HydePage\n{\n public Markdown $markdown;\n\n public static string $fileExtension = '.md';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/base-markdown-page-methods'))->toHtml($page::class) }}\n\n## InMemoryPage\n\nBefore we take a look at the common page classes, you'll usually use, let's first take a look at one that's quite interesting.\n\nThis class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize Hyde\nautodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.\n\nYou can learn more about the InMemoryPage class in the InMemoryPage documentation.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nInMemoryPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nAs the class is not discoverable, the static path properties are not initialized. Instead, you solely rely on the contents\/view properties.\n\nYou can also define macros which allow you to both add methods to the instance, but also to overload some built-in ones like the compile method.\n\n\/**\n * The InMemoryPage class, here simplified for the sake of brevity.\n *\/\nclass InMemoryPage extends HydePage\n{\n public static string $sourceDirectory;\n public static string $outputDirectory;\n public static string $fileExtension;\n\n protected string $contents;\n protected string $view;\n\n \/* @var array \/\n protected array $macros = [];\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/in-memory-page-methods'))->toHtml($page::class) }}\n\n## BladePage\n\nPage class for Blade pages.\n\nBlade pages are stored in the _pages directory and using the .blade.php extension.\nThey will be compiled using the Laravel Blade engine the _site\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nBladePage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass BladePage extends HydePage\n{\n public static string $sourceDirectory = '_pages';\n public static string $outputDirectory = '';\n public static string $fileExtension = '.blade.php';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/blade-page-methods'))->toHtml($page::class) }}\n\n## MarkdownPage\n\nPage class for Markdown pages.\n\nMarkdown pages are stored in the _pages directory and using the .md extension.\nThe Markdown will be compiled to HTML using a minimalistic layout to the _site\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nMarkdownPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass MarkdownPage extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_pages';\n public static string $outputDirectory = '';\n public static string $template = 'hyde::layouts\/page';\n}\n\n### Methods\n\nThis class does not define any additional methods.\n\n## MarkdownPost\n\nPage class for Markdown blog posts.\n\nMarkdown posts are stored in the _posts directory and using the .md extension.\nThe Markdown will be compiled to HTML using the blog post layout to the _site\/posts\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nMarkdownPost Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_posts';\n public static string $outputDirectory = 'posts';\n public static string $template = 'hyde::layouts\/post';\n\n public ?string $description;\n public ?string $category;\n public ?DateString $date;\n public ?PostAuthor $author;\n public ?FeaturedImage $image;\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/markdown-post-methods'))->toHtml($page::class) }}\n\n## DocumentationPage\n\nPage class for documentation pages.\n\nDocumentation pages are stored in the _docs directory and using the .md extension.\nThe Markdown will be compiled to HTML using the documentation page layout to the _site\/docs\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nDocumentationPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass DocumentationPage extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_docs';\n public static string $outputDirectory = 'docs';\n public static string $template = 'hyde::layouts\/docs';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/documentation-page-methods'))->toHtml($page::class) }}\n\n## HtmlPage\n\nPage class for HTML pages.\n\nHTML pages are stored in the _pages directory and using the .html extension.\nThese pages will be copied exactly as they are to the _site\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nHtmlPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass HtmlPage extends HydePage\n{\n public static string $sourceDirectory = '_pages';\n public static string $outputDirectory = '';\n public static string $fileExtension = '.html';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/html-page-methods'))->toHtml($page::class) }}","destination":"hyde-pages.html"},{"slug":"in-memory-pages","title":"InMemoryPages","content":"InMemoryPages\n\nIntroduction\n\nThis class is a special page class that is not backed by a file on disk, but rather generated at runtime. While it will\nprobably not be useful for the majority of users, it's a great class to know about if you are a package developer,\nbut feel free to skip this section if you're not interested in this.\n\nWhen to use\n\nThis class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize Hyde\nautodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.\n\nAbout discovery\n\nSince the InMemoryPages are not present in the filesystem, they cannot be found by the auto-discovery process.\nInstead, it's up to the developer to manually register them. If you are working on your own project, you can do this in\nthe boot method of a service provider, such as the AppServiceProvider which is already present in your app\/ directory.\n\nIf you are developing a package, you may instead want to register the page in your package extension class, within the\npage collection callback. In either case, if you want your page to be able to be fully processed by Hyde, you need to\nmake sure you register it before the full application is booted so that routes can be generated.\n\nTo see how to register the page, see the examples below. But first we must look at how to actually create the page.\n\nCreating the page\n\nTo create an InMemoryPage, you need to instantiate it with the required parameters.\n\nSince a page would not be useful without any content to render, the class offers two content options through the constructor.\n\nYou can either pass a string to the $contents parameter, Hyde will then save that literally as the page's contents.\n\n$page = new InMemoryPage(contents: 'Hello World!');\n\nAlternatively, you can pass a Blade view name to the $view parameter, and Hyde will use that view to render the page\ncontents with the supplied front matter during the static site build process.\n\nwarning Note that $contents take precedence over $view, so if you pass both, only $contents will be used.\n\nYou can also register a macro with the name compile to overload the default compile method.\n\nAPI Reference\n\nTo see all the methods available, please see the InMemoryPage API reference.","destination":"in-memory-pages.html"},{"slug":"architecture-concepts","title":"Advanced Architecture Concepts","content":"Advanced Architecture Concepts\n\nIntroduction\n\nThese chapters are written for power users and package contributors. If you're just looking to get a site up and running,\nyou can safely skip this section. The documentation here will cover advanced topics under the presumption that\nthe reader has a basic to intermediate understanding of programming, as well as PHP, object-oriented design,\nand to some extent Laravel, as the articles are heavily driven by code examples.\n\nYou are of course free to skip this entire section, as you don't need to know these things to use Hyde.\nHowever, if you want to know the \"magic\" behind Hyde, or if you want to take advantage of these powerful tools,\nthen by all means, please read on! This is also a great place to start if you want to contribute to the source code.\n\ninfo For a high-level overview of these concepts, see the Basic Architecture Concepts page.\n\nBehind the magic\n\nWant to learn more about a particular feature? Click on the links below to visit the article.\n\n[\/\/]: # (This would be better suited for a component, but it's a fun experiment for now)\n[Blade]: @foreach(glob(DocumentationPage::path('architecture-concepts\/*.md')) as $file) {{ Hyde::makeTitle(basename($file, '.md')) }} @endforeach","destination":"architecture-concepts.html"},{"slug":"autodiscovery","title":"Autodiscovery","content":"Autodiscovery\n\nIntroduction\n\nHydePHP aims to reduce the amount of configuration you need to do to get a site up and running.\nTo that end, Hyde uses a process called autodiscovery to automatically find and register your pages.\n\nThis article will go into detail about how autodiscovery works as well as the lifecycle of the HydeKernel.\n\nThe short version\n\nHyde will use the information in the page model classes to scan the source directories for matching files which are\nparsed using instructions from the model's class, resulting in data used to construct objects that get stored in the HydeKernel.\n\nPrerequisites\n\nBefore reading this article, you should be familiar with the following concepts:\n- Page Models\n- The HydeKernel\n\nBooting pipeline\n\nThe autodiscovery is run when the HydeKernel boots. It does so in three distinct steps, which run in sequence as each\nstep depends on the previous one. Each discovery step runs in a FoundationCollection which both runs the actual\ndiscovery process and stores the discovered data in memory.\n\nThe steps are as follows:\n\n1. Step one: The file collection discovers all the source files and stores them in memory\n2. Step two: The page collection parses all the source files into page model objects\n3. Step three: The route collection generates route objects for all the pages\n\nInteracting with the collections\n\nUsually, you will interact with the collection data through intermediaries.\n* For example, if you call MarkdownPost::get('my-post'), Hyde will retrieve that page from the page collection.\n* If you call Routes::get('index'), Hyde will retrieve that route from the route collection.\n\nThe HydeKernel\n\nIf you have not yet read the HydeKernel Documentation, here's a quick recap:\n\nThe HydeKernel encapsulates a HydePHP project, providing helpful methods for interacting with it.\nIt is also responsible for booting the application, which includes the autodiscovery process.\n\nThe kernel is created very early on in the application lifecycle, in the bootstrap.php file, where it is also bound\nas a singleton into the application service container.\n\nAt this point you might be wondering why we're talking about the kernel when this article is about autodiscovery.\nWell, as you'll see in just a moment, the kernel is responsible for initiating the autodiscovery process.\nThe kernel is also where the discovered data is stored in memory, so it's important to understand how it works.\n\nThe kernel lifecycle\n\nNow that we know the role of the HydeKernel, let's take a look at its lifecycle. The kernel is \"lazy-booted\", meaning\nthat all the heavy lifting only happens when you actually need it. Once booted, the kernel data will stay in memory\nuntil the console application is terminated.\n\nThe kernel data is primarily stored in three collections that get generated during the kernel's boot process.\nLet's take a look at a simplified version of the kernel's boot method to see how this works.\n\npublic function boot(): void\n{\n $this->files = FileCollection::boot($this);\n $this->pages = PageCollection::boot($this);\n $this->routes = RouteCollection::boot($this);\n\n \/\/ Scroll down to see what this is used for\n $this->booted = true;\n}\n\nHere you'll see that we boot the three collections. This is where all the autodiscovery magic happens!\n\nDeep dive into lazy-booting\n\nIf you're curious about how the kernel is lazy-booted, here's how it works!\nFeel free to skip this section if this doesn't interest you.\n\n\/\/ This will boot the kernel if it hasn't been booted yet\npublic function pages(): PageCollection\n{\n $this->needsToBeBooted();\n\n return $this->pages;\n}\n\n\/\/ This is the method that triggers the boot process\nprotected function needsToBeBooted(): void\n{\n if (! $this->booted) {\n $this->boot();\n }\n}\n\nYeah, it's really unglamorous I know. But it works! Having it like this will ensure that any time you call Hyde::pages(),\nthat underlying collection will always have been booted and be ready to use.","destination":"autodiscovery.html"},{"slug":"automatic-routing","title":"Automatic Routing","content":"Automatic Routing\n\ninfo This covers an intermediate topic which is not required for basic usage, but is useful if you want to use the framework to design custom Blade templates.\n\nHigh-level overview\n\nIf you've ever worked in an MVC framework, you are probably familiar with the concept of routing.\nAnd you are probably also familiar with how boring and tedious it can be. Thankfully, Hyde takes the pain out of routing\nthrough the Hyde Autodiscovery process.\n\nInternally, when booting the HydeCLI application, Hyde will automatically discover all the content files in the source\ndirectories, and create a route index for all of them. This index works as a two-way link between source files and compiled files.\n\nDon't worry if this sounds complex, as the key takeaway is that the index is created and maintained automatically.\nNevertheless, the routing system provides several helpers that you can optionally use in your Blade views to\nautomatically resolve relative links and other useful features.\n\nYou can see all the routes and their corresponding source files by running the hyde route:list command.\n\nphp hyde route:list\n\nAccessing routes\n\nEach route in your site is represented by a Route object. It's very easy to get a Route object instance from the Router's index.\nThere are a few ways to do this, but most commonly you'll use the Routes facade's get() method where you provide a route key,\nand it will return the Route object. The route key is generally ``. Here are some examples:\n\n\/\/ Source file: _pages\/index.md\/index.blade.php\n\/\/ Compiled file: _site\/index.html\nRoutes::get('index')\n\n\/\/ Source file: _posts\/my-post.md\n\/\/ Compiled file: _site\/posts\/my-post.html\nRoutes::get('posts\/my-post')\n\n\/\/ Source file: _docs\/readme.md\n\/\/ Compiled file: _site\/docs\/readme.html\nRoutes::get('docs\/readme')\n\nUsing the x-link component\n\nWhen designing Blade layouts it can be useful to use the x-link component to automatically resolve relative links.\n\nYou can of course use it just like a normal anchor tag like so:\n\nHome\n\nBut where it really shines is when you supply a route. This will then resolve the proper relative link, and format it to use pretty URLs if your site is configured to use them.\n\nHome\n\nYou can of course, also supply extra attributes like classes:\n\nHome","destination":"automatic-routing.html"},{"slug":"dynamic-data-discovery","title":"Dynamic Data Discovery","content":"Dynamic Data Discovery\n\n[\/\/]: # (Adds a pseudo-subtitle)\nAKA: Front Matter & Filling in the Gaps\n\nIntroduction\n\nHyde wants to allow developers to write less, and do more. This is also a major difference between HydePHP and JekyllRB.\nJekyll will only do what you tell it to do. Hyde, on the other hand, will try to do what you want it to do.\n\nAs with all other chapters in this category, you don't need to know about this to use Hyde -- that's the whole point!\nHowever, if you're anything like me, you'll likely find this interesting to read about, even if you don't really need to know it.\n\nHyde makes great use of front matter in both Markdown and Blade files (it's true!). However, it can quickly get tedious\nand quite frankly plain boring to have to write a bunch of front matter all the time. As Hyde wants you to focus on\nyour content, and not your markup, front matter is optional and Hyde will try to fill in the gaps for you.\n\nIf you're not happy with Hyde's generated data you can always override it by adding front matter to your files.\n\nHow it Works\n\nNow, to the fun part: getting into the nitty-gritty details of how Hyde does this!\n\nTo make things simple the dynamic data is created in a special stage where the page object is being created.\nIf you have not yet read the page models chapter you might want to do so now.\nYou might also want to read about the autodiscovery lifecycle for some context as to when this happens.\n\nThe factory pipeline, in short\n\nAfter basic information about the page has been gathered, such as the source file information and the front matter,\nthe page model is run through a series of factories. These are just classes that work around the limited data\nthat is available at this point and will generate the rich data used to make your Hyde page awesome.\n\nThere are a few factory classes. The one we will be looking at here is the HydePageDataFactory class, which is\nresponsible for data applicable to all page models. Complex structures and data only relevant to some page types\nhave their own factories, making the code more modular and maintainable.\n\nIn-depth overview of a page factory\n\nLet's take a look at how Hyde will discover the title of a page as an example. Since this is something used by all pages,\nthis discovery is done in the HydePageDataFactory class.\n\nFactory data input\n\nThe factory gets one input, a CoreDataObject class. Think of this like a DTO (Data Transfer Object) that holds\nimmutable data known from the start of the page construction process. It also has all the information needed\nto identify the page and its source file. Here's a simplified version of the class:\n\nclass CoreDataObject\n{\n public readonly FrontMatter $matter;\n public readonly Markdown|false $markdown;\n\n public readonly string $pageClass;\n public readonly string $identifier;\n public readonly string $sourcePath;\n public readonly string $outputPath;\n public readonly string $routeKey;\n}\n\nProcessing the known data\n\nNow that we have the input we pass it to the factory, where a simple algorithm is used to find the best title for the page.\n\nprivate function findTitleForPage(): string\n{\n return $this->matter('title')\n ?? $this->findTitleFromMarkdownHeadings()\n ?? Hyde::makeTitle(basename($this->identifier));\n}\n\nAs you can see, we are using the null coalescing operator (??) to return the first non-null value. We always want the\nuser to be able to set any data explicitly, so we first check the front matter in all factory methods.\n\nIf no title is set in the matter the method will return null, and Hyde will try the next step which is to search the headings.\nIf that fails, the last step will generate a title from the file name. This ensures that no matter what, we always have a title.\n\nInjecting the data into the page\n\nOnce the data has been discovered, it is injected into the page object. This is rather unglamorous but is mentioned\nhere for completeness. It's pretty simple. The factory will always return an array of the computed data, where the keys\nalways match the property names on the page object, so we just need to loop over the array and set the properties.\n\nforeach ($data->toArray() as $key => $value) {\n $this->{$key} = $value;\n}\n\nAnd that's pretty much it! Hyde will do this for all the data it can discover, freeing you to focus on your content.","destination":"dynamic-data-discovery.html"},{"slug":"extensions-api","title":"The Extensions API","content":"The Extensions API\n\nIntroduction\n\nThe Extensions API is a powerful interface designed for package developers who want to extend the functionality of HydePHP.\n\nUsing the API, you can hook directly into the HydePHP Kernel and extend sites with custom page types and new features.\n\nThis documentation page functions heavily through examples, so it's recommended that the sections are read in order.\n\nPrerequisites\n\nBefore creating your extension, it will certainly be helpful if you first become familiar with\nthe basic internal architecture of HydePHP, as well as how the auto-discovery system works,\nso you can understand how your code works with the internals.\n\n- Core concepts overview\n- Architecture concepts\n- Autodiscovery\n\nThe why and how of the Extensions API\n\nHydePHP being a static site generator, the Extensions API is centred around Page Models,\nwhich you are hopefully already familiar with, otherwise you should read up on them first.\n\nWhat the Extensions API does is to allow you to create custom page types, and tell HydePHP how to discover them.\nThis may sound like a small thing, but it's actually incredibly powerful as the page models are the foundation\nof HydePHP's functionality. They tell the system how to discover pages, how to render them,\nand how they interact with the site.\n\nAny other functionality you want to add to HydePHP, such as new commands or configuration options,\ncan be added the same way as you would in Laravel, and are thus not part of our API.\nSee the Laravel package development guide for more.\n\nCreating your Extension class\n\nThe entry-point for your extension is your Extensions class. Within this, you can register the custom page classes.\nIf needed, you can also register discovery handlers which can run custom logic at various parts of the boot process.\n\nIn this article we will create an extension that registers a new type of page, a JsonPageExtension.\n\nThe first step is to create a class that extends the HydeExtension class:\n\nuse Hyde\\Foundation\\Concerns\\HydeExtension;\n\nclass JsonPageExtension extends HydeExtension {\n \/\/\n}\n\nIn here, we will register our extension class name in the getPageClasses method:\n\nclass JsonPageExtension extends HydeExtension {\n public static function getPageClasses(): array {\n return [\n JsonPage::class,\n ];\n }\n}\n\nHyde will then use the information from the JsonPage class to automatically discover the pages when booting the Kernel.\nFor example, if you specify the file extension and source directory, that is all Hyde needs to know to discover the pages.\n\nIf our pages need more complex discovery logic, we can create custom handlers. so let's take a quick look at that next.\n\nDiscovery handlers\n\nThe discovery handlers let you run code at various points of the booting process. This is usually only needed if your\npage models cannot provide the information required for Hyde run the standard auto-discovery, and thus need custom logic.\n\nUsually in these cases, you would only need to add files to the Kernel FileCollection,\nthough the HydeExtension class offers the following three discovery handlers, in case you need them:\n\n\/* Runs during file discovery \/\npublic function discoverFiles(FileCollection $collection): void;\n\n\/* Runs during page discovery \/\npublic function discoverPages(PageCollection $collection): void;\n\n\/* Runs during route discovery \/\npublic function discoverRoutes(RouteCollection $collection): void;\n\nAny of these can be implemented in your extension class, and they will be called during the discovery. As you can see,\nthe instance of the discovery collection is injected into the method for you to interact with.\n\nDiscovery handler example\n\nLet's go crazy and implement a discovery handler to collect JsonPage files from an external API! We will do this\nby implementing the discoverPages method in our extension class, and from there inject pages retrieved from our API.\n\nclass JsonPageExtension extends HydeExtension {\n public function discoverPages(PageCollection $collection): void {\n $pages = Http::get('https:\/\/example.com\/my-api')->collect();\n\n $pages->each(function (array $page) use ($collection): void {\n $collection->addPage(JsonPage::fromArray($page));\n });\n }\n}\n\nSince the discovery steps are handled sequentially, the added pages will automatically be discovered as routes without\nus having to implement that handler method. As we inject the page objects directly, we bypass the need for the FileCollection.\n\nRegistering your extension\n\nNow that we have our extension class, we need to register it with HydePHP.\n\nIt's important that your class is registered before the HydeKernel boots. Therefore, an excellent place for this is the\nregister method of your extensions service provider, where you call the registerExtension method of the HydeKernel\nsingleton instance, which you can access via the Hyde\\Hyde facade, or via the service container.\n\nuse Hyde\\Hyde;\nuse Hyde\\Foundation\\HydeKernel;\nuse Illuminate\\Support\\ServiceProvider;\n\nclass JsonPageExtensionServiceProvider extends ServiceProvider {\n public function register(): void {\n \/\/ Via the service container:\n $this->app->make(HydeKernel::class)->registerExtension(JsonPageExtension::class);\n\n \/\/ Or via the facade:\n Hyde::registerExtension(JsonPageExtension::class);\n }\n}\n\nPackaging your extension\n\nTo make your extension available to other HydePHP users, you can make it into a Composer package,\nand publish it to Packagist for others to install.\n\nIf you register your service provider in your package's composer.json file, your extension automatically be enabled when\nthe package is installed in a HydePHP project!\n\n{\n \"extra\": {\n \"laravel\": {\n \"providers\": [\n \"My\\\\Namespace\\\\JsonPageExtensionServiceProvider\"\n ]\n }\n }\n}\n\nTelling the world about your extension\n\nNext up, why not send us a Tweet at @HydeFramework and tell us about your extension,\nso we can feature it?","destination":"extensions-api.html"},{"slug":"page-models","title":"Page models","content":"The Hyde Page Models\n\nIntroduction\n\nThe Hyde page models are an integral part of how HydePHP creates your static site. Each page in your site is represented\nby a page model. These are simply PHP classes that in addition to holding both the source content and computed data\nfor your pages, also house instructions to Hyde on how to parse, process, and render the pages to static HTML.\n\nIn this article, you'll get a high-level overview of the page models, and some code examples to give you a look inside.\n\nThe short version\n\nPage models are classes that have two primary concerns:\n\n1. They act as blueprints containing static instructions for how to parse, process, and, render pages.\n2. Each class instance also holds the page source contents, as well as the computed data.\n\nOther key points:\n\n- HydePHP, at the time of writing, comes with five different page classes, one for each supported type.\n- You don't construct page models yourself. HydePHP does it for you by the autodiscovery process.\n- Page models are just PHP classes. You can extend them, and you can implement your own.\n\nThe Page Model\n\nTo give you an idea of what a page model class looks like, here's a simplified version of the base MarkdownPost class,\nDon't worry if you don't understand everything yet, we'll talk more about these parts later.\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_posts';\n public static string $outputDirectory = 'posts';\n public static string $fileExtension = '.md';\n public static string $template = 'post';\n\n public string $identifier;\n public string $routeKey;\n public string $title;\n\n public FrontMatter $matter;\n public Markdown $markdown;\n}\n\n_Note that since Hyde pages are modular through class inheritance and traits, this example has been simplified and\nedited to show all the relevant parts inlined into one class._\n\nPage Models as Blueprints\n\nAll page models have some static properties (that is, they belong to the class, not the instance) that are used as\nblueprints, defining information for Hyde to know how to parse a file, and what data around it should be generated.\n\nLet's again take the simplified MarkdownPost class as an example, this time only showing the static properties:\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_posts';\n public static string $outputDirectory = 'posts';\n public static string $fileExtension = '.md';\n public static string $template = 'post';\n}\n\nWhat each property does\n\nThe properties should be self-explanatory, but here's a quick rundown to give some context on how they are used,\nand how the paths relate to each other. So for the class above, Hyde will thanks to this blueprint, know to:\n* Look for files in the _posts directory, with the .md extension\n* Compile the page using the post Blade template\n* Output the compiled page to the _site\/posts directory\n\nPage Models as Data Containers\n\nAs mentioned above, each page model instance also holds the page source contents, as well as the computed data.\n\nLet's again take the simplified MarkdownPost class as an example, this time only showing the instance properties:\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public string $identifier;\n public string $routeKey;\n public string $title;\n\n public FrontMatter $matter;\n public Markdown $markdown;\n}\n\nThere are some more properties than shown here, for example, various metadata properties, but these are the most common\nand important ones.\n\nWhile the static data gives instructions to Hyde on how to process all pages of the type, the instance data tells Hyde\nhow to process a specific page. For example, the identifier property is used to uniquely identify the page, and\nthe routeKey property is used to generate the URL for the page.\n\nThe matter and markdown properties as I'm sure you can guess, hold the page's front matter and markdown content.\nThese can then also be processed by page factories to generate the computed data like the\ntitle property.","destination":"page-models.html"},{"slug":"the-hydekernel","title":"The HydeKernel","content":"The HydeKernel\n\nIntroduction\n\nIn the centre, or should I say core, of HydePHP is the HydeKernel. The kernel encapsulates a HydePHP project and\nprovides helpful methods for interacting with it. You can think of it as the heart of HydePHP, if you're a romantic.\n\nThe HydeKernel is so important that you have probably used it already. The main entry point for the HydePHP\nAPI is the Hyde facade, which calls methods on the kernel.\n\nuse Hyde\\Hyde;\nuse Hyde\\Foundation\\HydeKernel;\n\nHyde::version(); \/\/ calls $HydeKernel->version()\n\nThe kernel is created very early on in the application lifecycle, in the bootstrap.php file, where it is also bound\nas a singleton into the application service container.\n\nAccessing the kernel\n\nThe HydeKernel is stored as a singleton in a static property in its own class and can be accessed in a few ways.\n\nCommonly, you'll use the Hyde facade which forwards calls to the singleton instance.\nYou can also use the hyde() function to get the Kernel, and call methods on it.\n\nSince the instance is also bound into the Laravel Application Service Container you can also use Dependency Injection by type-hinting the HydeKernel::class.\n\nHere are some examples of how you can call methods on the Kernel. All methods call the same method on the same instance, so it's just a matter of preference.\n\nuse Hyde\\Hyde;\nuse Hyde\\Foundation\\HydeKernel;\n\nHyde::version();\nHyde::kernel()->version();\nHydeKernel::getInstance()->version();\napp(HydeKernel::class)->version();\nhyde()->version();\n\nThe Kernel instance is constructed in bootstrap.php, and is available globally as $hyde.\n\nThe kernel lifecycle\n\nWhenever we talk about the kernel being \"booted\" we are talking about the kernel's role in the autodiscovery process.\n\nYou can read all about it in the Autodiscovery Documentation.\n\nAPI Reference\n\nSince the most common way to interact with the kernel is through the Hyde facade, we will use that for the examples.\nBut you could just as well chain the methods on the accessed kernel singleton instance if you wanted.\n\nversion()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::version(): string\n\n__construct()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\n$hyde = new HydeKernel(string $basePath): void\n\nfeatures()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::features(): Hyde\\Facades\\Features\n\nhasFeature()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::hasFeature(string $feature): bool\n\ntoArray()\n\nGet the instance as an array.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::toArray(): array\n\nfiles()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::files(): \\Hyde\\Foundation\\Kernel\\FileCollection\n\npages()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::pages(): \\Hyde\\Foundation\\Kernel\\PageCollection\n\nroutes()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::routes(): \\Hyde\\Foundation\\Kernel\\RouteCollection\n\nmakeTitle()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::makeTitle(string $value): string\n\nnormalizeNewlines()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::normalizeNewlines(string $string): string\n\nstripNewlines()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::stripNewlines(string $string): string\n\ntrimSlashes()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::trimSlashes(string $string): string\n\nmarkdown()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::markdown(string $text, bool $normalizeIndentation): Illuminate\\Support\\HtmlString\n\nformatLink()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::formatLink(string $destination): string\n\nrelativeLink()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::relativeLink(string $destination): string\n\nmediaLink()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::mediaLink(string $destination, bool $validate): string\n\nasset()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::asset(string $name, bool $preferQualifiedUrl): string\n\nurl()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::url(string $path): string\n\nhasSiteUrl()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::hasSiteUrl(): bool\n\nfilesystem()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::filesystem(): Hyde\\Foundation\\Kernel\\Filesystem\n\npath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::path(string $path): string\n\nvendorPath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::vendorPath(string $path, string $package): string\n\nmediaPath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::mediaPath(string $path): string\n\nsitePath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::sitePath(string $path): string\n\nsiteMediaPath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::siteMediaPath(string $path): string\n\npathToAbsolute()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::pathToAbsolute(array|string $path): array|string\n\npathToRelative()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::pathToRelative(string $path): string\n\ngetInstance()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getInstance(): Hyde\\Foundation\\HydeKernel\n\nsetInstance()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setInstance(Hyde\\Foundation\\HydeKernel $instance): void\n\ngetBasePath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getBasePath(): string\n\nsetBasePath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setBasePath(string $basePath): void\n\ngetSourceRoot()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getSourceRoot(): string\n\nsetSourceRoot()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setSourceRoot(string $sourceRoot): void\n\ngetOutputDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getOutputDirectory(): string\n\nsetOutputDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setOutputDirectory(string $outputDirectory): void\n\ngetMediaDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getMediaDirectory(): string\n\nsetMediaDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setMediaDirectory(string $mediaDirectory): void\n\ngetMediaOutputDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getMediaOutputDirectory(): string\n\nregisterExtension()\n\nRegister a HydePHP extension within the HydeKernel.\n\nTypically, you would call this method in the register method of a service provider. If your package uses the standard Laravel (Composer) package discovery feature, the extension will automatically be enabled when the package is installed.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::registerExtension(class-string<\\Hyde\\Foundation\\Concerns\\HydeExtension> $extension): void\n\ngetExtension()\n\nGet the singleton instance of the specified extension.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getExtension(class-string<T> $extension): T\n\nhasExtension()\n\nDetermine if the specified extension is registered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::hasExtension(class-string<\\Hyde\\Foundation\\Concerns\\HydeExtension> $extension): bool\n\ngetExtensions()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getExtensions(): array\n\ngetRegisteredExtensions()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getRegisteredExtensions(): array>\n\ngetRegisteredPageClasses()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getRegisteredPageClasses(): array>\n\nshareViewData()\n\nShare data for the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::shareViewData(Hyde\\Pages\\Concerns\\HydePage $page): void\n\ncurrentRouteKey()\n\nGet the route key for the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::currentRouteKey(): string\n\ncurrentRoute()\n\nGet the route for the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::currentRoute(): Hyde\\Support\\Models\\Route\n\ncurrentPage()\n\nGet the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::currentPage(): Hyde\\Pages\\Concerns\\HydePage\n\nisBooted()\n\nDetermine if the Kernel has booted.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::isBooted(): bool\n\nboot()\n\nBoot the Hyde Kernel and run the Auto-Discovery Process.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::boot(): void\n\nbooting()\n\nRegister a new boot listener.\n\nYour callback will be called before the kernel is booted. You can use this to register your own routes, pages, etc. The kernel instance will be passed to your callback.\n\n\/\/ torchlight! {\"lineNumbers\": false}\n\/* @param callable(\\Hyde\\Foundation\\HydeKernel): void $callback \/\nHyde::booting(callable(\\Hyde\\Foundation\\HydeKernel): void): void\n\nbooted()\n\nRegister a new "booted" listener.\n\nYour callback will be called after the kernel is booted. You can use this to run any logic after discovery has completed. The kernel instance will be passed to your callback.\n\n\/\/ torchlight! {\"lineNumbers\": false}\n\/* @param callable(\\Hyde\\Foundation\\HydeKernel): void $callback \/\nHyde::booted(callable(\\Hyde\\Foundation\\HydeKernel): void): void","destination":"the-hydekernel.html"},{"slug":"blog-posts","title":"Creating Blog Posts","content":"Creating Blog Posts\n\nIntroduction to Hyde Posts\n\nMaking blog posts with Hyde is easy. At the most basic level, all you need is to add a Markdown file to your _posts folder.\n\nTo use the full power of the Hyde post module you'll want to add YAML Front Matter to your posts.\n\nYou can interactively scaffold posts with automatic front matter using the HydeCLI:\n\nphp hyde make:post\nLearn more about scaffolding posts, and other files, in the console commands documentation.\n\nShort Video Tutorial\n\nBest Practices and Hyde Expectations\n\nSince Hyde does a lot of things automatically, there are some things you may need\nto keep in mind when creating blog posts so that you don't get unexpected results.\n\nFilenames\n\n- Markdown post files are stored in the _posts directory\n- The filename is used as the filename for the compiled HTML\n- Filenames should use kebab-case-name followed by the extension .md\n- Files prefixed with _underscores are ignored by Hyde\n- Your post will be stored in _site\/posts\/.html\n\nExample:\n\n\u2714 posts\/hello-world.md # Valid and will be compiled to site\/posts\/hello-world.html\n\nFront Matter\n\nFront matter is optional, but highly recommended for blog posts as the front matter is used to construct dynamic HTML\nmarkup for the post as well as meta tags and post feeds.\n\nYou are encouraged to look at the compiled HTML to learn\nand understand how your front matter is used. You can read more about the Front Matter format in the Front Matter documentation.\n\nBlog Post Example\n\nBefore digging deeper into all the supported options, let's take a look at what a basic post with front matter looks like.\n\n\/\/ filepath _posts\/my-new-post.md\ntitle: My New Post\ndescription: A short description used in previews and SEO\ncategory: blog\nauthor: Mr. Hyde\ndate: 2022-05-09 18:38\nWrite your Markdown here\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit.\nAutem aliquid alias explicabo consequatur similique,\nanimi distinctio earum ducimus minus, magnam.\n\nSupported Front Matter properties\n\nPost Front Matter Schema\n\nHere is a quick reference of the supported front matter properties.\nKeep on reading to see further explanations, details, and examples.\n\nKEY NAME VALUE TYPE EXAMPLE \/ FORMAT\n\ntitle string \"My New Post\"\ndescription string \"A short description\"\ncategory string \"my favorite recipes\"\ndate string \"YYYY-MM-DD [HH:MM]\"\nauthor string\/array See author section\nimage string\/array See image section\n\nNote that YAML here is pretty forgiving. In most cases you do not need to wrap strings in quotes.\nHowever, it can help in certain edge cases, for example if the text contains special Yaml characters, thus they are included here.\n\nIn the examples below, when there are multiple examples, they signify various ways to use the same property.\n\nWhen specifying an array you don't need all the sub-properties. The examples generally show all the supported values.\n\nTitle\n\ntitle: \"My New Post\"\n\nDescription\n\ndescription: \"A short description used in previews and SEO\"\n\nCategory\n\ncategory: blog\n\ncategory: \"My favorite recipes\"\n\nDate\n\ndate: \"2022-01-01\"\n\ndate: \"2022-01-01 12:00\"\n\nAuthor\n\nSpecify a page author, either by a username for an author defined in the authors config, or by an arbitrary name,\nor by an array of author data. See the Post Author section for more details.\n\nArbitrary name displayed \"as is\"\n\nauthor: \"Mr. Hyde\"\n\nUsername defined in authors config\n\nauthor: mr_hyde\n\nArray of author data\n\nauthor:\n name: \"Mr. Hyde\"\n username: mr_hyde\n website: https:\/\/twitter.com\/HydeFramework\n\nWhen specifying an array you don't need all the sub-properties. The example just shows all the supported values.\nArray values here will override all the values in the authors config entry.\n\nImage\n\nSpecify a cover image for the post, either by a local image path for a file in the _media\/ directory, or by a full URL.\nAny array data is constructed into a dynamic fluent caption, and injected into post and page metadata.\n\nLocal image path\n\nWhen supplying an image source with a local image path, the image is expected to be stored in the _media\/ directory.\nLike all other media files, it will be copied to _site\/media\/ when the site is built, so Hyde will resolve links accordingly.\n\nimage: image.jpg\n\nFull URL\n\nFull URL starting with http(s):\/\/) or \/\/ (protocol-relative).\nThe image source will be used as-is, and no additional processing is done.\n\nimage: https:\/\/cdn.example.com\/image.jpg\n\nData-rich image\n\nYou can also supply an array of data to construct a rich image with a fluent caption.\n\nimage:\n source: Local image path or full URL\n altText: \"Alt text for image\"\n titleText: \"Tooltip title\"\n copyright: \"Copyright (c) 2022\"\n licenseName: \"CC-BY-SA-4.0\"\n licenseUrl: https:\/\/example.com\/license\/\n authorUrl: https:\/\/photographer.example.com\/\n authorName: \"John Doe\"\n\nSee posts\/introducing-images\nfor a detailed blog post with examples and schema information!\n{ .info }\n\nUsing images in posts\n\nTo use images stored in the _media\/ directory, you can use the following syntax:\n\nImage Alt\n\nNote the relative path since the blog post is compiled to posts\/example.html\n\nTo learn more, check out the managing assets chapter on the topic.","destination":"blog-posts.html"},{"slug":"compile-and-deploy","title":"Compile and Deploy your site","content":"Compile and Deploy your site\n\nRunning the build command\n\nNow that you have some amazing content, you'll want to compile your site into static HTML.\n\nThis is as easy as executing the build command:\n\nphp hyde build\n\nYou can also compile a single file:\n\nphp hyde rebuild \n\nAnd, you can even start a development server to compile your site on the fly:\n\nphp hyde serve\n\nFurther reading\n\ninfo Key Concept: Autodiscovery When building the site, Hyde will use all the routes generated when the auto-discovery process scanned your source directories for files. The command will then compile them into static HTML using the appropriate layout depending on what kind of page it is. Thanks to Hyde, the days of manually defining routes are over!\n\nLearn more about these commands in the console commands documentation:\n\n- Build command\n- Rebuild command\n- Serve command\n\nDeploying your site\n\nOne of the things that make static sites so enjoyable to work with is how easy it is to deploy them to the web.\nThis list is not exhaustive, but gives you a general idea of the most common ways to deploy your site.\nIf you have ideas to add to the documentation, please send a pull request!\n\nGeneral deployment\n\nIn essence, all you need to do is copy the contents of the _site directory to a web server, and you're done.\n\nOnce the site is compiled there is nothing to configure or worry about.\n\nFTP and File Managers\n\nIf you have a conventional web host, you can use FTP\/SFTP\/FTPS to upload your compiled site files to the web server.\nSome web hosting services also have web-based file managers.\n\nTo deploy your site using any of these methods, all you need to do is upload the entire contents of your _site\ndirectory to the web server's public document root, which is usually the public_html, htdocs, or www directory.\n\nGitHub Pages - Manually\n\nGitHub Pages is a free service that allows you to host your static site on the web.\n\nIn general, push the entire contents of your _site directory to the gh-pages branch of your repository,\nor the docs\/ directory on your main branch, depending on how you set it up.\n\nPlease see the GitHub Pages documentation for more information.\n\nGitHub Pages - CI\/CD\n\nHyde works amazing with GitHub Pages and GitHub Actions and the entire build and deploy process can be automated.\n\n- We have a great blog post on how to do this, Automate HydePHP sites using GitHub Actions and GitHub Pages.\n\n- You can also copy our sample GitHub Actions Workflow.yml file.\n\nBy the way, HydePHP.com is hosted on GitHub Pages, and the site is compiled in a GitHub Action workflow that compiles and\ndeploys the site automatically when the source is updated using this GitHub workflow.","destination":"compile-and-deploy.html"},{"slug":"documentation-pages","title":"Creating Documentation Pages","content":"Creating Documentation Pages\n\nIntroduction to Hyde Documentation Pages\n\nWelcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier.\nUsing 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.\n\nHyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a\nresponsive sidebar that is automatically generated based on your Markdown files. You can even customize the order,\nlabels, and even groups, of the sidebar items to suit your needs.\n\nAdditionally, if you have a _docs\/index.md file, the sidebar header will link to it, and an automatically generated\n\"Docs\" link will be added to your site's main navigation menu, pointing to your documentation page.\n\nIf you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically,\nsaving you time and effort. For more information about this feature, see the extensions page.\n\nBest Practices and Hyde Expectations\n\nSince Hyde does a lot of things automatically, there are some things you may need\nto keep in mind when creating blog posts so that you don't get unexpected results.\n\nFilenames\n\n- Hyde Documentation pages are files stored in the _docs directory\n- The filename is used as the filename for the compiled HTML\n- Filenames should use kebab-case-name format, followed by the appropriate extension\n- Files prefixed with _underscores are ignored by Hyde\n- You should always have an index.md file in the _docs\/ directory\n- Your page will be stored in _site\/docs\/.html unless you change it in the config\n\nAdvanced usage and customization\n\nLike 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.\nSince 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 to see how it's all put together and find the customizations you are looking for.\n\nCreating Documentation Pages\n\nYou can create a Documentation page by adding a file to the _docs directory where the filename ends in .md.\n\nYou can also scaffold one quickly by using the HydeCLI.\n\nphp hyde make:page \"Page Title\" --type=\"docs\"\n\nThis will create the following file saved as _docs\/page-title.md\n\nPage Title\n\nFront Matter is optional\n\nYou don't need to use front matter to create a documentation page.\n\nHowever, Hyde still supports front matter here as it allows you to quickly override the default values.\n\nHere is a quick reference, however, you should take a look at the dynamic content section to learn more.\n\ntitle: \"Page Title\"\nnavigation:\n label: \"Sidebar Label\"\n hidden: true\n priority: 5\n\nDynamic content generation\n\nHyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title.\nIf you are not happy with the results you can customize them in the config or with front matter.\n\nFront Matter reference\n\nBefore we look at how to override things, here is an overview of the relevant content Hyde generates,\nand where the data is from as well as where it can be overridden.\n\nProperty Description Dynamic Data Source Override in\n\ntitle (string) The title of the page used in the HTML ` tag The first H1 heading (# Foo`) Front matter\nnavigation.label (string) The label for the page shown in the sidebar The page basename Front matter, config\nnavigation.priority (integer) The priority of the page used for ordering the sidebar Defaults to 999 Front matter, config\nnavigation.hidden (boolean) Hides the page from the sidebar none Front matter, config\nnavigation.group (string) The group the page belongs to in the sidebar Subdirectory, if nested Front matter\n\nSidebar\n\nThe sidebar is automatically generated from the files in the _docs directory. You will probably want to change the order\nof these items. You can do this in two ways, either in the config or with front matter using the navigation array settings.\n\nTable of contents\n\nHyde automatically generates a table of contents for the page and adds it to the sidebar.\n\nThe behaviour of this can be changed in the configuration file.\nSee the customization page for more details.\n\nSidebar ordering\n\nThe sidebar is sorted\/ordered by the priority property. The higher the priority the further down in the sidebar it will be.\nThe default priority is 999. You can override the priority using the following front matter:\n\nnavigation:\n priority: 5\n\nYou can also change the order in the Docs configuration file.\nSee the chapter in the customization page for more details. \nI personally think the config route is easier as it gives an instant overview, however the first way is nice as well.\n\nSidebar labels\n\nThe sidebar items are labelled with the label property. The default label is the filename of the file.\nYou can change it with the following front matter:\n\nnavigation:\n label: \"My Custom Sidebar Label\"\n\nSidebar grouping\n\nSidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items.\nThe Hyde docs for instance use this.\n\nThe feature is enabled automatically when one or more of your documentation pages have the navigation.group property set\nin the front matter. This will then switch to a slightly more compact sidebar layout with pages sorted into categories.\nAny pages without the group front matter will get put in the \"Other\" group.\n\nSidebar footer customization\n\nThe sidebar footer contains, by default, a link to your site homepage. You can change this in the config\/docs.php file.\n\n\/\/ filepath: config\/docs.php\n\n'sidebar' => [\n 'footer' => 'My Markdown Footer Text',\n],\n\nYou can also set the option to false to disable it entirely.\n\nUsing Front Matter\n\nTo enable sidebar grouping, you can add the following front matter to your documentation pages:\n\nnavigation:\n group: \"Getting Started\"\n\nAutomatic subdirectory-based grouping\n\nYou can also automatically group your documentation pages by placing source files in sub-directories.\n\nFor example, putting a Markdown file in _docs\/getting-started\/, is equivalent to adding the same front matter seen above.\n\ninfo Note that when the 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.\n\nHiding items\n\nYou can hide items from the sidebar by adding the hidden property to the front matter:\n\nnavigation:\n hidden: true\n\nThis can be useful to create redirects or other items that should not be shown in the sidebar.\n\ninfo The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header. \n\nCustomization\n\nPlease see the customization page for in-depth information on how to customize Hyde,\nincluding the documentation pages. Here is a high level overview for quick reference though.\n\nOutput directory\n\nIf you want to store the compiled documentation pages in a different directory than the default 'docs' directory,\nfor example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file.\nThe path is relative to the site output, typically _site.\n\n\/\/ filepath: config\/hyde.php\n'output_directories' => [\n \\Hyde\\Pages\\DocumentationPage::class => 'docs' \/\/ default [tl! --]\n \\Hyde\\Pages\\DocumentationPage::class => 'docs\/1.x' \/\/ What the Hyde docs use [tl! ++]\n]\n\nNote 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.\n\nAutomatic navigation menu\n\nBy 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 for more information.\n\nSidebar header name\n\nBy default, the site title shown in the sidebar header is generated from the configured site name suffixed with \"docs\".\nYou can change this in the Docs configuration file. Tip: The header will link to the docs\/index page, if it exists.\n\n'title' => 'API Documentation',\n\nSidebar page order\n\nTo 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.\nLink items without an entry here will have fall back to the default priority of 999, putting them last.\n\n'sidebar_order' => [\n 'readme',\n 'installation',\n 'getting-started',\n]\n\nSee the chapter in the customization page for more details. \n\nAutomatic sidebar group labels\n\nWhen using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names.\nIf these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file.\nThe array key is the directory name, and the value is the label.\n\nPlease 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!\n\n\/\/ Filepath: config\/docs.php\n\n'sidebargrouplabels' => [\n 'questions-and-answers' => 'Questions & Answers',\n],\n\nTable of contents settings\n\nIn the config\/docs.php file you can configure the behaviour, content, and the look and feel of the sidebar table of contents.\nYou can also disable the feature completely.\n\n'tableofcontents' => [\n 'enabled' => true,\n 'minheadinglevel' => 2,\n 'maxheadinglevel' => 4,\n 'smoothpagescrolling' => true,\n],\n\nUsing flattened output paths\n\nIf this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory.\nThis means that you can use the automatic directory-based grouping feature, but still have a \"flat\" output structure.\nNote 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.\n\nIf you set this to false, Hyde will match the directory structure of the source files (just like all other pages).\n\n\/\/ Filepath: config\/docs.php\n'flattenedoutputpaths' => true,\n\nSearch feature\n\nIntroduction\n\nThe HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator\nthat runs during the build command, and a frontend JavaScript plugin that adds the actual search widget.\n\ninfo Tip: The HydeSearch plugin is what powers the search feature on this site! Why not try it out?\n\nThe search feature is enabled by default. You can disable it by removing the documentationSearch from the Hyde Features config array.\n\n\/\/ filepath: config\/hyde.php\n'features' => [\n Features::documentationSearch(), \/\/ [tl! --]\n],\n\nUsing the search\n\nThe search works by generating a JSON search index which the JavaScript plugin loads asynchronously.\n\nTwo ways to access the search are added, one is a full page search screen that will be saved to docs\/search.html.\n\nThe second method is a button added to the documentation pages, similar to how Algolia DocSearch works.\nOpening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut \/.\n\ninfo The full page can be disabled by setting createsearchpage to false in the docs config.\n\nHiding pages from indexing\n\nIf you have a large page on your documentation site, like a changelog, you may want to hide it from the search index.\nYou can do this by adding the page identifier to the excludefromsearch array in the docs config, similar to how\nnavigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file.\n\n\/\/ filepath: config\/docs.php\n'excludefromsearch' => [\n 'changelog',\n]\n\nLive search with the realtime compiler\n\nThe Realtime Compiler that powers the php hyde serve command will automatically generate a fresh search index each time the browser requests it.\n\nAutomatic \"Edit Page\" button\n\nIntroduction\n\nHyde can automatically add links to documentation pages that take the user\nto a GitHub page (or similar) to edit the page. This makes it great for open-source projects\nlooking to allow others to contribute to the documentation in a quick and easy manner.\n\nThe feature is automatically enabled when you specify a base URL in the Docs configuration file.\nHyde expects this to be a GitHub path, but it will probably work with other methods as well,\nif not, please send a PR and\/or create an issue on the GitHub repository!\n\ninfo Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out!\n\nConfiguration\n\nAs an example configuration, let's take a practical example of how HydePHP.com uses this feature.\n\n\/\/ Filepath: config\/docs.php\n\n'sourcefilelocation_base' => 'https:\/\/github.com\/hydephp\/docs\/blob\/master\/',\n\nChanging the button text\n\nChanging the label is easy, just change the following config setting:\n\n\/\/ Filepath: config\/docs.php\n'editsourcelink_text' => 'Edit Source on GitHub',\n\nChanging the position\n\nBy default, the button will be shown in both the documentation page footer.\nYou can change this by setting the following config setting to 'header', 'footer', or 'both'\n\n\/\/ Filepath: config\/docs.php\n'editsourcelink_position' => 'header',\n\nAdding a button icon\n\nThis is not included out of the box, but is easy to add with some CSS!\nJust target the .edit-page-link class.\n\n\/\/ filepath e.g. app.css\n.edit-page-link::before {content: \"\u270f \"}\n\nChanging the Blade view\n\nYou can also publish the edit-source-button.blade.php view and change it to your liking.","destination":"documentation-pages.html"},{"slug":"managing-assets","title":"Managing and Compiling Assets","content":"Managing and Compiling Assets\n\nIntroduction\n\nManaging and compiling assets is a very common task in web development. Unfortunately, it's rarely fun.\n\nWith Hyde, you don't have to do it, in fact, you can skip this entire page if you are happy with how it is.\nBut as always with Hyde, you can customize everything if you want to.\n\nHyde ships with a complete frontend using Blade views, TailwindCSS styles, and Alpine.js interactions.\nSome extra custom styles are made in the HydeFront package, which is pre-installed and bundled in the pre-configured Laravel Mix.\n\nTo get you started quickly, all the styles are already compiled and minified into _media\/app.css,\nwhich will be copied to the _site\/media\/app.css directory when you run php hyde build.\n\nAdditional Information and Answers to Common Questions\n\nIs NodeJS\/NPM Required for Using Hyde?\n\nNo, it is optional. All the compiled styles that you need are already installed, and NPM is only necessary if you want to compile your own styles.\n\nWhen Should Assets be Compiled?\n\nThe _media\/app.css file that comes with Hyde contains TailwindCSS for all classes that are used in the default Blade views, as well as the HydeFront custom styles.\nIf you want to customize the Tailwind settings or add custom styles, you will need to recompile the styles yourself.\n\nFor example, if you customize the Blade views and add new classes or add new classes in Blade-based pages, you may need to compile the assets yourself to get the new styles.\nIf you use Markdown-based pages, you do not need to compile anything as those styles are already included in the compiled CSS file.\n\nHow are assets stored and managed?\n\nThe frontend assets are separated into three places.\n\n- The resources\/assets folder contain source files, meaning files that will be compiled into something else.\nHere you will find the app.css file that bootstraps the TailwindCSS styles. This file is also an excellent place\nto add your custom styles. It is also where we import HydeFront. If you compile this file in the base install,\nit will output the same file that's already included in Hyde.\n\n- The _media folder contains compiled (and usually minified) files. When Hyde compiles your static site,\nall asset files here will get copied as they are into the _site\/media folder.\n\n- The _site\/media folder contains the files that are served to the user.\n\nWhat is the difference between media and site\/media?\n\nIt may seem weird to have two folders for storing the compiled assets, but it is quite useful.\n\nThe site directory is intended to be excluded from version control, while the media folder is included in the\nversion control. You are of course free to modify this behaviour by editing the webpack.mix.js file to change the output directory.\n\nHow do I compile assets?\n\nFirst, make sure that you have installed all the NodeJS dependencies using npm install.\nThen run npm run dev to compile the assets. If you want to compile the assets for production, run npm run prod.\nYou can also run npm run watch to watch for changes in the source files and recompile the assets automatically.\n\nHow does it work?\n\nHyde uses Laravel Mix (which is a wrapper for Webpack) to compile the assets.\n\nWhen running the npm run dev\/prod command, the following happens:\n\n1. Laravel Mix will compile the resources\/assets\/app.css file into _media\/app.css using PostCSS with TailwindCSS and AutoPrefixer.\n2. Mix then copies the media folder into site\/media, this is so that they are automatically accessible to your site without having to rerun php hyde build.\n\nTelling Hyde where to find assets\n\nCustomizing the Blade templates\n\nTo make it really easy to customize asset loading, the styles and scripts are loaded in dedicated Blade components.\n\n- Styles are loaded in hyde::layouts.styles\n- Scripts are loaded in hyde::layouts.scripts\n\nTo customize them, run the following command:\n\nphp hyde publish:views layouts\n\nThen edit the files found in resources\/views\/vendor\/hyde\/layouts directory of your project.\n\nYou might not even need to do anything!\n\nFor the absolute majority of the cases, you don't need to mess with these files. Hyde will automatically load the app.css file when it exists in the _media directory.\n\nLoading from CDN\n\nIf you want to load the same pre-compiled file included with Hyde but from a CDN, you can set loadappstylesfromcdn to true in the config\/hyde.php file. While you lose the ability to customize it, your styles will be automatically updated when needed, as the installed Framework version will automatically specify the correct version to load.\n\nUsing the TailwindCSS Play CDN\n\nwarning Note that the Play CDN is not meant for production use, so enabling it will add a warning to the web console.\n\nIf you want to use the TailwindCSS Play CDN, all you need to do is\nset useplaycdn to true in the config\/hyde.php file. This will in addition to loading the standard app.css file,\nalso add a script tag which loads the TailwindCSS Play CDN.\n\nWhat's even better is that Hyde will also inject the contents of the included tailwind.config.js file into the script tag,\nso the Play CDN styles match the ones created by Laravel Mix.\n\nAll in all, this allows you to tinker around with Tailwind without having to compile anything.\n\nManaging images\n\nAs mentioned above, assets stored in the media folder are automatically copied to the site\/media folder,\nmaking it the recommended place to store images. You can then easily reference them in your Markdown files.\n\nReferencing images\n\nThe recommended way to reference images is with relative paths as this offers the most compatibility,\nallowing you to browse the site both locally on your filesystem and on the web when serving from a subdirectory.\n\nwarning Note: The path is relative to the compiled file in the site output\n\nThe path to use depends on the location of the page. Note the subtle difference in the path prefix.\n\n- If you are in a Blog Post or Documentation Page, use ..\/media\/image.png\n- If in a Markdown Page or Blade Page, use media\/image.png\n- While not recommended, you can also use absolute paths: \/media\/image.png\n- You can of course also use full URLs, for example when using a CDN.\n\nMaking images accessible\n\nTo improve accessibility, you should always add an alt text. Here is a full example including an image in a blog post:\n\nImage Alt # Note the relative path\n\nSetting a featured image for blog posts\n\nHyde offers great support for creating data-rich and accessible featured images for blog posts.\n\nYou can read more about this on the creating blog posts page.","destination":"managing-assets.html"},{"slug":"static-pages","title":"Creating Static Pages","content":"# Creating Static Pages\n\n## Introduction to Hyde Pages\n\nHyde offers two ways to create static pages:\nMarkdown pages which are perfect for simple pages that focus heavily on the content,\nand Blade pages which are perfect for more complex pages where you want full control over the HTML,\nand where you may want to include other components or want to use dynamic PHP code.\n\nLet's start with the basics.\n\n### Best Practices and Hyde Expectations\n\nSince Hyde does a lot of things automatically, there are some things you may need\nto keep in mind when creating blog posts so that you don't get unexpected results.\n\n#### Filenames\n\n- Hyde Pages are files stored in the _pages directory\n- The filename is used as the filename for the compiled HTML\n- Filenames should use kebab-case-identifier format, followed by the appropriate extension\n- Files prefixed with _underscores are ignored by Hyde\n- Your page will be stored in _site\/.html\n- Blade pages will override any Markdown pages with the same filename when compiled\n\n## Creating Markdown Pages\n\nMarkdown pages are the easiest way to create static pages. You can create a Markdown page by adding a file to the\n_pages directory where the filename ends in .md. You can also use Front Matter to add page metadata.\n\n### Scaffolding Markdown Pages\n\nScaffolding a Markdown page is as easy as using the HydeCLI.\n\nphp hyde make:page \"Page Title\"\n\nThis will create the following file saved as _pages\/page-title.md\n\ntitle: Page Title\n# Page Title\n\n\/\/ Write your content here\n\nYou can of course also create the file yourself with your text editor.\n\n### Front Matter is optional\n\nThe most common front matter used for Markdown pages is the title, which is used as the HTML ``.\n\nIf you don't supply a front matter title, Hyde will attempt to find a title in the Markdown body by searching\nfor the first level one heading (# Page Title), and if that fails, it will generate one from the filename.\n\n#### Navigation Front Matter\n\nFurthermore, you can customize how the page appears in the navigation menu using the following front matter options.\nYou can set just one or all of them, as Hyde will fill in the gaps for the rest.\n\nnavigation:\n label: 'string',\n priority: 'int',\n hidden: 'bool',\n group: 'string',\n\n- label is the text that will be displayed in the navigation menu\n- priority is the order in which the page will appear in the navigation menu (order is also supported)\n- hidden will hide the page from the navigation menu (visible) is also supported, but obviously invert the value)\n- group will put the page in a dropdown menu with the specified group name (category) is also supported)\n\n## Creating Blade Pages\n\nSince Hyde is based on Laravel and uses the powerful Blade templating engine, you can use Blade pages to create more\ncomplex pages with both standard HTML, PHP code, and the templating opportunities provided by Blade directives.\n\nIf you are not familiar with Blade, you may want to read the Laravel Blade docs first.\n\n### Scaffolding Blade Pages\n\nWe can scaffold Blade pages using the same CLI command as Markdown pages, however, this time we need to specify that\nwe want to use the blade page type, by using the --type option.\n\nphp hyde make:page \"Page Title\" --type=\"blade\"\n\nThis will create a file saved as _pages\/page-title.blade.php\n\nYou can of course also create the file yourself with your text editor, however,\nthe scaffolding command for Blade pages is arguably even more helpful than the\none for Markdown pages, as this one automatically adds the included app Layout.\n\nLet's take a look at the scaffolded file. You can also copy and paste this\nif you don't want to use the scaffolding command.\n\n@extends('hyde::layouts.app')\n@section('content')\n@php($title = \"Page Title\")\n\n Page Title\n\n@endsection\n\nTip: You don't have to use Blade in Blade pages. It's also perfectly fine to use plain HTML,\nhowever you still need to use the blade.php extension so Hyde can recognize it.\n\n## When to use which?\n\nMarkdown pages look great and work well for simple \"about\" pages and the like, but with Markdown we are still pretty limited.\n\nIf you are comfortable with it and have the need for it, use Blade to create more complex pages! And mix and match between them!\nSome page types are better suited for Markdown, and others for Blade. Don't limit yourself to just one type.\n\n### Comparison\n\nMarkdown Blade\n\n\u2795 Easily created and updated \u2795 Full control over the HTML\n\u2795 Very fast to create simple and lightweight pages \u2795 Use the default app layout or create your own\n\u2795 Suited for content-heavy pages such as \"about us\" \u2795 Use Blade templates and components to keep code DRY\n\u2796 Not as flexible as Blade pages \u2795 Use arbitrary PHP right in the page to create dynamic content\n \u2795 Access to all Blade helper directives like @foreach, @if, etc.\n \u2796 Takes longer to create as you need to write the markup\n \u2796 You may need to recompile your CSS if you add Tailwind classes\n\n### Live Demos\n\nThe Hyde website (hydephp.com) uses both Markdown and Blade pages. The homepage for example, is a Blade page and uses a bunch of custom HTML.\n\nA great example of a Markdown page can be found at hydephp.github.io\/portfolio-demo, you can see the page source here on GitHub.\n\n## Bonus: Creating HTML Pages\n\nIf you have an already created HTML page, simply drop it into the _pages directory and Hyde will copy it over as it is\ninto the _site directory. Like all other Hyde pages, the page will show up in the navigation menu using a title parsed from the filename.\nYou won't be able to change any settings with front matter, however.","destination":"static-pages.html"},{"slug":"advanced-customization","title":"Advanced Customization","content":"Advanced Customization\n\nIntroduction\n\nThis page covers advanced usage and is intended for developers who know what they are doing. Documentation here will be\nmainly example driven, as it is assumed you have somewhat of an understanding of what you are doing already.\n\nPrerequisites for customizing directories\n\ninfo Before customizing source and output directories it may be helpful to know how these settings are stored internally.\n\nThe following is a summary from the Page Models documentation:\n\nEach page type is represented by a page model class. Each of those classes have static properties that store the source and output directories.\nThese properties are set when the HydeServiceProvider\nis registered, at which point the provider will search for any overrides in the config file.\n\nThis means that there are two options to change the source and output directories:\n1. Recommended: You can change the values in the config file, to let the HydeServiceProvider handle it for you.\n2. Advanced\/Overkill: You can also set the static properties directly in the page model classes if you prefer.\n - You'd probably want to do this in a service provider, as it must be done before the Kernel is booted.\n - You can use the RegistersFileLocations\n trait to use the same registration logic as the HydeServiceProvider.\n\nCustomizing source directories\n\nThe directories you place your content in are important. The directory will be used to determine the proper page type and the templates used.\nIf you are not happy the with defaults, you can change them. Note that these are relative to the source_root setting,\nwhich is the root of your project, by default.\n\nNote that you need to take care of conflicts when changing the source directories. For example, if you store Markdown\nposts in the same directory as documentation pages, Hyde will not know which page type to use.\n\nIn the config file\n\n\/\/ filepath config\/hyde.php\n\n'source_directories' => [\n HtmlPage::class => '_pages',\n BladePage::class => '_pages',\n MarkdownPage::class => '_pages',\n MarkdownPost::class => '_posts',\n DocumentationPage::class => '_docs',\n],\n\nIn a service provider\n\n\/\/ filepath app\/AppServiceProvider.php\nuse Hyde\\Framework\\Concerns\\RegistersFileLocations;\n\npublic function register(): void\n{\n $this->registerSourceDirectories([\n HtmlPage::class => '_pages',\n BladePage::class => '_pages',\n MarkdownPage::class => '_pages',\n MarkdownPost::class => '_posts',\n DocumentationPage::class => '_docs',\n ]);\n}\n\nCustomizing output directories\n\nLike source directories, the output directories are also important as they determine the output path for the compiled pages.\nwarning Note that changing output directories also affects the route keys, as those are based on the output directory. Scroll down to see the Route key impact section for more information.\n\nEach option is relative to the site's output_directory setting. Setting a value to '' will output the page to the site root.\n\nIn the config file\n\n\/\/ filepath config\/hyde.php\n'output_directories' => [\n HtmlPage::class => '',\n BladePage::class => '',\n MarkdownPage::class => '',\n MarkdownPost::class => 'posts',\n DocumentationPage::class => 'docs',\n],\n\nIn a service provider\n\n\/\/ filepath app\/AppServiceProvider.php\nuse Hyde\\Framework\\Concerns\\RegistersFileLocations;\n\npublic function register(): void\n{\n $this->registerOutputDirectories([\n HtmlPage::class => '',\n BladePage::class => '',\n MarkdownPage::class => '',\n MarkdownPost::class => 'posts',\n DocumentationPage::class => 'docs',\n ]);\n}\n\nRoute key impact\n\nFor example, changing the output directory of Markdown posts to blog instead of posts will change the route key base from posts to blog.\nThis means that a file stored as _posts\/hello-world.md will have the route key blog\/hello-world instead of posts\/hello-world,\nthis may break your site's configuration and links, so you should always verify your site works properly after such a change.\nYou can learn more about this in the route key documentation.\n\nCustom source root\n\nHydePHP will by default look for the source directories shown above in the root of your project.\nIf you're not happy with this, it's easy to change! For example, you might want everything in a 'src' subdirectory.\nThat's easy enough, just set the value of the source_root setting in config\/hyde.php to 'src', or whatever you prefer!\n\n\/\/ filepath config\/hyde.php\n\n'source_root' => '', \/\/ [TL! --]\n'source_root' => 'src', \/\/ [TL! ++]\n\nAutomatic change\n\nYou can even make this change automatically with the php hyde change:sourceDirectory command!\n\nphp hyde change:sourceDirectory \n\nWhen run, Hyde will update the source directory setting in the config file, then create the directory if it doesn't exist,\nand move all source directories and their content into it.\n\nCustom media directory\n\nThe media directory houses assets like images and stylesheets. The default directory is _media, and upon building the site,\nHyde will copy all files in this directory to _site\/media (or whatever your configured output and media directories are).\n\nYou can change the path to this directory by setting the media_directory option in config\/hyde.php.\n\n\/\/ filepath config\/hyde.php\n'mediadirectory' => 'media',\n\nNext steps\n\n1. Note that you will likely need to manually update webpack.mix.js so Laravel Mix can compile the assets correctly.\n2. You will of course also need to copy over any existing files from the old directory to the new one.\n\nNote that this setting affects both source and output directories\n\nNote that this change will affect both the source and output directories. For example, if you set the value to assets,\nall files from assets will be copied to _site\/assets. If the setting starts with an underscore, that will be removed\nfrom the output directory, so files in assets will be copied to site\/assets.\n\nCustom output directory\n\ndanger Warning: Hyde deletes all files in the output directory before compiling the site. Don't set this path to a directory that contains important files!\n\nIf you want to store your compiled website in a different directory than the default _site, you can change the path\nusing the following configuration option in config\/hyde.php. The path is expected to be relative to your project root.\n\n\/\/ filepath config\/hyde.php\n'outputdirectory' => 'site',","destination":"advanced-customization.html"},{"slug":"advanced-markdown","title":"Advanced Markdown","content":"Advanced Markdown\n\nIntroduction\n\nSince HydePHP makes heavy use of Markdown, there are some extra features and helpers created just for Hyde to make using Markdown even easier and more powerful!\n\nUsing Blade in Markdown\n\nA special feature in Hyde, is that you can use Laravel Blade in Markdown files!\n\nTo use Blade in your Markdown files, simply use the Blade shortcode directive, followed by your desired Blade string.\n\nStandard syntax\n\n [Blade]: {{ \"Hello World!\" }} \/\/ Will render: 'Hello World!'\n\nBlade includes\n\nOnly single-line shortcode directives are supported. If you need to use multi-line Blade code, use an @include\ndirective to render a more complex Blade template. You can pass data to includes by specifying an array to the second argument.\n\n [Blade]: @include(\"hello-world\")\n [Blade]: @include(\"hello\", [\"name\" => \"World\"])\n\nEnabling Blade-supported Markdown\n\nThe feature is disabled by default since it allows arbitrary PHP to run, which could be a security risk, depending on your setup.\nHowever, if your Markdown is trusted, and you know it's safe, you can enable it in the config\/markdown.php file.\n\n\/\/ filepath: config\/markdown.php\n'enable_blade' => true,\n\nLimitations\n\nAll shortcodes must be the first word on a new line, and only single-line shortcodes are supported.\n\nColoured Blockquotes\n\nThe HydePHP Markdown converter also supports some extra directives and features. One of them being four different\ncoloured blockquotes. Simply append the desired colour after the initial > character.\n\n\u200e> Normal Blockquote\n\u200e>info Info Blockquote\n\u200e>warning Warning Blockquote\n\u200e>danger Danger Blockquote\n\u200e>success Success Blockquote\n\nNormal Blockquote\ninfo Info Blockquote\nwarning Warning Blockquote\ndanger Danger Blockquote\nsuccess Success Blockquote\n\nCustomizations\n\nYou can easily customize these styles too by adding and editing the following in your resources\/app.css file, and then recompiling your site styles.\nThe code examples here use the Tailwind @apply directives, but you could also use border-color: something; just as well.\n\n\/* filepath resources\/app.css\n\n\/* Markdown Features *\/\n\n.prose blockquote.info {\n @apply border-blue-500;\n}\n\n.prose blockquote.success {\n @apply border-green-500;\n}\n\n.prose blockquote.warning {\n @apply border-amber-500;\n}\n\n.prose blockquote.danger {\n @apply border-red-600;\n}\n\nMarkdown usage\n\nThe coloured blockquotes also support inline Markdown, just like normal blockquotes.\n\n\u200e>info Formatting is supported!\n\nLimitations\n\nNote that these currently do not support multi-line blockquotes.\n\nCode block filepaths\n\nWhen browsing these documentation pages you may have noticed a label in the top right corner of code blocks specifying the file path.\nThese are also created by using a custom Hyde feature that turns code comments into automatic code blocks.\n\nUsage\n\nSimply add a code comment with the path in the first line of a fenced code block like so:\n\n\/\/ Filepath: _docs\/advanced-markdown.md\n\u200e\/\/ Filepath: hello-world.php\n\necho 'Hello World!';\n\nWhich becomes:\n\n\/\/ Filepath: hello-world.php\n\necho 'Hello World!';\n\nAlternative syntax\n\nThe syntax is rather forgiving, by design, and supports using both \/\/ and # for comments.\nThe colon is also optional, and the 'filepath' string is case-insensitive. So the following is also perfectly valid:\n\n\u200e\/\/ filepath hello.js\nconsole.log('Hello World!');\n\nIf you have a newline after the filepath, like in the first example, it will be removed so your code stays readable.\n\nAdvanced usage\n\nIf you have enabled HTML in Markdown by setting the allow_html option to true in your config\/markdown.php file,\nanything within the path label will be rendered as HTML. This means you can add links, or even images to the label.\n\n\/\/ Filepath: View file on Github\n\u200e\/\/ Filepath: View file on Github\n\nLimitations\n\nThe filepaths are hidden on mobile devices using CSS to prevent them from overlapping with the code block.\n\nConfiguration\n\nFull configuration reference\n\nAll Markdown-related configuration options are in the config\/markdown.php file.\nYou can find the full reference on the Customization page.\n\nRaw HTML Tags\n\nTo convert Markdown, HydePHP uses the GitHub Flavored Markdown extension, which strips out potentially unsafe HTML.\nIf you want to allow all arbitrary HTML tags, and understand the risks involved, you can enable all HTML tags by setting\nthe allow_html option to true in your config\/markdown.php file.\n\n\/\/ filepath: config\/markdown.php\n'allow_html' => true,\n\nThis will add and configure the DisallowedRawHtml CommonMark extension so that no HTML tags are stripped out.\n\nTailwind Typography Prose Classes\n\nHydePHP uses the Tailwind Typography to style rendered Markdown.\nWe do this by adding the .prose CSS class to the HTML elements containing the rendered Markdown, using the built-in Blade components.\n\nYou can easily edit these classes, for example if you want to customize the prose colours, in the config\/markdown.php file.\n\n\/\/ filepath: config\/markdown.php\n'prose_classes' => 'prose dark:prose-invert', \/\/ [tl! remove]\n'prose_classes' => 'prose dark:prose-invert prose-img:inline', \/\/ [tl! add]\n\nPlease note that if you add any new classes, you may need to recompile your CSS file.","destination":"advanced-markdown.html"},{"slug":"collections","title":"File-based Collections","content":"# File-based Collections\n\n## Introduction to Hyde Data Collections\n\nHyde provides DataCollections, a subset of Laravel Collections giving you\na similar developer experience to working with Eloquent Collections. However, instead of accessing a database,\nit's all entirely file-based using static data files such as Markdown, Yaml, and JSON files which get\nparsed into objects that you can easily work with.\n\nAs you have access to all standard Laravel Collection methods, you are encouraged to read the\nLaravel Collections documentation for more information.\n\nThis article covers advanced usage intended for those who are writing their own Blade views, and is not required as Hyde comes pre-packaged with many templates for you to use.\n\n## High-Level Concept Overview\n\nTo make collections easy to use and understand, Hyde makes a few assumptions about the structure of your collections.\nFollow these conventions and creating dynamic static sites will be a breeze.\n\n1. Collections are accessed through static methods in the DataCollections class.\n2. Collections are stored as files in subdirectories of the resources\/collections directory.\n3. To get a collection, specify name of the subdirectory the files are stored in.\n4. Data will be parsed into differing objects depending on which facade method you use. See the table below.\n5. The class is aliased so that you can use it in Blade files without having to include the namespace.\n6. While not enforced, each subdirectory should probably only have the same filetype to prevent developer confusion\n7. Unlike source files for pages, files starting with underscores are not ignored.\n8. You can customize the source directory for collections through a service provider.\n9. If the base source directory does not exist, it will be created for you.\n\n## Available Collection Types\n\n### Quick Reference Overview\n\nThe following facade methods for creating data collections are available:\n\n\\Hyde\\Support\\DataCollections::markdown(string $name);\n\\Hyde\\Support\\DataCollections::yaml(string $name);\n\\Hyde\\Support\\DataCollections::json(string $name, bool $asArray = false);\n\n### Quick Reference Table\n\nCollection Type Facade Method Returned Object Type File Extension\n\nMarkdown ::markdown() MarkdownDocument .md\nYaml ::yaml() FrontMatter .yaml,  .yml\nJson ::json() stdClass OR  array .json\n\n## Markdown Collections\n\n### Usage\n\n$collection = \\Hyde\\Support\\DataCollections::markdown('name');\n\n### Example returns\n\nHere is an approximation of the data types contained by the variable created above:\n\n\\Hyde\\Support\\DataCollections {\n \"testimonials\/1.md\" => Hyde\\Markdown\\Models\\MarkdownDocument\n \"testimonials\/2.md\" => Hyde\\Markdown\\Models\\MarkdownDocument\n \"testimonials\/3.md\" => Hyde\\Markdown\\Models\\MarkdownDocument\n ]\n}\n\nThe returned MarkdownObjects look approximately like this:\n\n\\Hyde\\Markdown\\Models\\MarkdownDocument {\n +matter: Hyde\\Markdown\\Models\\FrontMatter {\n +data: array:1 [\n \"author\" => \"John Doe\"\n ]\n }\n +markdown: Hyde\\Markdown\\Models\\Markdown {\n +body: \"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\"\n }\n}\n\nAssuming the Markdown document looks like this:\n\nauthor: \"John Doe\"\nLorem ipsum dolor sit amet, consectetur adipiscing elit...\n\n## Yaml Collections\n\n### Usage\n\n$collection = \\Hyde\\Support\\DataCollections::yaml('name');\n\n### Example returns\n\nHere is an approximation of the data types contained by the variable created above:\n\n\\Hyde\\Support\\DataCollections {\n \"authors\/1.yaml\" => Hyde\\Markdown\\Models\\FrontMatter {\n +data: array:1 [\n \"name\" => \"John Doe\",\n \"email\" => \"john@example.org\"\n ]\n }\n}\n\nAssuming the Yaml document looks like this:\n\nname: \"John Doe\"\nemail: \"john@example.org\"\n\nwarning Note that the Yaml file should start with --- to be parsed correctly.\n\n## Json Collections\n\n### Usage\n\n$collection = \\Hyde\\Support\\DataCollections::json('name');\n\nBy default, the entries will be returned as stdClass objects. If you want to return an associative array instead, pass true as the second parameter:\n\n$collection = \\Hyde\\Support\\DataCollections::json('name', true);\n\nSince both return values use native PHP types, there are no example returns added here, as I'm sure you can imagine what they look like.\n\n## Markdown Collections - Hands-on Guide\n\nI think the best way to explain DataCollections is through examples, so let's create a Blade page with customer testimonials!\n\nThis example will use Markdown Collections, but the same concepts apply to all other collection types.\n\n#### Setting up the file structure\n\nWe start by setting up our directory structure. We will create a testimonials subdirectory, which will be the collection name.\n\nIn it, we will place Markdown files. Each file will be a testimonial.\nThe Markdown will be parsed into a MarkdownDocument object which parses any optional YAML front matter.\n\nHere is the sample Markdown we will use:\n\n\/\/ filepath: resources\/collections\/testimonials\/1.md\nauthor: John Doe\nLorem ipsum dolor sit amet, consectetur adipiscing elit...\n\nLet's take a look at our directory structure. I just copied the same file a few times.\nYou can name the files anything you want, I kept it simple and just numbered them.\n\nresources\/collections\n\u2514\u2500\u2500 testimonials\n \u251c\u2500\u2500 1.md\n \u251c\u2500\u2500 2.md\n \u2514\u2500\u2500 3.md\n\n#### Using the Facade to Access the Collections\n\nNow for the fun part! We will use the DataCollections::markdown() to access all our files into a convenient object.\nThe class is registered with an alias, so you don't need to include any namespaces when in a Blade file.\n\nThe general syntax to use the facade is as follows:\n\nDataCollections::markdown('subdirectory_name')\n\nThis will return a Hyde DataCollections object, containing our Markdown files as MarkdownDocument objects. Here is a quick look at the object the facade returns:\n\n^ Hyde\\Support\\DataCollections {#651 \u25bc\n #items: array:3 [\u25bc\n \"testimonials\/1.md\" => Hyde\\Markdown\\Models\\MarkdownDocument {#653 \u25bc\n +matter: Hyde\\Markdown\\Models\\FrontMatter {#652 \u25b6}\n +markdown: Hyde\\Markdown\\Models\\Markdown {#654 \u25b6}\n }\n \"testimonials\/2.md\" => Hyde\\Markdown\\Models\\MarkdownDocument {#656 \u25b6}\n \"testimonials\/3.md\" => Hyde\\Markdown\\Models\\MarkdownDocument {#659 \u25b6}\n ]\n}\n\n#### Implementing it in a Blade view\n\nLet's create a Blade page to display all our testimonials.\n\nphp hyde make:page \"Testimonials\" --type=\"blade\"\n\nAnd we can use the collection almost like any other Laravel one. As you can see, since each entry is a MarkdownDocument class,\nwe are able to get the author from the front matter, and the content from the body.\n\n\/\/ filepath _pages\/testimonials.blade.php\n@foreach(DataCollections::markdown('testimonials') as $testimonial)\n \n {{ $testimonial->body }}\n {{ $testimonial->matter['author'] }}\n \n@endforeach","destination":"collections.html"},{"slug":"customization","title":"Customizing your Site","content":"# Customizing your Site\n\n## Introduction\n\nHyde favours \"Convention over Configuration\"\nand comes preconfigured with sensible defaults. However, Hyde also strives to be modular and endlessly customizable\nif you need it. This page guides you through the many options available!\n\nAll the configuration files are stored in the config directory, and allow you to customize almost all aspects of your site.\nEach option is documented, so feel free to look through the files and get familiar with the options available to you.\n\n## Accessing Configuration Values\n\n### Configuration API Recap\n\nHydePHP uses the same configuration system as Laravel. Here's a quick recap from the Laravel Documentation:\n\nYou may easily access your configuration values using the global config function from anywhere in your project code.\nThe configuration values may be accessed using \"dot notation\" syntax, which includes the name of the file and option you wish to access.\n\n$value = config('hyde.name');\n\nA default value may also be specified and will be returned if the configuration option does not exist:\n\n$value = config('hyde.name', 'HydePHP');\n\nHydePHP also provides a strongly typed Config facade which extends the Laravel Config facade, but allows strict types:\n\nuse Hyde\\Facades\\Config;\n\n\/\/ Will always return a string, or it throws a TypeError\n$name = Config::getString('hyde.name', 'HydePHP'): string;\n\n### Dot Notation\n\nAs seen in the example above, when referencing configuration options, we often use \"dot notation\" to specify the configuration file.\nFor example, config('hyde.name') means that we are looking for the name option in the config\/hyde.php file.\n\n### Front Matter or Configuration Files?\n\nIn some cases, the same options can be set in the front matter of a page or in a configuration file. Both ways are always documented, and it's up to you to choose which one you prefer. Note that in most cases, if a setting is set in both the front matter and the configuration file, the front matter setting will take precedence.\n\n### A note on file paths\n\nWhen Hyde references files, especially when passing filenames between components, the file path is almost always\nrelative to the root of the project. Specifying absolute paths yourself could lead to unforeseen problems.\n\n## Configuration Files Overview\n\nThere are a few configuration files available in the config directory. All options are documented, so feel free to look through the files and get familiar with the options available to you.\n\nBelow are two tables over the different configuration files. Click on a file name to see the default file on GitHub.\n\n### HydePHP Configuration Files\n\nThese are the main configuration files for HydePHP and lets you customize the look and feel of your site, as well as the behaviour of HydePHP itself.\nThe main configuration file, hyde.php, is used for things ranging from site name and base URL to navigation menus and what features to enable.\n\nConfig File Description\n\nhyde.php Main HydePHP configuration file for customizing the overall project.\ndocs.php Options for the HydePHP documentation site generator module.\nmarkdown.php Configure Markdown related services, as well as change the CommonMark extensions.\napp\/config.php Configures the underlying Laravel application. (Commonly found as config\/app.php in Laravel apps)\n\ninfo Tip: The values in hyde.php can also be set in YAML by creating a hyde.yml file in the root of your project. See #yaml-configuration for more information.\n\n### Publishable Laravel & Package Configuration Files\n\nSince HydePHP is based on Laravel we also have a few configuration files related to them. As you most often don't need\nto edit any of these, unless you want to make changes to the underlying application, they are not present in the\nbase HydePHP installation. However, you can publish them to your project by running php hyde publish:configs.\n\nConfig File Description\n\nview.php Configures the paths for the Blade View compiler.\ncache.php Configures the cache driver and cache path locations.\ncommands.php Configures the Laravel Zero commands for the HydeCLI.\ntorchlight.php Configures settings for the Torchlight syntax highlighting integration.\n\n{.align-top}\n\nIf any of these files are missing, you can run php hyde publish:configs to copy the default files to your project.\n\n## Configuration Options\n\nWhile all options are already documented within the files, here are some further explanations of some of the options.\n\n### RSS feed generation\n\nWhen enabled, an RSS feed containing all your Markdown blog posts will be generated when you compile your static site.\nHere are the default settings:\n\n\/\/ filepath config\/hyde.php\n'rss' => [\n \/\/ Should the RSS feed be generated?\n 'enabled' => true,\n\n \/\/ What filename should the RSS file use?\n 'filename' => 'feed.xml',\n\n \/\/ The channel description.\n 'description' => env('SITE_NAME', 'HydePHP').' RSS Feed',\n],\n\nwarning Note that this feature requires that a site url is set!\n\n### Authors\n\nHyde has support for adding authors in front matter, for example to\nautomatically add a link to your website or social media profiles.\nHowever, it's tedious to have to add those to each and every\npost you make, and keeping them updated is even harder.\n\nYou can predefine authors in the Hyde config.\nWhen writing posts, just specify the username in the front matter,\nand the rest of the data will be pulled from a matching entry.\n\n#### Example\n\n\/\/ torchlight! {\"lineNumbers\": false}\n'authors' => [\n Author::create(\n username: 'mr_hyde', \/\/ Required username\n name: 'Mr. Hyde', \/\/ Optional display name\n website: 'https:\/\/hydephp.com' \/\/ Optional website URL\n ),\n],\n\nThis is equivalent to the following front matter in a blog post:\n\nauthor:\n username: mr_hyde\n name: Mr. Hyde\n website: https:\/\/hydephp.com\n\nBut you only have to specify the username:\n\nauthor: mr_hyde\n\n### Footer\n\nMost websites have a footer with copyright details and contact information. You probably want to change the Markdown to include your information, though you are of course welcome to keep the default attribution link!\n\nThe footer component is made up of a few levels of components, depending on how much you want to customize.\n\n#### Customizing the Markdown text\n\nThere are two ways to customize the footer text. First, you can set it in the configuration file:\n\n\/\/ filepath: config\/hyde.php\n'footer' => 'Site proudly built with HydePHP \ud83c\udfa9',\n\nIf you don't want to write Markdown in the configuration file, you can create a Markdown file in your includes directory. When this file is found, it will be used instead of the configuration setting.\n\n\/\/ filepath: resources\/includes\/footer.md\nSite proudly built with HydePHP \ud83c\udfa9\n\nIn both cases the parsed Markdown will be rendered in the footer Blade component.\n\n#### Customizing the Blade component\n\nThe actual footer component is rendered using the layouts\/footer.blade.php Blade template.\n\nIn this template we automatically render the configured footer Markdown text. If you want to change this behaviour, for example, HydePHP.com uses a more sophisticated footer, simply publish the footer component.\n\n#### Disabling the footer entirely\n\nIf you don't want to have a footer on your site, you can set the 'footer' configuration option to false.\n\n\/\/ filepath: config\/hyde.php\n'footer' => 'false',\n\n### Navigation Menu & Sidebar\n\nA great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation.\nHyde is designed to automatically configure these menus for you based on the content you have in your project.\n\nStill, you will likely want to customize some parts of these menus, and thankfully, Hyde makes it easy to do so.\n\n#### Customizing the navigation menu\n\n- To customize the navigation menu, use the setting navigation.order in the hyde.php config.\n- When customizing the navigation menu, you should use the route key of the page.\n\nLearn more in the Navigation Menu documentation.\n\n#### Customizing the documentation sidebar\n\n- To customize the sidebar, use the setting sidebar_order in the docs.php config.\n- When customizing the sidebar, can use the route key, or just the page identifier of the page.\n\nLearn more in the Documentation Pages documentation.\n\ninfo Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key.\n\n### Primer on priorities\n\nAll navigation menu items have an internal priority value that determines its order in the navigation.\nLower values means that the item will be higher up in the menu. The default for pages is 999 which puts them last.\nHowever, some pages are autoconfigured to have a lower priority, for example, the index page defaults to a priority of 0,\n\n#### Basic syntax for changing the priorities\n\nThe 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.\nThe offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings.\n\n[\n 'readme', \/\/ Gets priority 500\n 'installation', \/\/ Gets priority 501\n 'getting-started', \/\/ Gets priority 502\n]\n\n#### Explicit syntax for changing the priorities\n\nYou can also specify explicit priorities by adding a value to the array key:\n\n[\n 'readme' => 10, \/\/ Gets priority 10\n 'installation' => 15, \/\/ Gets priority 15\n 'getting-started' => 20, \/\/ Gets priority 20\n]\n\nYou can also combine these options if you want:\n\n[\n 'readme' => 10, \/\/ Gets priority 10\n 'installation', \/\/ Gets priority 500\n 'getting-started', \/\/ Gets priority 501\n]\n\nYou can also set the priority of a page directly in the front matter. This will override any dynamically inferred or\nconfig defined priority. While this is useful for one-offs, it can make it harder to reorder items later on.\nIt's up to you which method you prefer to use. This setting can be used both for the navigation menu and the sidebar.\n\nnavigation:\n priority: 25\n\n#### Changing the menu item labels\n\nHyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles.\nYou can override the label using the navigation.label front matter property.\n\nFrom the Hyde config you can also override the label of navigation links using the by mapping the route key\nto the desired title. Note that the front matter property will take precedence over the config property.\n\n\/\/ filepath config\/hyde.php\n'navigation' => [\n 'labels' => [\n 'index' => 'Start',\n 'docs\/index' => 'Documentation',\n ]\n]\n\n#### Excluding Items (Blacklist)\n\nSometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu.\nTo remove items from being automatically added, simply add the page's route key to the blacklist.\nAs you can see, the 404 page has already been filled in for you.\n\n\/\/ filepath config\/hyde.php\n'navigation' => [\n 'exclude' => [\n '404'\n ]\n]\n\nYou can also specify that a page should be excluded by setting the page front matter.\n\nnavigation:\n hidden: true\n\n#### Adding Custom Navigation Menu Links\n\nYou can easily add custom navigation menu links similar how we add Authors. Simply add a NavItem model to the navigation.custom array.\n\nWhen linking to an external site, you should use the NavItem::forLink() method facade. The first two arguments are the\ndestination and label, both required. Third argument is the priority, which is optional, and defaults to 500.\n\n\/\/ filepath config\/hyde.php\nuse Hyde\\Framework\\Features\\Navigation\\NavItem;\n\n'navigation' => [\n 'custom' => [\n NavItem::forLink('https:\/\/github.com\/hydephp\/hyde', 'GitHub', 200),\n ]\n]\n\nSimplified, this will then be rendered as follows:\n\nGitHub\n\n#### Automatic navigation menu dropdowns\n\nHydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories.\n\nFor pages that can be in the main site menu, ths feature needs to be enabled in the hyde.php config file.\n\n\/\/ filepath config\/hyde.php\n\n'navigation' => [\n 'subdirectories' => 'dropdown',\n],\n\nNow if you create a page called _pages\/about\/contact.md it will automatically be placed in a dropdown called \"About\".\n\n#### Automatic documentation sidebar grouping\n\nThis feature works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups.\nThis feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped.\n\nFor example: _docs\/getting-started\/installation.md will be placed in a group called \"Getting Started\".\n\n## Additional Advanced Options\n\nThe following configuration options in the confg\/hyde.php file are intended for advanced users and \nshould only be modified if you fully understand their impact. The code examples show the default values.\n\n### media_extensions\n\nThis option allows you to specify file extensions considered as media files, which will be copied to the output directory. \nTo add more extensions, either append them to the existing array or override the entire array.\n\n\/\/ filepath config\/hyde.php\nuse \\Hyde\\Support\\Filesystem\\MediaFile;\n\n'mediaextensions' => arraymerge([], MediaFile::EXTENSIONS),\n\n### safeoutputdirectories\n\nThis setting defines a list of directories deemed safe to empty during the site build process as a safeguard to prevent accidental data loss.\nIf the site output directory is not in this list, the build command will prompt for confirmation before emptying it. It is preconfigured\nwith common directories including the default one, but you are free to change this to include any custom directories you may need.\n\n\/\/ filepath config\/hyde.php\n'safeoutputdirectories' => ['_site', 'docs', 'build'],\n\n### generatebuildmanifest\n\nDetermines whether a JSON build manifest with metadata about the build should be generated. Set to true to enable.\n\n\/\/ filepath config\/hyde.php\n'generatebuildmanifest' => true,\n\n### buildmanifestpath\n\nSpecifies the path where the build manifest should be saved, relative to the project root.\n\n\/\/ filepath config\/hyde.php\n'buildmanifestpath' => 'app\/storage\/framework\/cache\/build-manifest.json',\n\n### hydefrontversion and hydefrontcdn_url\n\nThese options allow you to specify the HydeFront version and CDN URL when loading app.css from the CDN.\n\nOnly change these if you know what you're doing as some versions may incompatible with your Hyde version.\n\n\/\/ filepath config\/hyde.php\nuse \\Hyde\\Framework\\Services\\AssetService;\n\n'hydefrontversion' => AssetService::HYDEFRONTVERSION,\n'hydefrontcdnurl' => AssetService::HYDEFRONTCDNURL,\n\n## Blade Views\n\nHyde uses the Laravel Blade templating engine. Most parts of the included templates have been extracted into components to be customized easily.\nBefore editing the views you should familiarize yourself with the Laravel Blade Documentation.\n\nTo edit a default Hyde component you need to publish them first using the hyde publish:views command.\n\nphp hyde publish:views\n\nThe files will then be available in the resources\/views\/vendor\/hyde directory.\n\n## Frontend Styles\n\nHyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template\nfor you to get up and running quickly. If you want to customize these, you are free to do so.\nPlease see the Managing Assets page to learn more.\n\n## Markdown Configuration\n\nHyde uses League CommonMark for converting Markdown into HTML, and\nuses the GitHub Flavored Markdown extension. The Markdown related settings are found in the config\/markdown.php file.\nBelow follows an overview of the Markdown configuration options available in Hyde.\n\n### CommonMark Extensions\n\nYou can add any extra CommonMark Extensions,\nor change the default ones, using the extensions array in the config file. They will then automatically be loaded into\nthe CommonMark converter environment when being set up by Hyde.\n\n\/\/ filepath: config\/markdown.php\n'extensions' => [\n \\League\\CommonMark\\Extension\\GithubFlavoredMarkdownExtension::class,\n \\League\\CommonMark\\Extension\\Attributes\\AttributesExtension::class,\n],\n\nRemember that you may need to install any third party extensions through Composer before you can use them.\n\n### CommonMark Configuration\n\nIn the same file you can also change the configuration values to be passed to the CommonMark converter environment.\nHyde handles many of the options automatically, but you may want to override some of them and\/or add your own.\n\n\/\/ filepath: config\/markdown.php\n'config' => [\n 'disallowedrawhtml' => [\n 'disallowed_tags' => [],\n ],\n],\n\nSee the CommonMark Configuration Docs for the available options.\nAny custom options will be merged with the defaults.\n\n### Allow Raw HTML\n\nSince Hyde uses GitHub Flavored Markdown,\nsome HTML tags are stripped out by default. If you want to allow all arbitrary HTML tags, and understand the risks involved,\nyou can use the allow_html setting to enable all HTML tags.\n\n\/\/ filepath: config\/markdown.php\n'allow_html' => true,\n\n### Allow Blade Code\n\nHydePHP also allows you to use Blade code in your Markdown files. This is disabled by default, since it allows\narbitrary PHP code specified in Markdown to be executed. It's easy to enable however, using the enable_blade setting.\n\n\/\/ filepath: config\/markdown.php\n'enable_blade' => true,\n\nSee the Blade in Markdown documentation for more information on how to use this feature.\n\n## YAML Configuration\n\nThe settings in the config\/hyde.php file can also be set by using a hyde.yml file in the root of your project directory.\n\nNote that YAML settings cannot call any PHP functions, so you can't access helpers like env() for environment variables,\nnor declare authors or navigation links, as you cannot use facades and objects. But that doesn't stop you from using both\nfiles if you want to. Just keep in mind that any duplicate settings in the YAML file override any made in the PHP file.\n\nHere is an example showing some of the config\/hyde.php file settings, and how they would be set in the YAML file.\n\n# filepath hyde.yml\nname: HydePHP\nurl: \"http:\/\/localhost\"\npretty_urls: false\ngenerate_sitemap: true\nrss:\n enabled: true\n filename: feed.xml\n description: HydePHP RSS Feed\nlanguage: en\noutputdirectory: site\n\n### Namespaced YAML Configuration\n\nIf you are running v1.2 or higher, you can also use namespaced configuration options in the YAML file.\n\nThis allows you to set the settings of any configuration file normally found in the config directory.\n\nThis feature is automatically enabled when you have a hyde: entry first in your hyde.yml file\n\n# filepath hyde.yml\nhyde:\n name: HydePHP\n\ndocs:\n sidebar:\n header: \"My Docs\"\n\nThis would set the name setting in the config\/hyde.php file, and the sidebar.header setting in the config\/docs.php file.\n\nEach top level key in the YAML file is treated as a namespace, and the settings are set in the corresponding configuration file.\nYou can of course use arrays like normal even in namespaced configuration.","destination":"customization.html"},{"slug":"navigation","title":"Navigation","content":"Navigation","destination":"navigation.html"},{"slug":"troubleshooting","title":"Troubleshooting","content":"# Troubleshooting\n\nSince Hyde has a lot of \"magic\" features which depend on some base assumptions,\nthere might be some \"gotchas\" you might run into. Here are some I can think of,\ndid you find a new one? Send a PR to update the docs!\n\ninfo Tip: You can run php hyde validate to run a series of tests to help you catch common issues.\n\n## General Tips\n\n(In no particular order of importance)\n\n1. In general, Hyde is actually pretty forgiving. While this article makes it sound like there are a lot of rules to follow,\n honestly don't worry about it. Hyde will attempt to fix mistakes and make your life easier.\n2. You don't need to set an H1 heading in blog posts. The H1 is set by Hyde based on the front matter title.\n3. You never need front matter, though it is often useful.\n For example, Hyde makes attempts to guess the title for a page depending on the content. (Headings, filenames, etc).\n\n## Conventions to follow\n\n### File naming\n\nFor Hyde to be able to discover your files, you should follow the following conventions.\n\nMarkdown files should have the extension .md. Blade files should have the extension .blade.php.\n\nUnexpected behaviour might occur if you use conflicting file names.\nAll the following filenames are resolved into the same destination file:\nfoo-bar.md, Foo-Bar.md, foo-bar.blade.php, causing only one of them to be saved.\n\nRemember, files retain their base filenames when compiled to HTML.\n\n#### Summary\n\n- \u2714 Do use lowercase filenames and extensions\n- \u2714 Do use filenames written in kebab-case-format\n- \u2714 Do use the proper file extensions\n- \u274c Don't use conflicting source file names\n\n## Extra Information\n\n### Definitions\n\nWe will use the following definitions to describe the behaviour of Hyde.\n\n#### General\n\nHyde**: The application that you are using.\nHydeCLI**: The command-line interface for Hyde.\nFramework**: The package containing the core codebase.\n\n#### Path components\n\nIdentifier**: The filepath without the extension, relative to the page type source directory.\nRoute Key**: The page type's output directory plus the identifier. Example: posts\/hello-world\nBasename**: The filename without the extension. Example: hello-world\nFilename**: The full name of a file with the extension. Example: hello-world.md\nFilepath**: The full file path including extension. Example: _posts\/hello-world.md\n\nYou can read more about some of these in the Core Concepts article.\n\n## Common issues, causes, and solutions\n\nIssue Possible Cause \/ Issue Context Possible Solution\n\n404 error when visiting site Are you missing an index file in the pages directory? Add an index.md or index.blade.php to the pages directory\nNavigation menu not linking to the docs You probably don't have an index.md file in the docs directory. Create a docs\/index.md file\nPage not discovered when compiling The file name may be invalid Ensure you follow the correct file naming convention.\nPage compiles slowly The Torchlight extension may cause the compile times to increase as API calls need to be made. Try disabling Torchlight\nTorchlight not working Missing Composer package, missing API token, extension disabled in the config. Reinstall Torchlight, add your token in the .env file, check config\nMissing styles and\/or assets You may have accidentally deleted the files, or you have added new Tailwind classes. Run npm run dev\nImage not found You may be using a bad relative path. Ensure your relative paths are correct. See managing-assets.\nWrong layout used Hyde determines the layout template to use depending on the directory of the source file Ensure your source file is in the right directory.\nInvalid\/no permalinks or post URIs You may be missing or have an invalid site URL Set the site URL in the .env file\nNo styles in custom Blade pages When using custom blade pages need to add the styles yourself. You can do this by extending the default layout Use the app layout, or by include the Blade components directly.\nOverriding Hyde views is not working Ensure the Blade views are in the correct directory. Rerun php hyde publish:views.\nStyles not updating when deploying site It could be a caching issue. To be honest, when dealing with styles, it's always a caching issue. Clear your cache, and optionally complain to your site host\nDocumentation sidebar items are in the wrong order Double check the config, make sure the route keys are written correctly. Check that you are not overriding with front matter. Check config for typos and front matter\nDocumentation table of contents is weird The table of contents markup is generated by the League\/CommonMark extension Make sure that your Markdown headings make sense\nIssues with date in blog post front matter The date is parsed by the PHP strtotime() function. The date may be in an invalid format, or the front matter is invalid Ensure the date is in a format that strtotime() can parse. Wrap the front matter value in quotes.\nRSS 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.\nSitemap 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.\nUnable 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.\nNamespaced 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`\n\n### Extra troubleshooting information\n\n#### Fixing a broken config\n\nIf your configuration is broken, you might not be able to run any commands through the HydeCLI.\nTo remedy this you can copy the config files from the vendor directory into the project directory.\nYou can do this manually, or with the following rescue command:\n\ncopy vendor\/hyde\/framework\/config\/hyde.php config\/hyde.php","destination":"troubleshooting.html"},{"slug":"updating-hyde","title":"Updating Hyde Projects","content":"Updating Hyde Projects\n\nThis guide will help you update your HydePHP project to the latest version.\n\nBefore you start\n\nWhen updating an existing installation, first ensure that you have a backup of your project in case anything goes wrong.\nThe recommended way to do this is to use Git as that allows you to smoothly roll back any changes.\n\nVersion compatibility\n\nHydePHP follows semantic versioning, so you can expect that minor and patch releases will be backwards compatible.\nOnly major releases may introduce breaking changes, all of which are thoroughly documented in the accompanying release notes.\n\nNew features and bug fixes are added in minor and patch releases, so it is recommended to keep your project up to date.\n\nSide effects and ensuring a smooth update\n\nPlease note that due to the intricate nature of software, there is a possibility that an update contains side effects,\nhence why version controlling your site is helpful when updating versions as you can roll back changes. It can also\nbe helpful to version control the compiled HTML, so you can view a diff of the changes. Be sure to test that your site\ncan be built and that it looks as expected after updating before deploying the changes to your live site.\n\nWe of course have extensive tests in place run on each single code commit to ensure all code is functional, however,\nit is still possible that some edge cases slip through. This means that a bug fix may impact an edge case that you depend on.\n\nObligatory related XKCD: https:\/\/xkcd.com\/1172\n\nMethods\n\nWhich method?\n\nDepending on how you installed Hyde, there are a few different ways to update it.\n\nWe have a few methods documented here. The Git method is recommended as it is the easiest and safest way to\nupdate your project. If you are not using Git, you can still update your project using any of the manual methods.\n\nRegardless of the method you use, make sure you follow the post-update instructions at the end.\n\nUpdating just the Framework\n\nIf you just want to update the framework patch version, you can do so by running the following command:\n\ncomposer update hyde\/framework\n\nWhile the same can still be done for minor versions, it's best to also update your project scaffolding and resources to\nensure that everything is up to date, for which you should use the methods below.\n\nUsing Git\n\nFirst, make sure you have a remote set up for the base project repository.\n\ngit remote add upstream https:\/\/github.com\/hydephp\/hyde.git\n\nThen pull the latest release from the upstream repository.\n\ngit pull upstream master\n\nAfter this, you should update your composer dependencies:\n\ncomposer update\n\nNext, follow the post-update instructions.\n\nManual Update\n\nIf you are not using Git, you can still update your project. This is a bit more involved, but it is still possible.\n\n1. First, you will need to download the latest release archive from the releases page.\n2. Then extract the archive, and copy the contents into your project directory.\n\nSince this may overwrite modified files, it may be safer to use the hard update method.\n\nHard Update\n\nIf you are having trouble updating your project, you can try a hard update. In short, this approach consists of creating\na brand new project and copying over only your source and resource files. If you do not want to use Git, this may be\nthe safest option as you won't be overriding any of your existing files.\n\nIf you have changed any other files, for example in the App directory, you will need to update those files manually as well.\nThe same goes if you have created any custom Blade components or have modified Hyde ones.\n\nHere is an example CLI workflow, but you can do the same using a graphical file manager.\n\nmv my-project my-project-old\ncomposer create-project hyde\/hyde my-project\n\ncp -r my-old-project\/pages my-project\/content\/pages\ncp -r my-old-project\/posts my-project\/content\/posts\ncp -r my-old-project\/media my-project\/content\/media\ncp -r my-old-project\/docs my-project\/content\/docs\ncp -r my-old-project\/config my-project\/config\n\nNext, follow the post-update instructions. After verifying that everything is working, you can delete the old project directory.\n\nPost-update instructions\n\nAfter updating Hyde you should update your config and resource files. This is where things can get a tiny bit dangerous\nas existing files may be overwritten. If you are using Git, you can easily take care of any merge conflicts that arise.\n\nFirst, ensure that your dependencies are up to date. If you have already done this, you can skip this step.\n\ncomposer update\n\nThen, update your config files. This is the hardest part, as you may need to manually copy in your own changes.\n\nphp hyde publish:configs\n\nIf you have published any of the included Blade components you will need to re-publish them.\n\nphp hyde publish:views layouts\nphp hyde publish:views components\n\nNext, recompile your assets, if you are not using the built-in assets.\n\nnpm install\nnpm run dev\/prod\n\nFinally, you can rebuild your site.\n\nphp hyde build\n\nNow, you should browse your site files to ensure things are still looking as expected.","destination":"updating-hyde.html"},{"slug":"extensions","title":"Extensions & Integrations","content":"Extensions & Integrations\n\nHydePHP - Extensible by design\n\nHydePHP is designed to be extensible, and comes with a number of built-in extensions and integrations,\nas well as support for third-party extensions and integrations.\n\nFirst party extensions & integrations\n\nRealtime Compiler\n\nThe Hyde Realtime Compiler is included with Hyde installations and is what powers the php hyde serve command.\n- Learn more about the Realtime Compiler in the documentation.\n\nUI Kit\n\nThe HydePHP UI Kit is a set of minimalistic Blade & Tailwind components to kickstart development of custom Blade views for your HydePHP site.\n- Learn more at https:\/\/github.com\/hydephp\/ui-kit and see the documentation at https:\/\/hydephp.github.io\/ui-kit\n\nGitHub Action\n\nThe GitHub Action for HydePHP is hands-down the easiest way to build and deploy your Hyde site to GitHub Pages.\n- Learn more at https:\/\/github.com\/hydephp\/action and see the documentation at https:\/\/hydephp.github.io\/action\n\nIntegrations with third-party tools\n\nTorchlight\n\nTorchlight is an amazing API for syntax highlighting, and is supported natively by HydePHP.\n- Learn more about Torchlight in the documentation.\n\nContribute\n\nHave an idea for an extension or integration? Let me know! I'd love to hear from you. Get in touch on\nGitHub or send me a DM on Twitter.\nYou may also want to look at the Extension API documentation to learn how to create extensions.","destination":"extensions.html"},{"slug":"realtime-compiler","title":"Realtime Compiler","content":"Realtime Compiler\n\nThe Hyde Realtime Compiler is included with Hyde installations and is what powers the php hyde serve command,\nallowing you to preview your static site on a local development server without having to rebuild the site.\n\nUsage\n\nTo start the server, run the following command from a terminal in your project directory:\n\nphp hyde serve\n\nThis will start a local development server at http:\/\/localhost:8080\n\nwarning Please note that the server is designed for local development, and should not be used on a public network.\n\nConfiguration\n\nThe server can be configured in the config\/hyde.php file to change the port, host, and to customize its features.\n\n\/\/ filepath config\/hyde.php\n\n'server' => [\n 'port' => env('SERVER_PORT', 8080),\n 'host' => env('SERVER_HOST', 'localhost'),\n 'save_preview' => true,\n],\n\nLive dashboard\n\nUsage\n\nThe realtime compiler comes with a live dashboard that you can access at http:\/\/localhost:8080\/dashboard.\n\nFrom here, you can visually interact with your site content, including creating new pages and posts.\n\nThe live dashboard is not saved to your static site, and is only available through the development server.\n\nConfiguration\n\nThe dashboard can be customized, and disabled, in the config\/hyde.php file.\n\n\/\/ filepath config\/hyde.php\n\n'server' => [\n 'dashboard' => [\n 'enabled' => env('SERVER_DASHBOARD', true),\n 'interactive' => true,\n 'tips' => true,\n ],\n],\n\nThe dashboard was added in Realtime Compiler v3.0.0 (March 2023), with interactive features added in v3.1.0 (October 2023)\n\nLive edit\n\nUsage\n\nThe live edit feature allows you to quickly edit Markdown-based pages (posts, docs, and pages) directly in the browser.\n\nTo enter the live editor, simply double-click on the article you want to edit, and it will be replaced with a text editor.\nWhen you're done, click the save button to save the changes to the page's source file.\n\nShortcuts\n\nThe live editor supports the following keyboard shortcuts:\n- Ctrl + E - Enter\/Exit editor\n- Ctrl + S - Save changes\n- esc - Exit editor if active\n\nConfiguration\n\nThe live editor can be disabled in the config\/hyde.php file.\nThe live editor plugin code will not be saved to your static site.\n\n\/\/ filepath config\/hyde.php\n\n'server' => [\n 'liveedit' => env('SERVERLIVE_EDIT', true),\n],\n\nThe live editor was added in Hyde Realtime Compiler Server v3.2.0 (December 2023)\n\nSource code\n\nGitHub**: hydephp\/realtime-compiler\nPackagist**: hydephp\/realtime-compiler","destination":"realtime-compiler.html"},{"slug":"third-party-integrations","title":"Integrations with third-party tools","content":"Integrations with third-party tools\n\nTorchlight\n\nTorchlight is an amazing API for syntax highlighting, and is used by this site. I cannot recommend it highly enough,\nespecially for documentation sites and code-heavy blogs! As such, HydePHP has built-in support for Torchlight,\nwhich is automatically enabled once you add an API token to your .env file. Nothing else needs to be done!\n\nGetting started\n\nTo get started you need an API token which you can get at Torchlight.dev.\nIt is entirely free for personal and open source projects, as seen on their pricing page.\n\nWhen you have an API token, set it in the .env file in the root directory of your project.\nOnce a token is set, Hyde will automatically enable the CommonMark extension.\n\nTORCHLIGHTTOKEN=torch\n\nAttribution and configuration\n\nNote that for the free plan you need to provide an attribution link. Thankfully Hyde injects a customizable link\nautomatically to all pages that use Torchlight. You can of course disable and customize this in the config\/torchlight.php file.\n\n'attribution' => [\n 'enabled' => true,\n 'markdown' => 'Syntax highlighting by Torchlight.dev',\n],\n\nDon't have this file? Run php hyde vendor:publish to publish it.","destination":"third-party-integrations.html"},{"slug":"ui-kit","title":"HydePHP UI Kit - Documentation","content":"HydePHP UI Kit - Documentation\n\nThe HydePHP UI Kit is a collection of minimalistic and un-opinionated TailwindCSS components for Laravel Blade,\nindented to be used with HydePHP. Note that these components may require CSS classes not present in the bundled app.css\nfile and that you may need to recompile the CSS file using the included Laravel Mix configuration.\n\nScreenshot\n\nHere are some of the components you can use to build your next project! As you can see, all components support both light and dark mode out of the box, just like the rest of HydePHP.\n\nComponents Screenshot\n\nComponents\n\nPlease make sure you're familiar with Laravel Blade before using the HydePHP UI Kit.\n\ninfo Tip: Most components allow you to pass any additional HTML attributes to the element!\n\nButtons\n\nPrimary\n\n Primary Button\n\nSecondary\n\n Secondary Button\n\nInput\n\nThe base component is ``, any additional attributes will be passed to the input element as seen below.\n\nCard\n\nAn incredibly versatile component that can be used for a wide variety of purposes.\n\nIn the most basic form, a card is just a container with a white background and a shadow.\nHowever, it also supports two slots: title and footer.\n\n A card with some content.\n\n \n Card Title\n \n\n \n Some footer content.\n \n\nWhy not combine the components?\n\n \n My Amazing Card\n \n\n A card with some content and a footer with a button.\n\n \n \n Primary Button\n \n \n\nTypography Components\n\nHeading\n\nThis component will create a styled `` level heading centred on the page.\n\n Lorem ipsum dolor sit amet.\n\nProse\n\nThis simple component will create an `` element with TailwindCSS Typography (prose) styles applied.\n\n Prose Heading\n Prose paragraph\n\nMarkdown\n\nThis component will convert any Markdown within it to HTML using the Hyde Markdown compiler.\n\nMarkdown Heading\n\n Hello world!\n\ninfo Tip: You may also want to wrap this in the prose element or the Markdown will not be styled.\n\nWhat's Next?\n\nThe UI kit is minimal by design. It's up to you to create something amazing, we just want to give you a head start.\nYou can get surprisingly far when you combine the components. Take this newsletter signup card for example!\n\n \n Let your creativity flow!\n \n\n \n \n \n The UI kit is minimal by design. It's up to you to create something amazing.\n\n Maybe create a form to collect newsletter subscriptions?\n \n \n \n\n \n \n\n \n Subscribe\n \n \n\nNewsletter Screenshot\n\nGitHub Repository\n\nYou can find the source code for the UI Kit on GitHub at hydephp\/ui-kit.","destination":"ui-kit.html"},{"slug":"console-commands","title":"Console Commands","content":"# Console Commands\n\nThe primary way of interacting with Hyde is through the command line using the HydeCLI.\n\nIf you have ever used the Artisan Console in Laravel you will feel right at home,\nthe HydeCLI is based on Artisan after all!\n\n## Introduction\n\nTo use the HydeCLI, run php hyde from your project directory followed by a command.\n\nAll HydeCLI commands start with php hyde. Anything in [brackets] is optional.\nIf an argument or option value has a space in it, it needs to be wrapped in quotes.\n\nThe HydeCLI exists at the root of your application as the hyde script and provides a number of helpful commands that can\nassist you while you build your site. To view a list of all available Hyde commands, you may use the list command:\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde list\n\n### Got stuck? The CLI can help.\n\nEvery command also includes a \"help\" screen which displays and describes the command's available arguments and options.\nTo view a help screen, precede the name of the command with help:\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde help \n\nYou can also always add --help to a command to show detailed usage information.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde --help\n\n## Available Commands\n\nHere is a quick reference of all the available commands. You can also run php hyde list to see this list.\n\nCommand Description\n\nbuild Build the static site\nserve Start the realtime compiler server\nrebuild Run the static site builder for a single file\nbuild:rss Generate the RSS feed\nbuild:search Generate the docs\/search.json file\nbuild:sitemap Generate the sitemap.xml file\nmake:page Scaffold a new Markdown, Blade, or documentation page file\nmake:post Scaffold a new Markdown blog post file\npublish:configs Publish the default configuration files\npublish:homepage Publish one of the default homepages as index.blade.php\npublish:views Publish the hyde components for customization. Note that existing files will be overwritten\nvendor:publish Publish any publishable assets from vendor packages\nroute:list Display all registered routes\nvalidate Run a series of tests to validate your setup and help you optimize your site\nlist List all available commands\n\n## Build the static site\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build [--run-dev] [--run-prod] [--run-prettier] [--pretty-urls] [--no-api]\n\nBuild the static site\n\n#### Options\n\n\n\n--run-dev Run the NPM dev script after build\n--run-prod Run the NPM prod script after build\n--run-prettier Format the output using NPM Prettier\n--pretty-urls Should links in output use pretty URLs?\n--no-api Disable API calls, for example, Torchlight\n\n## Run the static site builder for a single file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde rebuild \n\nRun the static site builder for a single file\n\n#### Arguments\n\n\n\npath The relative file path (example: \\_posts\/hello-world.md) \\n - Is required: yes\n\n## Start the realtime compiler server\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde serve [--host [HOST]] [--port [PORT]]\n\nStart the realtime compiler server.\n\n#### Options\n\n\n\n--host= [default: \"localhost\"]\n--port= [default: 8080]\n\n## Test and validate your project to optimize your site\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde validate\n\nRun a series of tests to validate your setup and help you optimize your site.\n\n## Generate the RSS feed\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build:rss\n\nGenerate the RSS feed\n\n## Generate the docs\/search.json file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build:search\n\nGenerate the docs\/search.json file\n\n## Generate the sitemap.xml file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build:sitemap\n\nGenerate the sitemap.xml file\n\n## Scaffold a new Markdown, Blade, or documentation page file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde make:page [--type [TYPE]] [--blade] [--docs] [--force] [--] []\n\nScaffold a new Markdown, Blade, or documentation page file\n\n#### Arguments & Options\n\n\n\ntitle The name of the page file to create. Will be used to generate the filename\n--type=markdown The type of page to create (markdown, blade, or docs)\n--blade Create a Blade page\n--docs Create a Documentation page\n--force Overwrite any existing files\n\n## Scaffold a new Markdown blog post file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde make:post [--force] [--] []\n\nScaffold a new Markdown blog post file\n\n#### Arguments & Options\n\n\n\ntitle The title for the Post. Will also be used to generate the filename\n--force Should the generated file overwrite existing posts with the same filename?\n\n## Publish the default configuration files\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde publish:configs\n\nPublish the default configuration files\n\n## Publish one of the default homepages as index.blade.php.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde publish:homepage [--force] [--] []\n\nPublish one of the default homepages as index.blade.php.\n\n#### Arguments & Options\n\n\n\nhomepage The name of the page to publish\n--force Overwrite any existing files\n\n## Publish the hyde components for customization\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde publish:views []\n\nPublish the hyde components for customization. Note that existing files will be overwritten.\n\n#### Arguments\n\n\n\ncategory The category to publish\n\n## Display all registered routes.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde route:list\n\nDisplay all registered routes.\n\n## Publish any publishable assets from vendor packages\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde vendor:publish [--existing] [--force] [--all] [--provider [PROVIDER]] [--tag [TAG]]\n\nPublish any publishable assets from vendor packages\n\n#### Options\n\n\n\n--existing Publish and overwrite only the files that have already been published\n--force Overwrite any existing files\n--all Publish assets for all service providers without prompt\n--provider= The service provider that has assets you want to publish\n--tag= One or many tags that have assets you want to publish \\n- Is multiple: yes","destination":"console-commands.html"},{"slug":"core-concepts","title":"Core HydePHP Concepts","content":"Core HydePHP Concepts\n\nIntroduction to the Hyde Framework\n\nWhat makes HydePHP special are its \"magic\" features like autodiscovery and intelligent data generation.\nAll designed so that you can focus on your content, while the framework does the heavy lifting.\n\nThis page provides a high-level overview of the framework's capabilities, so you can quickly grasp its benefits.\nAs you delve deeper into the documentation, you'll discover the details of each feature and learn how to leverage them effectively.\n\nThe HydeCLI\n\nWhen you are not writing Markdown and Blade, most of your interactions with Hyde will be through the command line\nusing the HydeCLI, which is based on the Laravel Artisan Console that you may already be familiar with.\n\nIf you want to learn about the available commands and how to use them, you can visit the Console Commands page,\nor you can run any of the built-in help commands to get a list of available commands and their descriptions.\n\nphp hyde list\nphp hyde help \nphp hyde [--help]\n\nDirectory structure\n\nTo take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure.\n\nDirectory Purpose\n\n_docs For documentation pages\n_posts For blog posts\n_pages For static Markdown and Blade pages\n_media Store static assets to be copied to the build directory\n_site The build directory where your compiled site will be stored\nconfig Configuration files for Hyde and integrations\nresources\/assets Location for Laravel Mix source files (optional)\nresources\/views Location for Blade components (optional)\napp Location for custom PHP classes (optional)\n\nPage Models\n\nThe Hyde page models are an integral part of how HydePHP creates your static site. Each page in your site is represented\nby a page model. These are simply PHP classes that in addition to holding both the source content and computed data\nfor your pages, also house instructions to Hyde on how to parse, process, and render the pages to static HTML.\n\nThe page classes are very important and fill two roles:\n\n1. They act as blueprints containing static instructions for how to parse, process, and, render pages.\n2. Each class instance also holds the page source contents, as well as the computed data.\n\nTo learn more, you can visit the Page Models page.\n\nFile Autodiscovery\n\nContent files, meaning source Markdown and Blade files, are automatically discovered by Hyde and compiled to HTML when\nbuilding the site. This means that you don't need to worry about routing and controllers!\n\nThe directory a source file is in will determine the Blade template that is used to render it.\n\nAll source and output directories are configurable, but the defaults are as follows:\n\nPage\/File Type Source Directory Output Directory File Extensions\n\nStatic Pages pages\/ site\/ .md, .blade.php\nBlog Posts posts\/ site\/posts\/ .md\nDocumentation docs\/ site\/docs\/ .md\nMedia Assets media\/ site\/media\/ Common asset types\n\nPaths, Identifiers, and Route Keys\n\nSince HydePHP automatically discovers and compiles content files, it is important to understand how HydePHP handles paths,\nas the file names and directories they are in will directly influence how the page will be compiled.\n\nAs such, it will be helpful for you to know about the following terms:\n\nPath:** The full path to a file, including the file name, directory, and extension.\nIdentifier:** The unique identifier for a page. Unique only within the same page type.\nRoute key:** The key used to access the page in the routing system. Unique across all site pages.\n\nBoth the identifier and route key are derived from the path of the page. The identifier is the path without the file\nextension, and relative to the page type source directory. The route key is the output directory plus the identifier.\n\nThe identifier generation can be visualized as follows, where the identifier is underlined:\n\n _pages\/about\/contact.md\n\nFor a Markdown page, like the example above, the route key would be the same as the identifier, since Markdown pages are\noutput to the site root. If it was a Markdown post however, the route key would be: posts\/about\/contact.\n\nThis can be visualized as follows, assuming a blog post is stored as _posts\/hello-world.md:\n\n _site\/posts\/hello-world.html\n\nAs you can see, the route key is simply put the relative page URL, without the .html extension.\n\nConvention over Configuration\n\nHyde favours the \"Convention over Configuration\" paradigm and thus comes preconfigured with sensible defaults.\nHowever, Hyde also strives to be modular and endlessly customizable hackable if you need it.\nTake a look at the customization and configuration guide to see the endless options available!\n\nFront Matter\n\ninfo In a nutshell: Front Matter is a block of YAML containing metadata, stored at the top of a Markdown file.\n\nFront matter is heavily used in HydePHP to store metadata about pages. Hyde uses the front matter data to generate rich and dynamic content. For example, a blog post category, author website, or featured image.\n\nUsing front matter is optional, as Hyde will dynamically generate data based on the content itself. (Though any matter you provide will take precedence over the automatically generated data.)\n\nTo learn more, you can visit the Front Matter page.\n\nFront Matter in Markdown\n\nAll Markdown content files support Front Matter, and blog posts make heavy use of it. Here's what it may look like:\n\ntitle: \"My New Post\"\nauthor: \"Mr Hyde\"\ndate: \"2023-03-14\"\nMarkdown comes here\n\nLorem ipsum dolor sit amet, etc.\n\nFront Matter in Blade\n\nHydePHP has experimental support for creating front-matter in Blade templates, called BladeMatter,\nwhere code in @php directives are statically parsed into page object's front matter data where it can be accessed in your templates.\n\n@php($title = 'BladeMatter Demo') \/\/ Equivalent to title: 'BladeMatter Demo' in Yaml\n\nAutomatic Routing\n\ninfo In a nutshell: Hyde will automatically create routes for your source files.\n\nIf you've ever worked in an MVC framework, you are probably familiar with the concept of routing.\nAnd you are probably also familiar with how boring and tedious it can be. Thankfully, Hyde takes the pain out of routing by doing it for you!\n\nDuring the Autodiscovery process. Hyde will automatically discover all the content files in the source directories,\nand create routes for all of them, and store them in an index which works as a two-way link between source files and compiled files.\n\nYou can see all the routes and their corresponding source files by running the hyde route:list command.\n\nphp hyde route:list\n\nTo access routes in your code, simply use the Routes facade and specify the route key for the desired page.\n\nRoutes::get('posts\/my-post')\n\nTo learn more about the routing system, please visit the routing documentation.\n\nGlobal Page Data\n\nDuring the build of each page, Hyde will inject some data available to all Blade views. If you are not planning to write\nany custom Blade templates, you can safely ignore this section. If you are, here are the three global variables you can use:\n\n- $page: The Page Object for the current page.\n- $route: The Route Object for the current page.\n- $routeKey: The Route Key for the current page.\n\nThe $page variable is likely to the most important one, as it contains all the data for the current page.\nDepending on the page type, you will have different helpers available. But $page->matter() is likely to be very helpful.\n\nYou can see all the helpers in the Page API reference page.\n\nTerminology\n\nIn this quick reference, we'll briefly go over some terminology and concepts used in HydePHP.\nThis will help you understand the documentation and codebase better, as well as helping you know what to search for when you need help.\n\nTable of contents\n\nTools\n\n- HydePHP\n- Laravel\n- Composer\n- Tailwind CSS\n\nLanguages\n\n- Front Matter\n- Markdown\n- Blade\n- YAML\n- PHP\n- HTML\n\nGeneral Concepts\n\n- Static Sites\n- Version Control\n- Git\n\nHydePHP Features\n\n- Autodiscovery\n- Page Types\n- Page Identifiers\n- Routes\n- Route Keys\n\n[\/\/]: # (Languages and Tools)\n\nHydePHP\n\nHydePHP is a static site generator written in PHP, designed to make it easy for developers to build fast and secure websites.\nIt uses a simple directory structure and templating system to generate static websites from content files,\nand can be easily extended using PHP libraries and packages.\n\nLaravel\n\nLaravel is the PHP framework that HydePHP is built on top of. We use a specialized version called Laravel Zero,\nwhich is optimized for command-line applications.\n\nFront Matter\n\nFront Matter is a block of YAML, stored at the top of a Markdown file, enclosed by a set of triple-dashed lines.\nIt is commonly used to store metadata about the content, such as the title, author, date, etc.\n\nMarkdown\n\nMarkdown is a lightweight markup language that uses plain text formatting syntax, designed to make it easy to create\nstructured content for the web. HydePHP uses Markdown as the base for most of its content files.\n\nBlade\n\nBlade is the templating engine from Laravel, which allows developers to write clean and reusable code for the\npresentation layer of web applications. HydePHP uses Blade both for the built-in views and components,\nas well as to provide powerful templating capabilities through Blade-based pages.\n\nYAML\n\nYAML is a human-readable data serialization format used for configuration files and often used as the syntax for\nFront Matter in HydePHP content files. YAML is designed to be easily read by humans and parsed by machines,\nmaking it a popular choice for many applications and frameworks.\n\nPHP\n\nPHP is a popular server-side scripting language used for web development that can be embedded in HTML.\nHydePHP is built on top of PHP and utilizes its powerful capabilities for generating static websites.\n\nHTML\n\nHTML (Hypertext Markup Language) is the standard markup language used to create web pages and web applications.\nHydePHP uses HTML to render the static websites generated from its content files and templates.\n\nTailwind CSS\n\nTailwind CSS is a utility-first CSS framework used for rapidly building custom user interfaces.\nHydePHP supports Tailwind CSS out of the box through the built-in Blade templates,\nmaking it easy for developers to create beautiful and responsive websites without writing custom CSS.\n\nComposer\n\nComposer is a dependency manager for PHP that simplifies the process of installing and managing packages required by\nPHP applications. HydePHP uses Composer to manage its own dependencies and make it easy for users to install and use the software.\n\nStatic Sites\n\nA static website is a collection of HTML web pages that are delivered to the user's web browser exactly as they are stored\non the web server. HydePHP generates static websites, making them fast, secure, and easy to deploy.\n\nVersion Control\n\nHydePHP can be easily integrated with Git to manage website source files and track changes over time,\nas one of the many benefits with static sites is that they are designed to be version controlled.\n\nGit\n\nGit is a free and open-source distributed version control system that is widely used for software development.\nGit repositories can be hosted on GitHub, GitLab, BitBucket, or any other Git hosting service.\n\n[\/\/]: # (HydePHP Features)\n\nAutodiscovery\n\nContent files, including Markdown and Blade files, are automatically discovered and compiled to HTML during site builds.\nDuring autodiscovery, Hyde also generates dynamic data to enrich your content based on the page type.\n\nIn short the autodiscovery is split into three steps:\nFile discovery -> Page parsing -> Route generation\n\nPage Types\n\nAll pages in HydePHP are internally represented by a page object that extends the HydePage class. Each page type has its\nown page class which acts as a blueprint defining information for the framework to parse a file and generate relevant data.\n\nPage Identifiers\n\nThe page identifier is the name of the file without the file extension, relative to the page type's source directory.\nThe identifier is used to generate the route key, which is used to generate the file name for the compiled HTML file.\n\nRoutes\n\nAll pages are internally bound to a Route object, through the route key. During the build process, each route is\ncompiled to HTML using the page object's data, and saved to the output directory with a file name created from the route key.\nSince routes are generated automatically during autodiscovery, there is no need to create them manually.\n\nRoute Keys\n\nThe route key is the URL path relative to the site webroot, without the file extension. The route key is the common\nidentifier binding Page objects to Route objects, and is used to generate the file name for the compiled HTML file.\n\nRoute keys generation can be visualised as follows: \/","destination":"core-concepts.html"},{"slug":"front-matter","title":"Front Matter","content":"Front Matter\n\ninfo In a nutshell: Front Matter is a block of YAML containing metadata, stored at the top of a Markdown file.\n\nFront matter is heavily used in HydePHP to store metadata about pages. Hyde uses the front matter data to generate rich and dynamic content.\nFor example, in a blog post you may define a category, author website, or featured image. In a documentation page you may define the sidebar priority or label.\n\nUsing front matter is optional, as Hyde will dynamically generate data based on the content itself. (Though any matter you provide will take precedence over the automatically generated data.)\nWhile Hyde offers some support for front matter within Blade files, most of the time you use front matter, it will be in Markdown.\n\nFront matter syntax\n\nHere's a refresher on Yaml, and a quick reference of the syntax Hyde uses and expects:\n\nkey: value\nstring: \"quoted string\"\nboolean: true\ninteger: 100\narray:\n key: value\n key: value\n\nStrings don't need to be quoted, but it can help in certain edge cases, thus they are included here.\n\nFront Matter in Markdown\n\nAll Markdown content files support Front Matter. Blog posts for example make heavy use of it.\n\nThe specific usage and schemas used for pages are documented in their respective documentation, however, here is a primer on the fundamentals.\n\n- Front matter is stored in a block of YAML that starts and ends with a --- line.\n- The front matter should be the very first thing in the Markdown file.\n- Each key-pair value should be on its own line.\n\nTo use Front Matter, add Yaml to the top of your Markdown file:\n\ntitle: \"My New Post\"\nauthor:\n name: \"John Doe\"\n website: https:\/\/example.com\nMarkdown comes here\n\nLorem ipsum dolor sit amet, etc.\n\nFront Matter in Blade\n\nHydePHP has experimental support for creating front-matter in Blade templates, called BladeMatter.\n\nThe actual syntax does not use YAML; but instead PHP. However, the parsed end result is the same. Please note that\nBladeMatter currently does not support multidimensional arrays or multi-line directives as the data is statically parsed.\n\nTo create BladeMatter, you simply use the default Laravel Blade @php directive to declare a variable in the template.\n\n@php($title = 'BladeMatter Demo')\n\nIt will then be available through the global $page variable, $page->matter('title').\nHyde will of course also use the data for contextual autoconfiguration in the same way it would with Markdown and use the value as the page title.\n\nAnother idea is to use @php($navigation = ['hidden' => true]) if you want to hide a page from the navigation. The opportunities are limitless!","destination":"front-matter.html"},{"slug":"quickstart","title":"Quickstart Guide","content":"Quickstart Guide\n\nInstalling HydePHP using Composer\n\nThe recommended method of installing Hyde is using Composer, which installs the required dependencies on a per-project basis.\n\n\/\/ torchlight! {\"lineNumbers\": false}\ncomposer create-project hyde\/hyde\n\nRequirements\n\nHyde is based on Laravel 10\nwhich requires a minimum PHP version of 8.1.\nYou should also have Composer installed.\n\nTo use some features like compiling your own assets\nyou also need NodeJS and NPM.\n\nUsing the Hyde CLI\n\nThe main way to interact with Hyde is through the HydeCLI, a Laravel Artisan-based command-line interface. Learn more about the HydeCLI in the console commands documentation.\n\nStarting a development server\n\nTo make previewing your site a breeze you can use the realtime compiler, which builds your pages on the fly.\n\nphp hyde serve\nSimply run the serve command, and you will be able to preview your site at http:\/\/localhost:8080.\n\nCreating content\n\nDirectory structure\n\nCreating content with Hyde is easy! Simply place source files in one of the source directories,\nand Hyde will automatically discover, parse, and compile them to static HTML.\nThe directory and file extension of a source file will determine how HydePHP parses and compiles it.\nPlease see the directory structure section for more information.\n\nScaffolding files\n\nYou can scaffold blog post files using the php hyde make:post command which automatically creates the front matter, based on your input selections.\nYou can also scaffold pages with the php hyde make:page command.\n\nphp hyde make:post\nphp hyde make:page\n\nCompiling to static HTML\n\nNow that you have some amazing content, you'll want to compile your site into static HTML. Thankfully, this is as easy as executing the build command, after which your compiled site is stored in the _site directory.\n\nphp hyde build\n\nWhen building the site, Hyde will scan your source directories for files and compile them into static HTML using the appropriate layout depending\non what kind of page it is. You don't have to worry about routing as Hyde takes care of everything, including creating navigation menus!\n\nManaging assets\n\nHyde comes bundled with a precompiled and minified app.css file, containing all the Tailwind you need for the default views meaning that you don't even need to use NPM. However, Hyde is already configured to use Laravel Mix to compile your assets if you feel like there's a need to build the assets yourself. See more on the Managing Assets page.\n\nDeploying your site\n\nYou are now ready to show your site to the world! Simply copy the _site directory to your web server's document root, and you're ready to go.\n\nYou can even use GitHub Pages to host your site for free. That's what the Hyde website does, using an Actions CI workflow that automatically builds and deploys this site.\n\nFurther reading\n\nHere's some ideas of what to read next:\n\n- Architecture Concepts & Directory Structure\n- Console Commands with the HydeCLI\n- Creating Blog Posts","destination":"quickstart.html"},{"slug":"directory-structure","title":"Directory Structure","content":"Redirecting you to architecture-concepts#directory-structure","destination":"directory-structure.html"},{"slug":"getting-started","title":"Getting Started","content":"Redirecting you to quickstart","destination":"getting-started.html"},{"slug":"installation","title":"Installation","content":"Redirecting you to quickstart","destination":"installation.html"}] \ No newline at end of file +[{"slug":"README","title":"Hyde Documentation","content":"Hyde Documentation\n\nThis is the source for the HydePHP Documentation. Updates here are automatically propagated to the HydePHP.com website.\n\nThis document is not propagated to the website. It is only for the GitHub development repository.","destination":"README.html"},{"slug":"index","title":"Elegant and Powerful Static Site Generator","content":"Elegant and Powerful Static Site Generator\n\n.images-inline img { display: inline; margin: 4px 2px;}\n\nLatest Version on Packagist\nTotal Downloads on Packagist\nTest Coverage\nScrutinizer Code Quality\nPsalm Type Coverage\nLicense MIT\n{.images-inline .not-prose}\n\nAbout HydePHP\n\nHydePHP is a Static Site Generator focused on writing content, not markup. With Hyde, it is easy to create static\nwebsites, blogs, and documentation pages using Markdown and (optionally) Laravel's Blade.\n\nOperated entirely through the command-line, HydePHP provides developers with a fast and efficient way to create high-quality websites with ease.\nUnlike traditional web development frameworks, sites compiled with HydePHP don't require any server to run,\nmaking it an ideal choice for building lightweight and fast-loading websites.\n\nCompared with other static site builders, Hyde is blazingly fast and seriously simple to get started with, yet it has the\nfull power of Laravel waiting for you when you need it, as Hyde is powered by Laravel Zero, a stripped-down version of\nthe robust and popular Laravel Framework, optimized for console applications.\n\nHyde makes creating websites easy and fun by taking care of the boring stuff, like routing, writing boilerplate, and\nendless configuration. Instead, when you create a new Hyde project, everything you need to get started is already there\n-- including precompiled TailwindCSS, well-crafted Blade templates, and easy-to-use asset management.\n\nHyde was inspired by JekyllRB and is designed for developers who are comfortable writing posts in Markdown, and it requires\nvirtually no configuration out of the box as it favours convention over configuration and is preconfigured with sensible defaults.\n\nInstallation\n\nHydePHP is a command-line interface (CLI) application that is installed on a per-project basis.\n\nTo use HydePHP, your system must have PHP version 8.1 or later installed, along with Composer, and access to a terminal.\n\nThe recommended method of installation is using Composer.\n\ncomposer create-project hyde\/hyde\n\nOnce installed, you can access the HydeCLI from the project root using the hyde command.\n\nphp hyde info\n\nUsage\n\nCreating static websites with HydePHP is incredibly easy. First you need some content. You can just drop Markdown files\nin any of the source directories, or let Hyde scaffold the files for you using one of the many commands.\n\nphp hyde make:post \"My First Post\"\nphp hyde make:page \"About Me\"\n\nOnce you have some content, you can run the build command to compile the content into beautiful static HTML.\n\nphp hyde build\n\nAnd that's it, your amazing website is ready to be shared with the world!\n\nTo learn more, head over to the quickstart page.","destination":"index.html"},{"slug":"advanced-features","title":"Advanced Features in HydePHP","content":"Advanced Features in HydePHP\n\nPreface\n\nHydePHP is a simple, yet powerful, static site generator. It is designed to be easy to use and easy to extend.\n\nThis section of the documentation will cover some of the more advanced (but optional) features of the framework.\n\nPrerequisites\n\nTo fully understand the features described in these chapters, it may be beneficial to first skim through the\nArchitecture Concepts chapters, or at the very least, the Core Concepts page.\n\nYou are also expected to have a basic understanding of PHP, and object-oriented programming principles.\n\nHaving some familiarity with Laravel will also be beneficial, as HydePHP is built on top of the Laravel framework.\n\nTable of Contents\n\n[Blade]: @foreach(glob(DocumentationPage::path('advanced-features\/*.md')) as $file) {{ Hyde::makeTitle(basename($file, '.md')) }} @endforeach","destination":"advanced-features.html"},{"slug":"build-tasks","title":"Custom Build Tasks","content":"Custom Build Tasks\n\nIntroduction\n\nThe Build Task API offers a simple way to hook into the build process.\nThe build tasks are very powerful and allow for limitless customizability.\n\nThe built-in Hyde features like sitemap generation and RSS feeds are created using tasks like these.\nMaybe you want to create your own, to for example upload the site to FTP or copy the files to a public directory?\nYou can also overload the built-in tasks to customize them to your needs.\n\nGood to know before you start\n\nTypes of tasks\n\nThere are two types, PreBuildTasks and PostBuildTasks. As the names suggest, PreBuildTasks are executed before the site is built, and PostBuildTasks are executed after the site is built.\n\nTo choose which type of task you want to create, you extend either the PreBuildTask or PostBuildTask class.\nBoth of these have the exact same helpers and API available, so the only difference between them is when they are executed. The classes are otherwise identical.\n\nAbout these examples\n\nFor most of these examples we will focus on the PostBuildTasks as they are the most common.\n\nFor all these examples we assume you put the file in the App\/Actions directory, but you can put them anywhere.\n\nInteracting with output\n\nIn a way, build tasks are like micro-commands, as they can interact directly with the build commands I\/O. Please take a look at the Laravel Console Documentation for the full list of available methods.\n\nIn addition, there are some extra helpers available in the base BuildTask class that allow you to fluently format output to the console, which you will see in the examples below.\n\nCreating build tasks\n\nMinimal example\n\nHere is a minimal example to give you an idea of what we are working with.\n\nclass SimpleBuildTask extends PostBuildTask\n{\n public function handle(): void\n {\n \/\/\n }\n}\n\nAs you can see, at their core, build tasks are simple classes containing a handle() method,\nwhich as I'm sure you have guessed, is the method that is executed when the task is run by the build command.\n\nIf you want the task to run before the build, you would extend the PreBuildTask class instead.\n\nAutomatic output\n\nWhen running the build command, you will see the following output added after the build is complete.\n\n Generic build task... Done in 0.26ms\n\nAs you can see, some extra output including execution time tracking is added for us. We can of course customize all of this if we want, as you will learn a bit further down.\n\nFull example\n\nHere is a full example, with all the namespaces included, as well as the most common fluent output helpers.\n\ninfo('Hello World!');\n }\n\n public function printFinishMessage(): void\n {\n $this->line('Goodbye World!');\n }\n}\n\nYou can see a full API reference further below. But in short, the $message property is the message that runs before the task is executed, and the printFinishMessage() method is the message that runs after the task is executed.\n\nRunning this task will produce the following output:\n\n$ php hyde build\n Say hello... Hello World!\n Goodbye World!\n\nAs you can see, there is no execution time tracking here, since we overrode the printFinishMessage() method that normally prints this. You can of course call the withExecutionTime() method to add this back in. See more in the API reference below.\n\nRegistering the tasks\n\nThere are a few ways to register these tasks so Hyde can find them.\n\nThey are shown here in order of presumed convenience, but you are free to choose whichever you prefer. The latter options are more suited for extension developers.\n\nAutodiscovery registration\n\nThe easiest way to register build tasks is to not do it -- just let Hyde do it for you!\n\nAny classes that end in BuildTask.php that are stored in app\/Actions will be autoloaded and registered to run automatically.\n\nFor example: app\/Actions\/ExampleBuildTask.php.\n\nConfig file registration\n\nIf you want, you can also register build tasks of any namespace in the convenient build_tasks array which is in the main configuration file, config\/hyde.php.\n\n\/\/ filepath config\/hyde.php\n'build_tasks' => [\n \\App\\Actions\\SimpleTask::class,\n \\MyPackage\\Tasks\\MyBuildTask::class,\n],\n\nProgrammatic registration\n\ninfo This option assumes you are familiar with Laravel's service container and service providers.\n\nIf you are developing an extension, you can either instruct users register your tasks with the config option above,\nor you can register the extensions programmatically, I recommend you do this in the boot method of a service provider.\n\nThe build tasks are registered in an internal array of the BuildService class, which is bound as a singleton in the underlying Laravel service container.\nTo actually register your task, provide the fully qualified class name of the task to the BuildTaskService::registerTask() method.\n\nHere is an example of how to do this using a service provider. Though you could technically do it anywhere using the app() helper,\njust as long as it's done early enough in the application lifecycle, so it's registered before the build command is executed.\n\nclass MyServiceProvider extends ServiceProvider\n{\n public function boot(): void\n {\n $this->app->make(\\Hyde\\Framework\\Services\\BuildTaskService::class)\n ->registerTask(\\MyPackage\\Tasks\\MyBuildTask::class);\n }\n}","destination":"build-tasks.html"},{"slug":"hyde-pages","title":"HydePage API Reference","content":"# HydePage API Reference\n\nwarning This article covers advanced information, and you are expected to already be familiar with Page Models and OOP\n\n## Abstract\n\nThis page contains the full API references for the built-in HydePage classes. Most users will not need to know about\nthe inner workings of classes, but if you're interested in extending HydePHP, or just curious, this page is for you.\nIt is especially useful if you're looking to implement your own page classes, or if you are creating advanced Blade templates.\n\n### About the reference\n\nThis document is heavily based around the actual source code, as I believe the best way to understand the code is to read it.\nHowever, large parts of the code are simplified for brevity and illustration. The code is not meant to be copy-pasted, but\nrather used as a reference so that you know what to look for in the actual source code, if you want to dig deeper.\n\n#### Inheritance\n\nSince all HydePages extend the base HydePage class, those shared methods are only listed once,\nunder the HydePage class documentation which is conveniently located just below this section.\n\n### Table of Contents\n\nClass Description\n\nHydePage The base class for all Hyde pages.\nBaseMarkdownPage The base class for all Markdown pages.\nInMemoryPage Extendable class for in-memory pages.\nBladePage Class for Blade pages.\nMarkdownPage Class for Markdown pages.\nMarkdownPost Class for Markdown posts.\nDocumentationPage Class for documentation pages.\nHtmlPage Class for HTML pages.\n\n## HydePage\n\nThe base class for all Hyde pages. All other page classes extend this class.\n\nUnlike other frameworks, you generally don't instantiate pages yourself in Hyde. Instead, the page models act as\nblueprints defining information for Hyde to know how to parse a file, and what data around it should be generated.\n\nTo get a parsed file instance, you'd typically just create a source file, and you can then access the parsed file\nfrom the HydeKernel's page index.\n\nIn Blade views, you can always access the current page instance being rendered using the $page variable.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nHydePage Hyde\\Pages\\Concerns Open in GitHub Live API Docs\n\n### Base Structure\n\n\/**\n * The base class for all Hyde pages. Here simplified for the sake of brevity.\n *\/\nabstract class HydePage\n{\n \/**\n * The directory in which source files are stored. Relative to the project root.\n *\/\n public static string $sourceDirectory;\n\n \/**\n * The output subdirectory to store compiled HTML. Relative to the _site output directory.\n *\/\n public static string $outputDirectory;\n\n \/**\n * The file extension of the source files.\n *\/\n public static string $fileExtension;\n\n \/**\n * The default template to use for rendering the page.\n *\/\n public static string $template;\n\n \/**\n * The page instance identifier.\n *\/\n public readonly string $identifier;\n\n \/**\n * The page instance route key.\n *\/\n public readonly string $routeKey;\n\n \/**\n * The parsed front matter.\n *\/\n public FrontMatter $matter;\n\n \/**\n * The generated page metadata.\n *\/\n public PageMetadataBag $metadata;\n\n \/**\n * The generated page navigation data.\n *\/\n public NavigationData $navigation;\n}\n\n### Methods\n\nwarning Heads up! The following methods are defined in the HydePage class, and are thus available to all page classes. Since the HydePage class is abstract, you cannot instantiate it directly, and many of the static methods are also only callable from the child classes.\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/hyde-page-methods'))->toHtml($page::class) }}\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/interacts-with-front-matter-methods'))->toHtml($page::class) }}\n\n## BaseMarkdownPage\n\nThe base class for all Markdown-based page models, with additional helpers tailored for Markdown pages.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nBaseMarkdownPage Hyde\\Pages\\Concerns Open in GitHub Live API Docs\n\n### Base Structure\n\n\/**\n * The base class for all Markdown-based page models. Here simplified for the sake of brevity.\n *\/\nabstract class BaseMarkdownPage extends HydePage\n{\n public Markdown $markdown;\n\n public static string $fileExtension = '.md';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/base-markdown-page-methods'))->toHtml($page::class) }}\n\n## InMemoryPage\n\nBefore we take a look at the common page classes, you'll usually use, let's first take a look at one that's quite interesting.\n\nThis class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize Hyde\nautodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.\n\nYou can learn more about the InMemoryPage class in the InMemoryPage documentation.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nInMemoryPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nAs the class is not discoverable, the static path properties are not initialized. Instead, you solely rely on the contents\/view properties.\n\nYou can also define macros which allow you to both add methods to the instance, but also to overload some built-in ones like the compile method.\n\n\/**\n * The InMemoryPage class, here simplified for the sake of brevity.\n *\/\nclass InMemoryPage extends HydePage\n{\n public static string $sourceDirectory;\n public static string $outputDirectory;\n public static string $fileExtension;\n\n protected string $contents;\n protected string $view;\n\n \/* @var array \/\n protected array $macros = [];\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/in-memory-page-methods'))->toHtml($page::class) }}\n\n## BladePage\n\nPage class for Blade pages.\n\nBlade pages are stored in the _pages directory and using the .blade.php extension.\nThey will be compiled using the Laravel Blade engine the _site\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nBladePage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass BladePage extends HydePage\n{\n public static string $sourceDirectory = '_pages';\n public static string $outputDirectory = '';\n public static string $fileExtension = '.blade.php';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/blade-page-methods'))->toHtml($page::class) }}\n\n## MarkdownPage\n\nPage class for Markdown pages.\n\nMarkdown pages are stored in the _pages directory and using the .md extension.\nThe Markdown will be compiled to HTML using a minimalistic layout to the _site\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nMarkdownPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass MarkdownPage extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_pages';\n public static string $outputDirectory = '';\n public static string $template = 'hyde::layouts\/page';\n}\n\n### Methods\n\nThis class does not define any additional methods.\n\n## MarkdownPost\n\nPage class for Markdown blog posts.\n\nMarkdown posts are stored in the _posts directory and using the .md extension.\nThe Markdown will be compiled to HTML using the blog post layout to the _site\/posts\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nMarkdownPost Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_posts';\n public static string $outputDirectory = 'posts';\n public static string $template = 'hyde::layouts\/post';\n\n public ?string $description;\n public ?string $category;\n public ?DateString $date;\n public ?PostAuthor $author;\n public ?FeaturedImage $image;\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/markdown-post-methods'))->toHtml($page::class) }}\n\n## DocumentationPage\n\nPage class for documentation pages.\n\nDocumentation pages are stored in the _docs directory and using the .md extension.\nThe Markdown will be compiled to HTML using the documentation page layout to the _site\/docs\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nDocumentationPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass DocumentationPage extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_docs';\n public static string $outputDirectory = 'docs';\n public static string $template = 'hyde::layouts\/docs';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/documentation-page-methods'))->toHtml($page::class) }}\n\n## HtmlPage\n\nPage class for HTML pages.\n\nHTML pages are stored in the _pages directory and using the .html extension.\nThese pages will be copied exactly as they are to the _site\/ directory.\n\n### Quick Reference\n\nClass Name Namespace Source Code API Docs\n\nHtmlPage Hyde\\Pages Open in GitHub Live API Docs\n\n### Base Structure\n\nclass HtmlPage extends HydePage\n{\n public static string $sourceDirectory = '_pages';\n public static string $outputDirectory = '';\n public static string $fileExtension = '.html';\n}\n\n### Methods\n\n[Blade]: {{ Hyde\\Markdown\\Models\\Markdown::fromFile(DocumentationPage::sourcePath('_data\/partials\/hyde-pages-api\/html-page-methods'))->toHtml($page::class) }}","destination":"hyde-pages.html"},{"slug":"in-memory-pages","title":"InMemoryPages","content":"InMemoryPages\n\nIntroduction\n\nThis class is a special page class that is not backed by a file on disk, but rather generated at runtime. While it will\nprobably not be useful for the majority of users, it's a great class to know about if you are a package developer,\nbut feel free to skip this section if you're not interested in this.\n\nWhen to use\n\nThis class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize Hyde\nautodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.\n\nAbout discovery\n\nSince the InMemoryPages are not present in the filesystem, they cannot be found by the auto-discovery process.\nInstead, it's up to the developer to manually register them. If you are working on your own project, you can do this in\nthe boot method of a service provider, such as the AppServiceProvider which is already present in your app\/ directory.\n\nIf you are developing a package, you may instead want to register the page in your package extension class, within the\npage collection callback. In either case, if you want your page to be able to be fully processed by Hyde, you need to\nmake sure you register it before the full application is booted so that routes can be generated.\n\nTo see how to register the page, see the examples below. But first we must look at how to actually create the page.\n\nCreating the page\n\nTo create an InMemoryPage, you need to instantiate it with the required parameters.\n\nSince a page would not be useful without any content to render, the class offers two content options through the constructor.\n\nYou can either pass a string to the $contents parameter, Hyde will then save that literally as the page's contents.\n\n$page = new InMemoryPage(contents: 'Hello World!');\n\nAlternatively, you can pass a Blade view name to the $view parameter, and Hyde will use that view to render the page\ncontents with the supplied front matter during the static site build process.\n\nwarning Note that $contents take precedence over $view, so if you pass both, only $contents will be used.\n\nYou can also register a macro with the name compile to overload the default compile method.\n\nAPI Reference\n\nTo see all the methods available, please see the InMemoryPage API reference.","destination":"in-memory-pages.html"},{"slug":"architecture-concepts","title":"Advanced Architecture Concepts","content":"Advanced Architecture Concepts\n\nIntroduction\n\nThese chapters are written for power users and package contributors. If you're just looking to get a site up and running,\nyou can safely skip this section. The documentation here will cover advanced topics under the presumption that\nthe reader has a basic to intermediate understanding of programming, as well as PHP, object-oriented design,\nand to some extent Laravel, as the articles are heavily driven by code examples.\n\nYou are of course free to skip this entire section, as you don't need to know these things to use Hyde.\nHowever, if you want to know the \"magic\" behind Hyde, or if you want to take advantage of these powerful tools,\nthen by all means, please read on! This is also a great place to start if you want to contribute to the source code.\n\ninfo For a high-level overview of these concepts, see the Basic Architecture Concepts page.\n\nBehind the magic\n\nWant to learn more about a particular feature? Click on the links below to visit the article.\n\n[\/\/]: # (This would be better suited for a component, but it's a fun experiment for now)\n[Blade]: @foreach(glob(DocumentationPage::path('architecture-concepts\/*.md')) as $file) {{ Hyde::makeTitle(basename($file, '.md')) }} @endforeach","destination":"architecture-concepts.html"},{"slug":"autodiscovery","title":"Autodiscovery","content":"Autodiscovery\n\nIntroduction\n\nHydePHP aims to reduce the amount of configuration you need to do to get a site up and running.\nTo that end, Hyde uses a process called autodiscovery to automatically find and register your pages.\n\nThis article will go into detail about how autodiscovery works as well as the lifecycle of the HydeKernel.\n\nThe short version\n\nHyde will use the information in the page model classes to scan the source directories for matching files which are\nparsed using instructions from the model's class, resulting in data used to construct objects that get stored in the HydeKernel.\n\nPrerequisites\n\nBefore reading this article, you should be familiar with the following concepts:\n- Page Models\n- The HydeKernel\n\nBooting pipeline\n\nThe autodiscovery is run when the HydeKernel boots. It does so in three distinct steps, which run in sequence as each\nstep depends on the previous one. Each discovery step runs in a FoundationCollection which both runs the actual\ndiscovery process and stores the discovered data in memory.\n\nThe steps are as follows:\n\n1. Step one: The file collection discovers all the source files and stores them in memory\n2. Step two: The page collection parses all the source files into page model objects\n3. Step three: The route collection generates route objects for all the pages\n\nInteracting with the collections\n\nUsually, you will interact with the collection data through intermediaries.\n* For example, if you call MarkdownPost::get('my-post'), Hyde will retrieve that page from the page collection.\n* If you call Routes::get('index'), Hyde will retrieve that route from the route collection.\n\nThe HydeKernel\n\nIf you have not yet read the HydeKernel Documentation, here's a quick recap:\n\nThe HydeKernel encapsulates a HydePHP project, providing helpful methods for interacting with it.\nIt is also responsible for booting the application, which includes the autodiscovery process.\n\nThe kernel is created very early on in the application lifecycle, in the bootstrap.php file, where it is also bound\nas a singleton into the application service container.\n\nAt this point you might be wondering why we're talking about the kernel when this article is about autodiscovery.\nWell, as you'll see in just a moment, the kernel is responsible for initiating the autodiscovery process.\nThe kernel is also where the discovered data is stored in memory, so it's important to understand how it works.\n\nThe kernel lifecycle\n\nNow that we know the role of the HydeKernel, let's take a look at its lifecycle. The kernel is \"lazy-booted\", meaning\nthat all the heavy lifting only happens when you actually need it. Once booted, the kernel data will stay in memory\nuntil the console application is terminated.\n\nThe kernel data is primarily stored in three collections that get generated during the kernel's boot process.\nLet's take a look at a simplified version of the kernel's boot method to see how this works.\n\npublic function boot(): void\n{\n $this->files = FileCollection::boot($this);\n $this->pages = PageCollection::boot($this);\n $this->routes = RouteCollection::boot($this);\n\n \/\/ Scroll down to see what this is used for\n $this->booted = true;\n}\n\nHere you'll see that we boot the three collections. This is where all the autodiscovery magic happens!\n\nDeep dive into lazy-booting\n\nIf you're curious about how the kernel is lazy-booted, here's how it works!\nFeel free to skip this section if this doesn't interest you.\n\n\/\/ This will boot the kernel if it hasn't been booted yet\npublic function pages(): PageCollection\n{\n $this->needsToBeBooted();\n\n return $this->pages;\n}\n\n\/\/ This is the method that triggers the boot process\nprotected function needsToBeBooted(): void\n{\n if (! $this->booted) {\n $this->boot();\n }\n}\n\nYeah, it's really unglamorous I know. But it works! Having it like this will ensure that any time you call Hyde::pages(),\nthat underlying collection will always have been booted and be ready to use.","destination":"autodiscovery.html"},{"slug":"automatic-routing","title":"Automatic Routing","content":"Automatic Routing\n\ninfo This covers an intermediate topic which is not required for basic usage, but is useful if you want to use the framework to design custom Blade templates.\n\nHigh-level overview\n\nIf you've ever worked in an MVC framework, you are probably familiar with the concept of routing.\nAnd you are probably also familiar with how boring and tedious it can be. Thankfully, Hyde takes the pain out of routing\nthrough the Hyde Autodiscovery process.\n\nInternally, when booting the HydeCLI application, Hyde will automatically discover all the content files in the source\ndirectories, and create a route index for all of them. This index works as a two-way link between source files and compiled files.\n\nDon't worry if this sounds complex, as the key takeaway is that the index is created and maintained automatically.\nNevertheless, the routing system provides several helpers that you can optionally use in your Blade views to\nautomatically resolve relative links and other useful features.\n\nYou can see all the routes and their corresponding source files by running the hyde route:list command.\n\nphp hyde route:list\n\nAccessing routes\n\nEach route in your site is represented by a Route object. It's very easy to get a Route object instance from the Router's index.\nThere are a few ways to do this, but most commonly you'll use the Routes facade's get() method where you provide a route key,\nand it will return the Route object. The route key is generally ``. Here are some examples:\n\n\/\/ Source file: _pages\/index.md\/index.blade.php\n\/\/ Compiled file: _site\/index.html\nRoutes::get('index')\n\n\/\/ Source file: _posts\/my-post.md\n\/\/ Compiled file: _site\/posts\/my-post.html\nRoutes::get('posts\/my-post')\n\n\/\/ Source file: _docs\/readme.md\n\/\/ Compiled file: _site\/docs\/readme.html\nRoutes::get('docs\/readme')\n\nUsing the x-link component\n\nWhen designing Blade layouts it can be useful to use the x-link component to automatically resolve relative links.\n\nYou can of course use it just like a normal anchor tag like so:\n\nHome\n\nBut where it really shines is when you supply a route. This will then resolve the proper relative link, and format it to use pretty URLs if your site is configured to use them.\n\nHome\n\nYou can of course, also supply extra attributes like classes:\n\nHome","destination":"automatic-routing.html"},{"slug":"dynamic-data-discovery","title":"Dynamic Data Discovery","content":"Dynamic Data Discovery\n\n[\/\/]: # (Adds a pseudo-subtitle)\nAKA: Front Matter & Filling in the Gaps\n\nIntroduction\n\nHyde wants to allow developers to write less, and do more. This is also a major difference between HydePHP and JekyllRB.\nJekyll will only do what you tell it to do. Hyde, on the other hand, will try to do what you want it to do.\n\nAs with all other chapters in this category, you don't need to know about this to use Hyde -- that's the whole point!\nHowever, if you're anything like me, you'll likely find this interesting to read about, even if you don't really need to know it.\n\nHyde makes great use of front matter in both Markdown and Blade files (it's true!). However, it can quickly get tedious\nand quite frankly plain boring to have to write a bunch of front matter all the time. As Hyde wants you to focus on\nyour content, and not your markup, front matter is optional and Hyde will try to fill in the gaps for you.\n\nIf you're not happy with Hyde's generated data you can always override it by adding front matter to your files.\n\nHow it Works\n\nNow, to the fun part: getting into the nitty-gritty details of how Hyde does this!\n\nTo make things simple the dynamic data is created in a special stage where the page object is being created.\nIf you have not yet read the page models chapter you might want to do so now.\nYou might also want to read about the autodiscovery lifecycle for some context as to when this happens.\n\nThe factory pipeline, in short\n\nAfter basic information about the page has been gathered, such as the source file information and the front matter,\nthe page model is run through a series of factories. These are just classes that work around the limited data\nthat is available at this point and will generate the rich data used to make your Hyde page awesome.\n\nThere are a few factory classes. The one we will be looking at here is the HydePageDataFactory class, which is\nresponsible for data applicable to all page models. Complex structures and data only relevant to some page types\nhave their own factories, making the code more modular and maintainable.\n\nIn-depth overview of a page factory\n\nLet's take a look at how Hyde will discover the title of a page as an example. Since this is something used by all pages,\nthis discovery is done in the HydePageDataFactory class.\n\nFactory data input\n\nThe factory gets one input, a CoreDataObject class. Think of this like a DTO (Data Transfer Object) that holds\nimmutable data known from the start of the page construction process. It also has all the information needed\nto identify the page and its source file. Here's a simplified version of the class:\n\nclass CoreDataObject\n{\n public readonly FrontMatter $matter;\n public readonly Markdown|false $markdown;\n\n public readonly string $pageClass;\n public readonly string $identifier;\n public readonly string $sourcePath;\n public readonly string $outputPath;\n public readonly string $routeKey;\n}\n\nProcessing the known data\n\nNow that we have the input we pass it to the factory, where a simple algorithm is used to find the best title for the page.\n\nprivate function findTitleForPage(): string\n{\n return $this->matter('title')\n ?? $this->findTitleFromMarkdownHeadings()\n ?? Hyde::makeTitle(basename($this->identifier));\n}\n\nAs you can see, we are using the null coalescing operator (??) to return the first non-null value. We always want the\nuser to be able to set any data explicitly, so we first check the front matter in all factory methods.\n\nIf no title is set in the matter the method will return null, and Hyde will try the next step which is to search the headings.\nIf that fails, the last step will generate a title from the file name. This ensures that no matter what, we always have a title.\n\nInjecting the data into the page\n\nOnce the data has been discovered, it is injected into the page object. This is rather unglamorous but is mentioned\nhere for completeness. It's pretty simple. The factory will always return an array of the computed data, where the keys\nalways match the property names on the page object, so we just need to loop over the array and set the properties.\n\nforeach ($data->toArray() as $key => $value) {\n $this->{$key} = $value;\n}\n\nAnd that's pretty much it! Hyde will do this for all the data it can discover, freeing you to focus on your content.","destination":"dynamic-data-discovery.html"},{"slug":"extensions-api","title":"The Extensions API","content":"The Extensions API\n\nIntroduction\n\nThe Extensions API is a powerful interface designed for package developers who want to extend the functionality of HydePHP.\n\nUsing the API, you can hook directly into the HydePHP Kernel and extend sites with custom page types and new features.\n\nThis documentation page functions heavily through examples, so it's recommended that the sections are read in order.\n\nPrerequisites\n\nBefore creating your extension, it will certainly be helpful if you first become familiar with\nthe basic internal architecture of HydePHP, as well as how the auto-discovery system works,\nso you can understand how your code works with the internals.\n\n- Core concepts overview\n- Architecture concepts\n- Autodiscovery\n\nThe why and how of the Extensions API\n\nHydePHP being a static site generator, the Extensions API is centred around Page Models,\nwhich you are hopefully already familiar with, otherwise you should read up on them first.\n\nWhat the Extensions API does is to allow you to create custom page types, and tell HydePHP how to discover them.\nThis may sound like a small thing, but it's actually incredibly powerful as the page models are the foundation\nof HydePHP's functionality. They tell the system how to discover pages, how to render them,\nand how they interact with the site.\n\nAny other functionality you want to add to HydePHP, such as new commands or configuration options,\ncan be added the same way as you would in Laravel, and are thus not part of our API.\nSee the Laravel package development guide for more.\n\nCreating your Extension class\n\nThe entry-point for your extension is your Extensions class. Within this, you can register the custom page classes.\nIf needed, you can also register discovery handlers which can run custom logic at various parts of the boot process.\n\nIn this article we will create an extension that registers a new type of page, a JsonPageExtension.\n\nThe first step is to create a class that extends the HydeExtension class:\n\nuse Hyde\\Foundation\\Concerns\\HydeExtension;\n\nclass JsonPageExtension extends HydeExtension {\n \/\/\n}\n\nIn here, we will register our extension class name in the getPageClasses method:\n\nclass JsonPageExtension extends HydeExtension {\n public static function getPageClasses(): array {\n return [\n JsonPage::class,\n ];\n }\n}\n\nHyde will then use the information from the JsonPage class to automatically discover the pages when booting the Kernel.\nFor example, if you specify the file extension and source directory, that is all Hyde needs to know to discover the pages.\n\nIf our pages need more complex discovery logic, we can create custom handlers. so let's take a quick look at that next.\n\nDiscovery handlers\n\nThe discovery handlers let you run code at various points of the booting process. This is usually only needed if your\npage models cannot provide the information required for Hyde run the standard auto-discovery, and thus need custom logic.\n\nUsually in these cases, you would only need to add files to the Kernel FileCollection,\nthough the HydeExtension class offers the following three discovery handlers, in case you need them:\n\n\/* Runs during file discovery \/\npublic function discoverFiles(FileCollection $collection): void;\n\n\/* Runs during page discovery \/\npublic function discoverPages(PageCollection $collection): void;\n\n\/* Runs during route discovery \/\npublic function discoverRoutes(RouteCollection $collection): void;\n\nAny of these can be implemented in your extension class, and they will be called during the discovery. As you can see,\nthe instance of the discovery collection is injected into the method for you to interact with.\n\nDiscovery handler example\n\nLet's go crazy and implement a discovery handler to collect JsonPage files from an external API! We will do this\nby implementing the discoverPages method in our extension class, and from there inject pages retrieved from our API.\n\nclass JsonPageExtension extends HydeExtension {\n public function discoverPages(PageCollection $collection): void {\n $pages = Http::get('https:\/\/example.com\/my-api')->collect();\n\n $pages->each(function (array $page) use ($collection): void {\n $collection->addPage(JsonPage::fromArray($page));\n });\n }\n}\n\nSince the discovery steps are handled sequentially, the added pages will automatically be discovered as routes without\nus having to implement that handler method. As we inject the page objects directly, we bypass the need for the FileCollection.\n\nRegistering your extension\n\nNow that we have our extension class, we need to register it with HydePHP.\n\nIt's important that your class is registered before the HydeKernel boots. Therefore, an excellent place for this is the\nregister method of your extensions service provider, where you call the registerExtension method of the HydeKernel\nsingleton instance, which you can access via the Hyde\\Hyde facade, or via the service container.\n\nuse Hyde\\Hyde;\nuse Hyde\\Foundation\\HydeKernel;\nuse Illuminate\\Support\\ServiceProvider;\n\nclass JsonPageExtensionServiceProvider extends ServiceProvider {\n public function register(): void {\n \/\/ Via the service container:\n $this->app->make(HydeKernel::class)->registerExtension(JsonPageExtension::class);\n\n \/\/ Or via the facade:\n Hyde::registerExtension(JsonPageExtension::class);\n }\n}\n\nPackaging your extension\n\nTo make your extension available to other HydePHP users, you can make it into a Composer package,\nand publish it to Packagist for others to install.\n\nIf you register your service provider in your package's composer.json file, your extension automatically be enabled when\nthe package is installed in a HydePHP project!\n\n{\n \"extra\": {\n \"laravel\": {\n \"providers\": [\n \"My\\\\Namespace\\\\JsonPageExtensionServiceProvider\"\n ]\n }\n }\n}\n\nTelling the world about your extension\n\nNext up, why not send us a Tweet at @HydeFramework and tell us about your extension,\nso we can feature it?","destination":"extensions-api.html"},{"slug":"page-models","title":"Page models","content":"The Hyde Page Models\n\nIntroduction\n\nThe Hyde page models are an integral part of how HydePHP creates your static site. Each page in your site is represented\nby a page model. These are simply PHP classes that in addition to holding both the source content and computed data\nfor your pages, also house instructions to Hyde on how to parse, process, and render the pages to static HTML.\n\nIn this article, you'll get a high-level overview of the page models, and some code examples to give you a look inside.\n\nThe short version\n\nPage models are classes that have two primary concerns:\n\n1. They act as blueprints containing static instructions for how to parse, process, and, render pages.\n2. Each class instance also holds the page source contents, as well as the computed data.\n\nOther key points:\n\n- HydePHP, at the time of writing, comes with five different page classes, one for each supported type.\n- You don't construct page models yourself. HydePHP does it for you by the autodiscovery process.\n- Page models are just PHP classes. You can extend them, and you can implement your own.\n\nThe Page Model\n\nTo give you an idea of what a page model class looks like, here's a simplified version of the base MarkdownPost class,\nDon't worry if you don't understand everything yet, we'll talk more about these parts later.\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_posts';\n public static string $outputDirectory = 'posts';\n public static string $fileExtension = '.md';\n public static string $template = 'post';\n\n public string $identifier;\n public string $routeKey;\n public string $title;\n\n public FrontMatter $matter;\n public Markdown $markdown;\n}\n\n_Note that since Hyde pages are modular through class inheritance and traits, this example has been simplified and\nedited to show all the relevant parts inlined into one class._\n\nPage Models as Blueprints\n\nAll page models have some static properties (that is, they belong to the class, not the instance) that are used as\nblueprints, defining information for Hyde to know how to parse a file, and what data around it should be generated.\n\nLet's again take the simplified MarkdownPost class as an example, this time only showing the static properties:\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public static string $sourceDirectory = '_posts';\n public static string $outputDirectory = 'posts';\n public static string $fileExtension = '.md';\n public static string $template = 'post';\n}\n\nWhat each property does\n\nThe properties should be self-explanatory, but here's a quick rundown to give some context on how they are used,\nand how the paths relate to each other. So for the class above, Hyde will thanks to this blueprint, know to:\n* Look for files in the _posts directory, with the .md extension\n* Compile the page using the post Blade template\n* Output the compiled page to the _site\/posts directory\n\nPage Models as Data Containers\n\nAs mentioned above, each page model instance also holds the page source contents, as well as the computed data.\n\nLet's again take the simplified MarkdownPost class as an example, this time only showing the instance properties:\n\nclass MarkdownPost extends BaseMarkdownPage\n{\n public string $identifier;\n public string $routeKey;\n public string $title;\n\n public FrontMatter $matter;\n public Markdown $markdown;\n}\n\nThere are some more properties than shown here, for example, various metadata properties, but these are the most common\nand important ones.\n\nWhile the static data gives instructions to Hyde on how to process all pages of the type, the instance data tells Hyde\nhow to process a specific page. For example, the identifier property is used to uniquely identify the page, and\nthe routeKey property is used to generate the URL for the page.\n\nThe matter and markdown properties as I'm sure you can guess, hold the page's front matter and markdown content.\nThese can then also be processed by page factories to generate the computed data like the\ntitle property.","destination":"page-models.html"},{"slug":"the-hydekernel","title":"The HydeKernel","content":"The HydeKernel\n\nIntroduction\n\nIn the centre, or should I say core, of HydePHP is the HydeKernel. The kernel encapsulates a HydePHP project and\nprovides helpful methods for interacting with it. You can think of it as the heart of HydePHP, if you're a romantic.\n\nThe HydeKernel is so important that you have probably used it already. The main entry point for the HydePHP\nAPI is the Hyde facade, which calls methods on the kernel.\n\nuse Hyde\\Hyde;\nuse Hyde\\Foundation\\HydeKernel;\n\nHyde::version(); \/\/ calls $HydeKernel->version()\n\nThe kernel is created very early on in the application lifecycle, in the bootstrap.php file, where it is also bound\nas a singleton into the application service container.\n\nAccessing the kernel\n\nThe HydeKernel is stored as a singleton in a static property in its own class and can be accessed in a few ways.\n\nCommonly, you'll use the Hyde facade which forwards calls to the singleton instance.\nYou can also use the hyde() function to get the Kernel, and call methods on it.\n\nSince the instance is also bound into the Laravel Application Service Container you can also use Dependency Injection by type-hinting the HydeKernel::class.\n\nHere are some examples of how you can call methods on the Kernel. All methods call the same method on the same instance, so it's just a matter of preference.\n\nuse Hyde\\Hyde;\nuse Hyde\\Foundation\\HydeKernel;\n\nHyde::version();\nHyde::kernel()->version();\nHydeKernel::getInstance()->version();\napp(HydeKernel::class)->version();\nhyde()->version();\n\nThe Kernel instance is constructed in bootstrap.php, and is available globally as $hyde.\n\nThe kernel lifecycle\n\nWhenever we talk about the kernel being \"booted\" we are talking about the kernel's role in the autodiscovery process.\n\nYou can read all about it in the Autodiscovery Documentation.\n\nAPI Reference\n\nSince the most common way to interact with the kernel is through the Hyde facade, we will use that for the examples.\nBut you could just as well chain the methods on the accessed kernel singleton instance if you wanted.\n\nversion()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::version(): string\n\n__construct()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\n$hyde = new HydeKernel(string $basePath): void\n\nfeatures()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::features(): Hyde\\Facades\\Features\n\nhasFeature()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::hasFeature(string $feature): bool\n\ntoArray()\n\nGet the instance as an array.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::toArray(): array\n\nfiles()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::files(): \\Hyde\\Foundation\\Kernel\\FileCollection\n\npages()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::pages(): \\Hyde\\Foundation\\Kernel\\PageCollection\n\nroutes()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::routes(): \\Hyde\\Foundation\\Kernel\\RouteCollection\n\nmakeTitle()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::makeTitle(string $value): string\n\nnormalizeNewlines()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::normalizeNewlines(string $string): string\n\nstripNewlines()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::stripNewlines(string $string): string\n\ntrimSlashes()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::trimSlashes(string $string): string\n\nmarkdown()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::markdown(string $text, bool $normalizeIndentation): Illuminate\\Support\\HtmlString\n\nformatLink()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::formatLink(string $destination): string\n\nrelativeLink()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::relativeLink(string $destination): string\n\nmediaLink()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::mediaLink(string $destination, bool $validate): string\n\nasset()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::asset(string $name, bool $preferQualifiedUrl): string\n\nurl()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::url(string $path): string\n\nhasSiteUrl()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::hasSiteUrl(): bool\n\nfilesystem()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::filesystem(): Hyde\\Foundation\\Kernel\\Filesystem\n\npath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::path(string $path): string\n\nvendorPath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::vendorPath(string $path, string $package): string\n\nmediaPath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::mediaPath(string $path): string\n\nsitePath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::sitePath(string $path): string\n\nsiteMediaPath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::siteMediaPath(string $path): string\n\npathToAbsolute()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::pathToAbsolute(array|string $path): array|string\n\npathToRelative()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::pathToRelative(string $path): string\n\ngetInstance()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getInstance(): Hyde\\Foundation\\HydeKernel\n\nsetInstance()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setInstance(Hyde\\Foundation\\HydeKernel $instance): void\n\ngetBasePath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getBasePath(): string\n\nsetBasePath()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setBasePath(string $basePath): void\n\ngetSourceRoot()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getSourceRoot(): string\n\nsetSourceRoot()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setSourceRoot(string $sourceRoot): void\n\ngetOutputDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getOutputDirectory(): string\n\nsetOutputDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setOutputDirectory(string $outputDirectory): void\n\ngetMediaDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getMediaDirectory(): string\n\nsetMediaDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::setMediaDirectory(string $mediaDirectory): void\n\ngetMediaOutputDirectory()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getMediaOutputDirectory(): string\n\nregisterExtension()\n\nRegister a HydePHP extension within the HydeKernel.\n\nTypically, you would call this method in the register method of a service provider. If your package uses the standard Laravel (Composer) package discovery feature, the extension will automatically be enabled when the package is installed.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::registerExtension(class-string<\\Hyde\\Foundation\\Concerns\\HydeExtension> $extension): void\n\ngetExtension()\n\nGet the singleton instance of the specified extension.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getExtension(class-string<T> $extension): T\n\nhasExtension()\n\nDetermine if the specified extension is registered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::hasExtension(class-string<\\Hyde\\Foundation\\Concerns\\HydeExtension> $extension): bool\n\ngetExtensions()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getExtensions(): array\n\ngetRegisteredExtensions()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getRegisteredExtensions(): array>\n\ngetRegisteredPageClasses()\n\nNo description provided.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::getRegisteredPageClasses(): array>\n\nshareViewData()\n\nShare data for the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::shareViewData(Hyde\\Pages\\Concerns\\HydePage $page): void\n\ncurrentRouteKey()\n\nGet the route key for the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::currentRouteKey(): string\n\ncurrentRoute()\n\nGet the route for the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::currentRoute(): Hyde\\Support\\Models\\Route\n\ncurrentPage()\n\nGet the page being rendered.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::currentPage(): Hyde\\Pages\\Concerns\\HydePage\n\nisBooted()\n\nDetermine if the Kernel has booted.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::isBooted(): bool\n\nboot()\n\nBoot the Hyde Kernel and run the Auto-Discovery Process.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nHyde::boot(): void\n\nbooting()\n\nRegister a new boot listener.\n\nYour callback will be called before the kernel is booted. You can use this to register your own routes, pages, etc. The kernel instance will be passed to your callback.\n\n\/\/ torchlight! {\"lineNumbers\": false}\n\/* @param callable(\\Hyde\\Foundation\\HydeKernel): void $callback \/\nHyde::booting(callable(\\Hyde\\Foundation\\HydeKernel): void): void\n\nbooted()\n\nRegister a new "booted" listener.\n\nYour callback will be called after the kernel is booted. You can use this to run any logic after discovery has completed. The kernel instance will be passed to your callback.\n\n\/\/ torchlight! {\"lineNumbers\": false}\n\/* @param callable(\\Hyde\\Foundation\\HydeKernel): void $callback \/\nHyde::booted(callable(\\Hyde\\Foundation\\HydeKernel): void): void","destination":"the-hydekernel.html"},{"slug":"blog-posts","title":"Creating Blog Posts","content":"Creating Blog Posts\n\nIntroduction to Hyde Posts\n\nMaking blog posts with Hyde is easy. At the most basic level, all you need is to add a Markdown file to your _posts folder.\n\nTo use the full power of the Hyde post module you'll want to add YAML Front Matter to your posts.\n\nYou can interactively scaffold posts with automatic front matter using the HydeCLI:\n\nphp hyde make:post\nLearn more about scaffolding posts, and other files, in the console commands documentation.\n\nShort Video Tutorial\n\nBest Practices and Hyde Expectations\n\nSince Hyde does a lot of things automatically, there are some things you may need\nto keep in mind when creating blog posts so that you don't get unexpected results.\n\nFilenames\n\n- Markdown post files are stored in the _posts directory\n- The filename is used as the filename for the compiled HTML\n- Filenames should use kebab-case-name followed by the extension .md\n- Files prefixed with _underscores are ignored by Hyde\n- Your post will be stored in _site\/posts\/.html\n\nExample:\n\n\u2714 posts\/hello-world.md # Valid and will be compiled to site\/posts\/hello-world.html\n\nFront Matter\n\nFront matter is optional, but highly recommended for blog posts as the front matter is used to construct dynamic HTML\nmarkup for the post as well as meta tags and post feeds.\n\nYou are encouraged to look at the compiled HTML to learn\nand understand how your front matter is used. You can read more about the Front Matter format in the Front Matter documentation.\n\nBlog Post Example\n\nBefore digging deeper into all the supported options, let's take a look at what a basic post with front matter looks like.\n\n\/\/ filepath _posts\/my-new-post.md\ntitle: My New Post\ndescription: A short description used in previews and SEO\ncategory: blog\nauthor: Mr. Hyde\ndate: 2022-05-09 18:38\nWrite your Markdown here\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit.\nAutem aliquid alias explicabo consequatur similique,\nanimi distinctio earum ducimus minus, magnam.\n\nSupported Front Matter properties\n\nPost Front Matter Schema\n\nHere is a quick reference of the supported front matter properties.\nKeep on reading to see further explanations, details, and examples.\n\nKEY NAME VALUE TYPE EXAMPLE \/ FORMAT\n\ntitle string \"My New Post\"\ndescription string \"A short description\"\ncategory string \"my favorite recipes\"\ndate string \"YYYY-MM-DD [HH:MM]\"\nauthor string\/array See author section\nimage string\/array See image section\n\nNote that YAML here is pretty forgiving. In most cases you do not need to wrap strings in quotes.\nHowever, it can help in certain edge cases, for example if the text contains special Yaml characters, thus they are included here.\n\nIn the examples below, when there are multiple examples, they signify various ways to use the same property.\n\nWhen specifying an array you don't need all the sub-properties. The examples generally show all the supported values.\n\nTitle\n\ntitle: \"My New Post\"\n\nDescription\n\ndescription: \"A short description used in previews and SEO\"\n\nCategory\n\ncategory: blog\n\ncategory: \"My favorite recipes\"\n\nDate\n\ndate: \"2022-01-01\"\n\ndate: \"2022-01-01 12:00\"\n\nAuthor\n\nSpecify a page author, either by a username for an author defined in the authors config, or by an arbitrary name,\nor by an array of author data. See the Post Author section for more details.\n\nArbitrary name displayed \"as is\"\n\nauthor: \"Mr. Hyde\"\n\nUsername defined in authors config\n\nauthor: mr_hyde\n\nArray of author data\n\nauthor:\n name: \"Mr. Hyde\"\n username: mr_hyde\n website: https:\/\/twitter.com\/HydeFramework\n\nWhen specifying an array you don't need all the sub-properties. The example just shows all the supported values.\nArray values here will override all the values in the authors config entry.\n\nImage\n\nSpecify a cover image for the post, either by a local image path for a file in the _media\/ directory, or by a full URL.\nAny array data is constructed into a dynamic fluent caption, and injected into post and page metadata.\n\nLocal image path\n\nWhen supplying an image source with a local image path, the image is expected to be stored in the _media\/ directory.\nLike all other media files, it will be copied to _site\/media\/ when the site is built, so Hyde will resolve links accordingly.\n\nimage: image.jpg\n\nFull URL\n\nFull URL starting with http(s):\/\/) or \/\/ (protocol-relative).\nThe image source will be used as-is, and no additional processing is done.\n\nimage: https:\/\/cdn.example.com\/image.jpg\n\nData-rich image\n\nYou can also supply an array of data to construct a rich image with a fluent caption.\n\nimage:\n source: Local image path or full URL\n altText: \"Alt text for image\"\n titleText: \"Tooltip title\"\n copyright: \"Copyright (c) 2022\"\n licenseName: \"CC-BY-SA-4.0\"\n licenseUrl: https:\/\/example.com\/license\/\n authorUrl: https:\/\/photographer.example.com\/\n authorName: \"John Doe\"\n\nSee posts\/introducing-images\nfor a detailed blog post with examples and schema information!\n{ .info }\n\nUsing images in posts\n\nTo use images stored in the _media\/ directory, you can use the following syntax:\n\nImage Alt\n\nNote the relative path since the blog post is compiled to posts\/example.html\n\nTo learn more, check out the managing assets chapter on the topic.","destination":"blog-posts.html"},{"slug":"compile-and-deploy","title":"Compile and Deploy your site","content":"Compile and Deploy your site\n\nRunning the build command\n\nNow that you have some amazing content, you'll want to compile your site into static HTML.\n\nThis is as easy as executing the build command:\n\nphp hyde build\n\nYou can also compile a single file:\n\nphp hyde rebuild \n\nAnd, you can even start a development server to compile your site on the fly:\n\nphp hyde serve\n\nFurther reading\n\ninfo Key Concept: Autodiscovery When building the site, Hyde will use all the routes generated when the auto-discovery process scanned your source directories for files. The command will then compile them into static HTML using the appropriate layout depending on what kind of page it is. Thanks to Hyde, the days of manually defining routes are over!\n\nLearn more about these commands in the console commands documentation:\n\n- Build command\n- Rebuild command\n- Serve command\n\nDeploying your site\n\nOne of the things that make static sites so enjoyable to work with is how easy it is to deploy them to the web.\nThis list is not exhaustive, but gives you a general idea of the most common ways to deploy your site.\nIf you have ideas to add to the documentation, please send a pull request!\n\nGeneral deployment\n\nIn essence, all you need to do is copy the contents of the _site directory to a web server, and you're done.\n\nOnce the site is compiled there is nothing to configure or worry about.\n\nFTP and File Managers\n\nIf you have a conventional web host, you can use FTP\/SFTP\/FTPS to upload your compiled site files to the web server.\nSome web hosting services also have web-based file managers.\n\nTo deploy your site using any of these methods, all you need to do is upload the entire contents of your _site\ndirectory to the web server's public document root, which is usually the public_html, htdocs, or www directory.\n\nGitHub Pages - Manually\n\nGitHub Pages is a free service that allows you to host your static site on the web.\n\nIn general, push the entire contents of your _site directory to the gh-pages branch of your repository,\nor the docs\/ directory on your main branch, depending on how you set it up.\n\nPlease see the GitHub Pages documentation for more information.\n\nGitHub Pages - CI\/CD\n\nHyde works amazing with GitHub Pages and GitHub Actions and the entire build and deploy process can be automated.\n\n- We have a great blog post on how to do this, Automate HydePHP sites using GitHub Actions and GitHub Pages.\n\n- You can also copy our sample GitHub Actions Workflow.yml file.\n\nBy the way, HydePHP.com is hosted on GitHub Pages, and the site is compiled in a GitHub Action workflow that compiles and\ndeploys the site automatically when the source is updated using this GitHub workflow.","destination":"compile-and-deploy.html"},{"slug":"documentation-pages","title":"Creating Documentation Pages","content":"Creating Documentation Pages\n\nIntroduction to Hyde Documentation Pages\n\nWelcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier.\nUsing 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.\n\nHyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a\nresponsive sidebar that is automatically generated based on your Markdown files. You can even customize the order,\nlabels, and even groups, of the sidebar items to suit your needs.\n\nAdditionally, if you have a _docs\/index.md file, the sidebar header will link to it, and an automatically generated\n\"Docs\" link will be added to your site's main navigation menu, pointing to your documentation page.\n\nIf you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically,\nsaving you time and effort. For more information about this feature, see the extensions page.\n\nBest Practices and Hyde Expectations\n\nSince Hyde does a lot of things automatically, there are some things you may need\nto keep in mind when creating blog posts so that you don't get unexpected results.\n\nFilenames\n\n- Hyde Documentation pages are files stored in the _docs directory\n- The filename is used as the filename for the compiled HTML\n- Filenames should use kebab-case-name format, followed by the appropriate extension\n- Files prefixed with _underscores are ignored by Hyde\n- You should always have an index.md file in the _docs\/ directory\n- Your page will be stored in _site\/docs\/.html unless you change it in the config\n\nAdvanced usage and customization\n\nLike 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.\nSince 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 to see how it's all put together and find the customizations you are looking for.\n\nCreating Documentation Pages\n\nYou can create a Documentation page by adding a file to the _docs directory where the filename ends in .md.\n\nYou can also scaffold one quickly by using the HydeCLI.\n\nphp hyde make:page \"Page Title\" --type=\"docs\"\n\nThis will create the following file saved as _docs\/page-title.md\n\nPage Title\n\nFront Matter is optional\n\nYou don't need to use front matter to create a documentation page.\n\nHowever, Hyde still supports front matter here as it allows you to quickly override the default values.\n\nHere is a quick reference, however, you should take a look at the dynamic content section to learn more.\n\ntitle: \"Page Title\"\nnavigation:\n label: \"Sidebar Label\"\n hidden: true\n priority: 5\n\nDynamic content generation\n\nHyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title.\nIf you are not happy with the results you can customize them in the config or with front matter.\n\nFront Matter reference\n\nBefore we look at how to override things, here is an overview of the relevant content Hyde generates,\nand where the data is from as well as where it can be overridden.\n\nProperty Description Dynamic Data Source Override in\n\ntitle (string) The title of the page used in the HTML ` tag The first H1 heading (# Foo`) Front matter\nnavigation.label (string) The label for the page shown in the sidebar The page basename Front matter, config\nnavigation.priority (integer) The priority of the page used for ordering the sidebar Defaults to 999 Front matter, config\nnavigation.hidden (boolean) Hides the page from the sidebar none Front matter, config\nnavigation.group (string) The group the page belongs to in the sidebar Subdirectory, if nested Front matter\n\nSidebar\n\nThe sidebar is automatically generated from the files in the _docs directory. You will probably want to change the order\nof these items. You can do this in two ways, either in the config or with front matter using the navigation array settings.\n\nTable of contents\n\nHyde automatically generates a table of contents for the page and adds it to the sidebar.\n\nThe behaviour of this can be changed in the configuration file.\nSee the customization page for more details.\n\nSidebar ordering\n\nThe sidebar is sorted\/ordered by the priority property. The higher the priority the further down in the sidebar it will be.\nThe default priority is 999. You can override the priority using the following front matter:\n\nnavigation:\n priority: 5\n\nYou can also change the order in the Docs configuration file.\nSee the chapter in the customization page for more details. \nI personally think the config route is easier as it gives an instant overview, however the first way is nice as well.\n\nSidebar labels\n\nThe sidebar items are labelled with the label property. The default label is the filename of the file.\nYou can change it with the following front matter:\n\nnavigation:\n label: \"My Custom Sidebar Label\"\n\nSidebar grouping\n\nSidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items.\nThe Hyde docs for instance use this.\n\nThe feature is enabled automatically when one or more of your documentation pages have the navigation.group property set\nin the front matter. This will then switch to a slightly more compact sidebar layout with pages sorted into categories.\nAny pages without the group front matter will get put in the \"Other\" group.\n\nSidebar footer customization\n\nThe sidebar footer contains, by default, a link to your site homepage. You can change this in the config\/docs.php file.\n\n\/\/ filepath: config\/docs.php\n\n'sidebar' => [\n 'footer' => 'My Markdown Footer Text',\n],\n\nYou can also set the option to false to disable it entirely.\n\nUsing Front Matter\n\nTo enable sidebar grouping, you can add the following front matter to your documentation pages:\n\nnavigation:\n group: \"Getting Started\"\n\nAutomatic subdirectory-based grouping\n\nYou can also automatically group your documentation pages by placing source files in sub-directories.\n\nFor example, putting a Markdown file in _docs\/getting-started\/, is equivalent to adding the same front matter seen above.\n\ninfo Note that when the 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.\n\nHiding items\n\nYou can hide items from the sidebar by adding the hidden property to the front matter:\n\nnavigation:\n hidden: true\n\nThis can be useful to create redirects or other items that should not be shown in the sidebar.\n\ninfo The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header. \n\nCustomization\n\nPlease see the customization page for in-depth information on how to customize Hyde,\nincluding the documentation pages. Here is a high level overview for quick reference though.\n\nOutput directory\n\nIf you want to store the compiled documentation pages in a different directory than the default 'docs' directory,\nfor example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file.\nThe path is relative to the site output, typically _site.\n\n\/\/ filepath: config\/hyde.php\n'output_directories' => [\n \\Hyde\\Pages\\DocumentationPage::class => 'docs' \/\/ default [tl! --]\n \\Hyde\\Pages\\DocumentationPage::class => 'docs\/1.x' \/\/ What the Hyde docs use [tl! ++]\n]\n\nNote 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.\n\nAutomatic navigation menu\n\nBy 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 for more information.\n\nSidebar header name\n\nBy default, the site title shown in the sidebar header is generated from the configured site name suffixed with \"docs\".\nYou can change this in the Docs configuration file. Tip: The header will link to the docs\/index page, if it exists.\n\n'title' => 'API Documentation',\n\nSidebar page order\n\nTo 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.\nLink items without an entry here will have fall back to the default priority of 999, putting them last.\n\n'sidebar_order' => [\n 'readme',\n 'installation',\n 'getting-started',\n]\n\nSee the chapter in the customization page for more details. \n\nAutomatic sidebar group labels\n\nWhen using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names.\nIf these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file.\nThe array key is the directory name, and the value is the label.\n\nPlease 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!\n\n\/\/ Filepath: config\/docs.php\n\n'sidebargrouplabels' => [\n 'questions-and-answers' => 'Questions & Answers',\n],\n\nTable of contents settings\n\nIn the config\/docs.php file you can configure the behaviour, content, and the look and feel of the sidebar table of contents.\nYou can also disable the feature completely.\n\n'tableofcontents' => [\n 'enabled' => true,\n 'minheadinglevel' => 2,\n 'maxheadinglevel' => 4,\n 'smoothpagescrolling' => true,\n],\n\nUsing flattened output paths\n\nIf this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory.\nThis means that you can use the automatic directory-based grouping feature, but still have a \"flat\" output structure.\nNote 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.\n\nIf you set this to false, Hyde will match the directory structure of the source files (just like all other pages).\n\n\/\/ Filepath: config\/docs.php\n'flattenedoutputpaths' => true,\n\nSearch feature\n\nIntroduction\n\nThe HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator\nthat runs during the build command, and a frontend JavaScript plugin that adds the actual search widget.\n\ninfo Tip: The HydeSearch plugin is what powers the search feature on this site! Why not try it out?\n\nThe search feature is enabled by default. You can disable it by removing the documentationSearch from the Hyde Features config array.\n\n\/\/ filepath: config\/hyde.php\n'features' => [\n Features::documentationSearch(), \/\/ [tl! --]\n],\n\nUsing the search\n\nThe search works by generating a JSON search index which the JavaScript plugin loads asynchronously.\n\nTwo ways to access the search are added, one is a full page search screen that will be saved to docs\/search.html.\n\nThe second method is a button added to the documentation pages, similar to how Algolia DocSearch works.\nOpening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut \/.\n\ninfo The full page can be disabled by setting createsearchpage to false in the docs config.\n\nHiding pages from indexing\n\nIf you have a large page on your documentation site, like a changelog, you may want to hide it from the search index.\nYou can do this by adding the page identifier to the excludefromsearch array in the docs config, similar to how\nnavigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file.\n\n\/\/ filepath: config\/docs.php\n'excludefromsearch' => [\n 'changelog',\n]\n\nLive search with the realtime compiler\n\nThe Realtime Compiler that powers the php hyde serve command will automatically generate a fresh search index each time the browser requests it.\n\nAutomatic \"Edit Page\" button\n\nIntroduction\n\nHyde can automatically add links to documentation pages that take the user\nto a GitHub page (or similar) to edit the page. This makes it great for open-source projects\nlooking to allow others to contribute to the documentation in a quick and easy manner.\n\nThe feature is automatically enabled when you specify a base URL in the Docs configuration file.\nHyde expects this to be a GitHub path, but it will probably work with other methods as well,\nif not, please send a PR and\/or create an issue on the GitHub repository!\n\ninfo Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out!\n\nConfiguration\n\nAs an example configuration, let's take a practical example of how HydePHP.com uses this feature.\n\n\/\/ Filepath: config\/docs.php\n\n'sourcefilelocation_base' => 'https:\/\/github.com\/hydephp\/docs\/blob\/master\/',\n\nChanging the button text\n\nChanging the label is easy, just change the following config setting:\n\n\/\/ Filepath: config\/docs.php\n'editsourcelink_text' => 'Edit Source on GitHub',\n\nChanging the position\n\nBy default, the button will be shown in both the documentation page footer.\nYou can change this by setting the following config setting to 'header', 'footer', or 'both'\n\n\/\/ Filepath: config\/docs.php\n'editsourcelink_position' => 'header',\n\nAdding a button icon\n\nThis is not included out of the box, but is easy to add with some CSS!\nJust target the .edit-page-link class.\n\n\/\/ filepath e.g. app.css\n.edit-page-link::before {content: \"\u270f \"}\n\nChanging the Blade view\n\nYou can also publish the edit-source-button.blade.php view and change it to your liking.","destination":"documentation-pages.html"},{"slug":"managing-assets","title":"Managing and Compiling Assets","content":"Managing and Compiling Assets\n\nIntroduction\n\nManaging and compiling assets is a very common task in web development. Unfortunately, it's rarely fun.\n\nWith Hyde, you don't have to do it, in fact, you can skip this entire page if you are happy with how it is.\nBut as always with Hyde, you can customize everything if you want to.\n\nHyde ships with a complete frontend using Blade views, TailwindCSS styles, and Alpine.js interactions.\nSome extra custom styles are made in the HydeFront package, which is pre-installed and bundled in the pre-configured Laravel Mix.\n\nTo get you started quickly, all the styles are already compiled and minified into _media\/app.css,\nwhich will be copied to the _site\/media\/app.css directory when you run php hyde build.\n\nAdditional Information and Answers to Common Questions\n\nIs NodeJS\/NPM Required for Using Hyde?\n\nNo, it is optional. All the compiled styles that you need are already installed, and NPM is only necessary if you want to compile your own styles.\n\nWhen Should Assets be Compiled?\n\nThe _media\/app.css file that comes with Hyde contains TailwindCSS for all classes that are used in the default Blade views, as well as the HydeFront custom styles.\nIf you want to customize the Tailwind settings or add custom styles, you will need to recompile the styles yourself.\n\nFor example, if you customize the Blade views and add new classes or add new classes in Blade-based pages, you may need to compile the assets yourself to get the new styles.\nIf you use Markdown-based pages, you do not need to compile anything as those styles are already included in the compiled CSS file.\n\nHow are assets stored and managed?\n\nThe frontend assets are separated into three places.\n\n- The resources\/assets folder contain source files, meaning files that will be compiled into something else.\nHere you will find the app.css file that bootstraps the TailwindCSS styles. This file is also an excellent place\nto add your custom styles. It is also where we import HydeFront. If you compile this file in the base install,\nit will output the same file that's already included in Hyde.\n\n- The _media folder contains compiled (and usually minified) files. When Hyde compiles your static site,\nall asset files here will get copied as they are into the _site\/media folder.\n\n- The _site\/media folder contains the files that are served to the user.\n\nWhat is the difference between media and site\/media?\n\nIt may seem weird to have two folders for storing the compiled assets, but it is quite useful.\n\nThe site directory is intended to be excluded from version control, while the media folder is included in the\nversion control. You are of course free to modify this behaviour by editing the webpack.mix.js file to change the output directory.\n\nHow do I compile assets?\n\nFirst, make sure that you have installed all the NodeJS dependencies using npm install.\nThen run npm run dev to compile the assets. If you want to compile the assets for production, run npm run prod.\nYou can also run npm run watch to watch for changes in the source files and recompile the assets automatically.\n\nHow does it work?\n\nHyde uses Laravel Mix (which is a wrapper for Webpack) to compile the assets.\n\nWhen running the npm run dev\/prod command, the following happens:\n\n1. Laravel Mix will compile the resources\/assets\/app.css file into _media\/app.css using PostCSS with TailwindCSS and AutoPrefixer.\n2. Mix then copies the media folder into site\/media, this is so that they are automatically accessible to your site without having to rerun php hyde build.\n\nTelling Hyde where to find assets\n\nCustomizing the Blade templates\n\nTo make it really easy to customize asset loading, the styles and scripts are loaded in dedicated Blade components.\n\n- Styles are loaded in hyde::layouts.styles\n- Scripts are loaded in hyde::layouts.scripts\n\nTo customize them, run the following command:\n\nphp hyde publish:views layouts\n\nThen edit the files found in resources\/views\/vendor\/hyde\/layouts directory of your project.\n\nYou might not even need to do anything!\n\nFor the absolute majority of the cases, you don't need to mess with these files. Hyde will automatically load the app.css file when it exists in the _media directory.\n\nLoading from CDN\n\nIf you want to load the same pre-compiled file included with Hyde but from a CDN, you can set loadappstylesfromcdn to true in the config\/hyde.php file. While you lose the ability to customize it, your styles will be automatically updated when needed, as the installed Framework version will automatically specify the correct version to load.\n\nUsing the TailwindCSS Play CDN\n\nwarning Note that the Play CDN is not meant for production use, so enabling it will add a warning to the web console.\n\nIf you want to use the TailwindCSS Play CDN, all you need to do is\nset useplaycdn to true in the config\/hyde.php file. This will in addition to loading the standard app.css file,\nalso add a script tag which loads the TailwindCSS Play CDN.\n\nWhat's even better is that Hyde will also inject the contents of the included tailwind.config.js file into the script tag,\nso the Play CDN styles match the ones created by Laravel Mix.\n\nAll in all, this allows you to tinker around with Tailwind without having to compile anything.\n\nManaging images\n\nAs mentioned above, assets stored in the media folder are automatically copied to the site\/media folder,\nmaking it the recommended place to store images. You can then easily reference them in your Markdown files.\n\nReferencing images\n\nThe recommended way to reference images is with relative paths as this offers the most compatibility,\nallowing you to browse the site both locally on your filesystem and on the web when serving from a subdirectory.\n\nwarning Note: The path is relative to the compiled file in the site output\n\nThe path to use depends on the location of the page. Note the subtle difference in the path prefix.\n\n- If you are in a Blog Post or Documentation Page, use ..\/media\/image.png\n- If in a Markdown Page or Blade Page, use media\/image.png\n- While not recommended, you can also use absolute paths: \/media\/image.png\n- You can of course also use full URLs, for example when using a CDN.\n\nMaking images accessible\n\nTo improve accessibility, you should always add an alt text. Here is a full example including an image in a blog post:\n\nImage Alt # Note the relative path\n\nSetting a featured image for blog posts\n\nHyde offers great support for creating data-rich and accessible featured images for blog posts.\n\nYou can read more about this on the creating blog posts page.","destination":"managing-assets.html"},{"slug":"static-pages","title":"Creating Static Pages","content":"# Creating Static Pages\n\n## Introduction to Hyde Pages\n\nHyde offers two ways to create static pages:\nMarkdown pages which are perfect for simple pages that focus heavily on the content,\nand Blade pages which are perfect for more complex pages where you want full control over the HTML,\nand where you may want to include other components or want to use dynamic PHP code.\n\nLet's start with the basics.\n\n### Best Practices and Hyde Expectations\n\nSince Hyde does a lot of things automatically, there are some things you may need\nto keep in mind when creating blog posts so that you don't get unexpected results.\n\n#### Filenames\n\n- Hyde Pages are files stored in the _pages directory\n- The filename is used as the filename for the compiled HTML\n- Filenames should use kebab-case-identifier format, followed by the appropriate extension\n- Files prefixed with _underscores are ignored by Hyde\n- Your page will be stored in _site\/.html\n- Blade pages will override any Markdown pages with the same filename when compiled\n\n## Creating Markdown Pages\n\nMarkdown pages are the easiest way to create static pages. You can create a Markdown page by adding a file to the\n_pages directory where the filename ends in .md. You can also use Front Matter to add page metadata.\n\n### Scaffolding Markdown Pages\n\nScaffolding a Markdown page is as easy as using the HydeCLI.\n\nphp hyde make:page \"Page Title\"\n\nThis will create the following file saved as _pages\/page-title.md\n\ntitle: Page Title\n# Page Title\n\n\/\/ Write your content here\n\nYou can of course also create the file yourself with your text editor.\n\n### Front Matter is optional\n\nThe most common front matter used for Markdown pages is the title, which is used as the HTML ``.\n\nIf you don't supply a front matter title, Hyde will attempt to find a title in the Markdown body by searching\nfor the first level one heading (# Page Title), and if that fails, it will generate one from the filename.\n\n#### Navigation Front Matter\n\nFurthermore, you can customize how the page appears in the navigation menu using the following front matter options.\nYou can set just one or all of them, as Hyde will fill in the gaps for the rest.\n\nnavigation:\n label: 'string',\n priority: 'int',\n hidden: 'bool',\n group: 'string',\n\n- label is the text that will be displayed in the navigation menu\n- priority is the order in which the page will appear in the navigation menu (order is also supported)\n- hidden will hide the page from the navigation menu (visible) is also supported, but obviously invert the value)\n- group will put the page in a dropdown menu with the specified group name (category) is also supported)\n\n## Creating Blade Pages\n\nSince Hyde is based on Laravel and uses the powerful Blade templating engine, you can use Blade pages to create more\ncomplex pages with both standard HTML, PHP code, and the templating opportunities provided by Blade directives.\n\nIf you are not familiar with Blade, you may want to read the Laravel Blade docs first.\n\n### Scaffolding Blade Pages\n\nWe can scaffold Blade pages using the same CLI command as Markdown pages, however, this time we need to specify that\nwe want to use the blade page type, by using the --type option.\n\nphp hyde make:page \"Page Title\" --type=\"blade\"\n\nThis will create a file saved as _pages\/page-title.blade.php\n\nYou can of course also create the file yourself with your text editor, however,\nthe scaffolding command for Blade pages is arguably even more helpful than the\none for Markdown pages, as this one automatically adds the included app Layout.\n\nLet's take a look at the scaffolded file. You can also copy and paste this\nif you don't want to use the scaffolding command.\n\n@extends('hyde::layouts.app')\n@section('content')\n@php($title = \"Page Title\")\n\n Page Title\n\n@endsection\n\nTip: You don't have to use Blade in Blade pages. It's also perfectly fine to use plain HTML,\nhowever you still need to use the blade.php extension so Hyde can recognize it.\n\n## When to use which?\n\nMarkdown pages look great and work well for simple \"about\" pages and the like, but with Markdown we are still pretty limited.\n\nIf you are comfortable with it and have the need for it, use Blade to create more complex pages! And mix and match between them!\nSome page types are better suited for Markdown, and others for Blade. Don't limit yourself to just one type.\n\n### Comparison\n\nMarkdown Blade\n\n\u2795 Easily created and updated \u2795 Full control over the HTML\n\u2795 Very fast to create simple and lightweight pages \u2795 Use the default app layout or create your own\n\u2795 Suited for content-heavy pages such as \"about us\" \u2795 Use Blade templates and components to keep code DRY\n\u2796 Not as flexible as Blade pages \u2795 Use arbitrary PHP right in the page to create dynamic content\n \u2795 Access to all Blade helper directives like @foreach, @if, etc.\n \u2796 Takes longer to create as you need to write the markup\n \u2796 You may need to recompile your CSS if you add Tailwind classes\n\n### Live Demos\n\nThe Hyde website (hydephp.com) uses both Markdown and Blade pages. The homepage for example, is a Blade page and uses a bunch of custom HTML.\n\nA great example of a Markdown page can be found at hydephp.github.io\/portfolio-demo, you can see the page source here on GitHub.\n\n## Bonus: Creating HTML Pages\n\nIf you have an already created HTML page, simply drop it into the _pages directory and Hyde will copy it over as it is\ninto the _site directory. Like all other Hyde pages, the page will show up in the navigation menu using a title parsed from the filename.\nYou won't be able to change any settings with front matter, however.","destination":"static-pages.html"},{"slug":"advanced-customization","title":"Advanced Customization","content":"Advanced Customization\n\nIntroduction\n\nThis page covers advanced usage and is intended for developers who know what they are doing. Documentation here will be\nmainly example driven, as it is assumed you have somewhat of an understanding of what you are doing already.\n\nPrerequisites for customizing directories\n\ninfo Before customizing source and output directories it may be helpful to know how these settings are stored internally.\n\nThe following is a summary from the Page Models documentation:\n\nEach page type is represented by a page model class. Each of those classes have static properties that store the source and output directories.\nThese properties are set when the HydeServiceProvider\nis registered, at which point the provider will search for any overrides in the config file.\n\nThis means that there are two options to change the source and output directories:\n1. Recommended: You can change the values in the config file, to let the HydeServiceProvider handle it for you.\n2. Advanced\/Overkill: You can also set the static properties directly in the page model classes if you prefer.\n - You'd probably want to do this in a service provider, as it must be done before the Kernel is booted.\n - You can use the RegistersFileLocations\n trait to use the same registration logic as the HydeServiceProvider.\n\nCustomizing source directories\n\nThe directories you place your content in are important. The directory will be used to determine the proper page type and the templates used.\nIf you are not happy the with defaults, you can change them. Note that these are relative to the source_root setting,\nwhich is the root of your project, by default.\n\nNote that you need to take care of conflicts when changing the source directories. For example, if you store Markdown\nposts in the same directory as documentation pages, Hyde will not know which page type to use.\n\nIn the config file\n\n\/\/ filepath config\/hyde.php\n\n'source_directories' => [\n HtmlPage::class => '_pages',\n BladePage::class => '_pages',\n MarkdownPage::class => '_pages',\n MarkdownPost::class => '_posts',\n DocumentationPage::class => '_docs',\n],\n\nIn a service provider\n\n\/\/ filepath app\/AppServiceProvider.php\nuse Hyde\\Framework\\Concerns\\RegistersFileLocations;\n\npublic function register(): void\n{\n $this->registerSourceDirectories([\n HtmlPage::class => '_pages',\n BladePage::class => '_pages',\n MarkdownPage::class => '_pages',\n MarkdownPost::class => '_posts',\n DocumentationPage::class => '_docs',\n ]);\n}\n\nCustomizing output directories\n\nLike source directories, the output directories are also important as they determine the output path for the compiled pages.\nwarning Note that changing output directories also affects the route keys, as those are based on the output directory. Scroll down to see the Route key impact section for more information.\n\nEach option is relative to the site's output_directory setting. Setting a value to '' will output the page to the site root.\n\nIn the config file\n\n\/\/ filepath config\/hyde.php\n'output_directories' => [\n HtmlPage::class => '',\n BladePage::class => '',\n MarkdownPage::class => '',\n MarkdownPost::class => 'posts',\n DocumentationPage::class => 'docs',\n],\n\nIn a service provider\n\n\/\/ filepath app\/AppServiceProvider.php\nuse Hyde\\Framework\\Concerns\\RegistersFileLocations;\n\npublic function register(): void\n{\n $this->registerOutputDirectories([\n HtmlPage::class => '',\n BladePage::class => '',\n MarkdownPage::class => '',\n MarkdownPost::class => 'posts',\n DocumentationPage::class => 'docs',\n ]);\n}\n\nRoute key impact\n\nFor example, changing the output directory of Markdown posts to blog instead of posts will change the route key base from posts to blog.\nThis means that a file stored as _posts\/hello-world.md will have the route key blog\/hello-world instead of posts\/hello-world,\nthis may break your site's configuration and links, so you should always verify your site works properly after such a change.\nYou can learn more about this in the route key documentation.\n\nCustom source root\n\nHydePHP will by default look for the source directories shown above in the root of your project.\nIf you're not happy with this, it's easy to change! For example, you might want everything in a 'src' subdirectory.\nThat's easy enough, just set the value of the source_root setting in config\/hyde.php to 'src', or whatever you prefer!\n\n\/\/ filepath config\/hyde.php\n\n'source_root' => '', \/\/ [TL! --]\n'source_root' => 'src', \/\/ [TL! ++]\n\nAutomatic change\n\nYou can even make this change automatically with the php hyde change:sourceDirectory command!\n\nphp hyde change:sourceDirectory \n\nWhen run, Hyde will update the source directory setting in the config file, then create the directory if it doesn't exist,\nand move all source directories and their content into it.\n\nCustom media directory\n\nThe media directory houses assets like images and stylesheets. The default directory is _media, and upon building the site,\nHyde will copy all files in this directory to _site\/media (or whatever your configured output and media directories are).\n\nYou can change the path to this directory by setting the media_directory option in config\/hyde.php.\n\n\/\/ filepath config\/hyde.php\n'mediadirectory' => 'media',\n\nNext steps\n\n1. Note that you will likely need to manually update webpack.mix.js so Laravel Mix can compile the assets correctly.\n2. You will of course also need to copy over any existing files from the old directory to the new one.\n\nNote that this setting affects both source and output directories\n\nNote that this change will affect both the source and output directories. For example, if you set the value to assets,\nall files from assets will be copied to _site\/assets. If the setting starts with an underscore, that will be removed\nfrom the output directory, so files in assets will be copied to site\/assets.\n\nCustom output directory\n\ndanger Warning: Hyde deletes all files in the output directory before compiling the site. Don't set this path to a directory that contains important files!\n\nIf you want to store your compiled website in a different directory than the default _site, you can change the path\nusing the following configuration option in config\/hyde.php. The path is expected to be relative to your project root.\n\n\/\/ filepath config\/hyde.php\n'outputdirectory' => 'site',","destination":"advanced-customization.html"},{"slug":"advanced-markdown","title":"Advanced Markdown","content":"Advanced Markdown\n\nIntroduction\n\nSince HydePHP makes heavy use of Markdown, there are some extra features and helpers created just for Hyde to make using Markdown even easier and more powerful!\n\nUsing Blade in Markdown\n\nA special feature in Hyde, is that you can use Laravel Blade in Markdown files!\n\nTo use Blade in your Markdown files, simply use the Blade shortcode directive, followed by your desired Blade string.\n\nStandard syntax\n\n [Blade]: {{ \"Hello World!\" }} \/\/ Will render: 'Hello World!'\n\nBlade includes\n\nOnly single-line shortcode directives are supported. If you need to use multi-line Blade code, use an @include\ndirective to render a more complex Blade template. You can pass data to includes by specifying an array to the second argument.\n\n [Blade]: @include(\"hello-world\")\n [Blade]: @include(\"hello\", [\"name\" => \"World\"])\n\nEnabling Blade-supported Markdown\n\nThe feature is disabled by default since it allows arbitrary PHP to run, which could be a security risk, depending on your setup.\nHowever, if your Markdown is trusted, and you know it's safe, you can enable it in the config\/markdown.php file.\n\n\/\/ filepath: config\/markdown.php\n'enable_blade' => true,\n\nLimitations\n\nAll shortcodes must be the first word on a new line, and only single-line shortcodes are supported.\n\nColoured Blockquotes\n\nThe HydePHP Markdown converter also supports some extra directives and features. One of them being four different\ncoloured blockquotes. Simply append the desired colour after the initial > character.\n\n\u200e> Normal Blockquote\n\u200e>info Info Blockquote\n\u200e>warning Warning Blockquote\n\u200e>danger Danger Blockquote\n\u200e>success Success Blockquote\n\nNormal Blockquote\ninfo Info Blockquote\nwarning Warning Blockquote\ndanger Danger Blockquote\nsuccess Success Blockquote\n\nCustomizations\n\nYou can easily customize these styles too by adding and editing the following in your resources\/app.css file, and then recompiling your site styles.\nThe code examples here use the Tailwind @apply directives, but you could also use border-color: something; just as well.\n\n\/* filepath resources\/app.css\n\n\/* Markdown Features *\/\n\n.prose blockquote.info {\n @apply border-blue-500;\n}\n\n.prose blockquote.success {\n @apply border-green-500;\n}\n\n.prose blockquote.warning {\n @apply border-amber-500;\n}\n\n.prose blockquote.danger {\n @apply border-red-600;\n}\n\nMarkdown usage\n\nThe coloured blockquotes also support inline Markdown, just like normal blockquotes.\n\n\u200e>info Formatting is supported!\n\nLimitations\n\nNote that these currently do not support multi-line blockquotes.\n\nCode block filepaths\n\nWhen browsing these documentation pages you may have noticed a label in the top right corner of code blocks specifying the file path.\nThese are also created by using a custom Hyde feature that turns code comments into automatic code blocks.\n\nUsage\n\nSimply add a code comment with the path in the first line of a fenced code block like so:\n\n\/\/ Filepath: _docs\/advanced-markdown.md\n\u200e\/\/ Filepath: hello-world.php\n\necho 'Hello World!';\n\nWhich becomes:\n\n\/\/ Filepath: hello-world.php\n\necho 'Hello World!';\n\nAlternative syntax\n\nThe syntax is rather forgiving, by design, and supports using both \/\/ and # for comments.\nThe colon is also optional, and the 'filepath' string is case-insensitive. So the following is also perfectly valid:\n\n\u200e\/\/ filepath hello.js\nconsole.log('Hello World!');\n\nIf you have a newline after the filepath, like in the first example, it will be removed so your code stays readable.\n\nAdvanced usage\n\nIf you have enabled HTML in Markdown by setting the allow_html option to true in your config\/markdown.php file,\nanything within the path label will be rendered as HTML. This means you can add links, or even images to the label.\n\n\/\/ Filepath: View file on Github\n\u200e\/\/ Filepath: View file on Github\n\nLimitations\n\nThe filepaths are hidden on mobile devices using CSS to prevent them from overlapping with the code block.\n\nConfiguration\n\nFull configuration reference\n\nAll Markdown-related configuration options are in the config\/markdown.php file.\nYou can find the full reference on the Customization page.\n\nRaw HTML Tags\n\nTo convert Markdown, HydePHP uses the GitHub Flavored Markdown extension, which strips out potentially unsafe HTML.\nIf you want to allow all arbitrary HTML tags, and understand the risks involved, you can enable all HTML tags by setting\nthe allow_html option to true in your config\/markdown.php file.\n\n\/\/ filepath: config\/markdown.php\n'allow_html' => true,\n\nThis will add and configure the DisallowedRawHtml CommonMark extension so that no HTML tags are stripped out.\n\nTailwind Typography Prose Classes\n\nHydePHP uses the Tailwind Typography to style rendered Markdown.\nWe do this by adding the .prose CSS class to the HTML elements containing the rendered Markdown, using the built-in Blade components.\n\nYou can easily edit these classes, for example if you want to customize the prose colours, in the config\/markdown.php file.\n\n\/\/ filepath: config\/markdown.php\n'prose_classes' => 'prose dark:prose-invert', \/\/ [tl! remove]\n'prose_classes' => 'prose dark:prose-invert prose-img:inline', \/\/ [tl! add]\n\nPlease note that if you add any new classes, you may need to recompile your CSS file.","destination":"advanced-markdown.html"},{"slug":"collections","title":"File-based Collections","content":"# File-based Collections\n\n## Introduction to Hyde Data Collections\n\nHyde provides DataCollections, a subset of Laravel Collections giving you\na similar developer experience to working with Eloquent Collections. However, instead of accessing a database,\nit's all entirely file-based using static data files such as Markdown, Yaml, and JSON files which get\nparsed into objects that you can easily work with.\n\nAs you have access to all standard Laravel Collection methods, you are encouraged to read the\nLaravel Collections documentation for more information.\n\nThis article covers advanced usage intended for those who are writing their own Blade views, and is not required as Hyde comes pre-packaged with many templates for you to use.\n\n## High-Level Concept Overview\n\nTo make collections easy to use and understand, Hyde makes a few assumptions about the structure of your collections.\nFollow these conventions and creating dynamic static sites will be a breeze.\n\n1. Collections are accessed through static methods in the DataCollections class.\n2. Collections are stored as files in subdirectories of the resources\/collections directory.\n3. To get a collection, specify name of the subdirectory the files are stored in.\n4. Data will be parsed into differing objects depending on which facade method you use. See the table below.\n5. The class is aliased so that you can use it in Blade files without having to include the namespace.\n6. While not enforced, each subdirectory should probably only have the same filetype to prevent developer confusion\n7. Unlike source files for pages, files starting with underscores are not ignored.\n8. You can customize the source directory for collections through a service provider.\n9. If the base source directory does not exist, it will be created for you.\n\n## Available Collection Types\n\n### Quick Reference Overview\n\nThe following facade methods for creating data collections are available:\n\n\\Hyde\\Support\\DataCollections::markdown(string $name);\n\\Hyde\\Support\\DataCollections::yaml(string $name);\n\\Hyde\\Support\\DataCollections::json(string $name, bool $asArray = false);\n\n### Quick Reference Table\n\nCollection Type Facade Method Returned Object Type File Extension\n\nMarkdown ::markdown() MarkdownDocument .md\nYaml ::yaml() FrontMatter .yaml,  .yml\nJson ::json() stdClass OR  array .json\n\n## Markdown Collections\n\n### Usage\n\n$collection = \\Hyde\\Support\\DataCollections::markdown('name');\n\n### Example returns\n\nHere is an approximation of the data types contained by the variable created above:\n\n\\Hyde\\Support\\DataCollections {\n \"testimonials\/1.md\" => Hyde\\Markdown\\Models\\MarkdownDocument\n \"testimonials\/2.md\" => Hyde\\Markdown\\Models\\MarkdownDocument\n \"testimonials\/3.md\" => Hyde\\Markdown\\Models\\MarkdownDocument\n ]\n}\n\nThe returned MarkdownObjects look approximately like this:\n\n\\Hyde\\Markdown\\Models\\MarkdownDocument {\n +matter: Hyde\\Markdown\\Models\\FrontMatter {\n +data: array:1 [\n \"author\" => \"John Doe\"\n ]\n }\n +markdown: Hyde\\Markdown\\Models\\Markdown {\n +body: \"Lorem ipsum dolor sit amet, consectetur adipiscing elit...\"\n }\n}\n\nAssuming the Markdown document looks like this:\n\nauthor: \"John Doe\"\nLorem ipsum dolor sit amet, consectetur adipiscing elit...\n\n## Yaml Collections\n\n### Usage\n\n$collection = \\Hyde\\Support\\DataCollections::yaml('name');\n\n### Example returns\n\nHere is an approximation of the data types contained by the variable created above:\n\n\\Hyde\\Support\\DataCollections {\n \"authors\/1.yaml\" => Hyde\\Markdown\\Models\\FrontMatter {\n +data: array:1 [\n \"name\" => \"John Doe\",\n \"email\" => \"john@example.org\"\n ]\n }\n}\n\nAssuming the Yaml document looks like this:\n\nname: \"John Doe\"\nemail: \"john@example.org\"\n\nwarning Note that the Yaml file should start with --- to be parsed correctly.\n\n## Json Collections\n\n### Usage\n\n$collection = \\Hyde\\Support\\DataCollections::json('name');\n\nBy default, the entries will be returned as stdClass objects. If you want to return an associative array instead, pass true as the second parameter:\n\n$collection = \\Hyde\\Support\\DataCollections::json('name', true);\n\nSince both return values use native PHP types, there are no example returns added here, as I'm sure you can imagine what they look like.\n\n## Markdown Collections - Hands-on Guide\n\nI think the best way to explain DataCollections is through examples, so let's create a Blade page with customer testimonials!\n\nThis example will use Markdown Collections, but the same concepts apply to all other collection types.\n\n#### Setting up the file structure\n\nWe start by setting up our directory structure. We will create a testimonials subdirectory, which will be the collection name.\n\nIn it, we will place Markdown files. Each file will be a testimonial.\nThe Markdown will be parsed into a MarkdownDocument object which parses any optional YAML front matter.\n\nHere is the sample Markdown we will use:\n\n\/\/ filepath: resources\/collections\/testimonials\/1.md\nauthor: John Doe\nLorem ipsum dolor sit amet, consectetur adipiscing elit...\n\nLet's take a look at our directory structure. I just copied the same file a few times.\nYou can name the files anything you want, I kept it simple and just numbered them.\n\nresources\/collections\n\u2514\u2500\u2500 testimonials\n \u251c\u2500\u2500 1.md\n \u251c\u2500\u2500 2.md\n \u2514\u2500\u2500 3.md\n\n#### Using the Facade to Access the Collections\n\nNow for the fun part! We will use the DataCollections::markdown() to access all our files into a convenient object.\nThe class is registered with an alias, so you don't need to include any namespaces when in a Blade file.\n\nThe general syntax to use the facade is as follows:\n\nDataCollections::markdown('subdirectory_name')\n\nThis will return a Hyde DataCollections object, containing our Markdown files as MarkdownDocument objects. Here is a quick look at the object the facade returns:\n\n^ Hyde\\Support\\DataCollections {#651 \u25bc\n #items: array:3 [\u25bc\n \"testimonials\/1.md\" => Hyde\\Markdown\\Models\\MarkdownDocument {#653 \u25bc\n +matter: Hyde\\Markdown\\Models\\FrontMatter {#652 \u25b6}\n +markdown: Hyde\\Markdown\\Models\\Markdown {#654 \u25b6}\n }\n \"testimonials\/2.md\" => Hyde\\Markdown\\Models\\MarkdownDocument {#656 \u25b6}\n \"testimonials\/3.md\" => Hyde\\Markdown\\Models\\MarkdownDocument {#659 \u25b6}\n ]\n}\n\n#### Implementing it in a Blade view\n\nLet's create a Blade page to display all our testimonials.\n\nphp hyde make:page \"Testimonials\" --type=\"blade\"\n\nAnd we can use the collection almost like any other Laravel one. As you can see, since each entry is a MarkdownDocument class,\nwe are able to get the author from the front matter, and the content from the body.\n\n\/\/ filepath _pages\/testimonials.blade.php\n@foreach(DataCollections::markdown('testimonials') as $testimonial)\n \n {{ $testimonial->body }}\n {{ $testimonial->matter['author'] }}\n \n@endforeach","destination":"collections.html"},{"slug":"customization","title":"Customizing your Site","content":"# Customizing your Site\n\n## Introduction\n\nHyde favours \"Convention over Configuration\"\nand comes preconfigured with sensible defaults. However, Hyde also strives to be modular and endlessly customizable\nif you need it. This page guides you through the many options available!\n\nAll the configuration files are stored in the config directory, and allow you to customize almost all aspects of your site.\nEach option is documented, so feel free to look through the files and get familiar with the options available to you.\n\n## Accessing Configuration Values\n\n### Configuration API Recap\n\nHydePHP uses the same configuration system as Laravel. Here's a quick recap from the Laravel Documentation:\n\nYou may easily access your configuration values using the global config function from anywhere in your project code.\nThe configuration values may be accessed using \"dot notation\" syntax, which includes the name of the file and option you wish to access.\n\n$value = config('hyde.name');\n\nA default value may also be specified and will be returned if the configuration option does not exist:\n\n$value = config('hyde.name', 'HydePHP');\n\nHydePHP also provides a strongly typed Config facade which extends the Laravel Config facade, but allows strict types:\n\nuse Hyde\\Facades\\Config;\n\n\/\/ Will always return a string, or it throws a TypeError\n$name = Config::getString('hyde.name', 'HydePHP'): string;\n\n### Dot Notation\n\nAs seen in the example above, when referencing configuration options, we often use \"dot notation\" to specify the configuration file.\nFor example, config('hyde.name') means that we are looking for the name option in the config\/hyde.php file.\n\n### Front Matter or Configuration Files?\n\nIn some cases, the same options can be set in the front matter of a page or in a configuration file. Both ways are always documented, and it's up to you to choose which one you prefer. Note that in most cases, if a setting is set in both the front matter and the configuration file, the front matter setting will take precedence.\n\n### A note on file paths\n\nWhen Hyde references files, especially when passing filenames between components, the file path is almost always\nrelative to the root of the project. Specifying absolute paths yourself could lead to unforeseen problems.\n\n## Configuration Files Overview\n\nThere are a few configuration files available in the config directory. All options are documented, so feel free to look through the files and get familiar with the options available to you.\n\nBelow are two tables over the different configuration files. Click on a file name to see the default file on GitHub.\n\n### HydePHP Configuration Files\n\nThese are the main configuration files for HydePHP and lets you customize the look and feel of your site, as well as the behaviour of HydePHP itself.\nThe main configuration file, hyde.php, is used for things ranging from site name and base URL to navigation menus and what features to enable.\n\nConfig File Description\n\nhyde.php Main HydePHP configuration file for customizing the overall project.\ndocs.php Options for the HydePHP documentation site generator module.\nmarkdown.php Configure Markdown related services, as well as change the CommonMark extensions.\napp\/config.php Configures the underlying Laravel application. (Commonly found as config\/app.php in Laravel apps)\n\ninfo Tip: The values in hyde.php can also be set in YAML by creating a hyde.yml file in the root of your project. See #yaml-configuration for more information.\n\n### Publishable Laravel & Package Configuration Files\n\nSince HydePHP is based on Laravel we also have a few configuration files related to them. As you most often don't need\nto edit any of these, unless you want to make changes to the underlying application, they are not present in the\nbase HydePHP installation. However, you can publish them to your project by running php hyde publish:configs.\n\nConfig File Description\n\nview.php Configures the paths for the Blade View compiler.\ncache.php Configures the cache driver and cache path locations.\ncommands.php Configures the Laravel Zero commands for the HydeCLI.\ntorchlight.php Configures settings for the Torchlight syntax highlighting integration.\n\n{.align-top}\n\nIf any of these files are missing, you can run php hyde publish:configs to copy the default files to your project.\n\n## Configuration Options\n\nWhile all options are already documented within the files, here are some further explanations of some of the options.\n\n### RSS feed generation\n\nWhen enabled, an RSS feed containing all your Markdown blog posts will be generated when you compile your static site.\nHere are the default settings:\n\n\/\/ filepath config\/hyde.php\n'rss' => [\n \/\/ Should the RSS feed be generated?\n 'enabled' => true,\n\n \/\/ What filename should the RSS file use?\n 'filename' => 'feed.xml',\n\n \/\/ The channel description.\n 'description' => env('SITE_NAME', 'HydePHP').' RSS Feed',\n],\n\nwarning Note that this feature requires that a site url is set!\n\n### Authors\n\nHyde has support for adding authors in front matter, for example to\nautomatically add a link to your website or social media profiles.\nHowever, it's tedious to have to add those to each and every\npost you make, and keeping them updated is even harder.\n\nYou can predefine authors in the Hyde config.\nWhen writing posts, just specify the username in the front matter,\nand the rest of the data will be pulled from a matching entry.\n\n#### Example\n\n\/\/ torchlight! {\"lineNumbers\": false}\n'authors' => [\n Author::create(\n username: 'mr_hyde', \/\/ Required username\n name: 'Mr. Hyde', \/\/ Optional display name\n website: 'https:\/\/hydephp.com' \/\/ Optional website URL\n ),\n],\n\nThis is equivalent to the following front matter in a blog post:\n\nauthor:\n username: mr_hyde\n name: Mr. Hyde\n website: https:\/\/hydephp.com\n\nBut you only have to specify the username:\n\nauthor: mr_hyde\n\n### Footer\n\nMost websites have a footer with copyright details and contact information. You probably want to change the Markdown to include your information, though you are of course welcome to keep the default attribution link!\n\nThe footer component is made up of a few levels of components, depending on how much you want to customize.\n\n#### Customizing the Markdown text\n\nThere are two ways to customize the footer text. First, you can set it in the configuration file:\n\n\/\/ filepath: config\/hyde.php\n'footer' => 'Site proudly built with HydePHP \ud83c\udfa9',\n\nIf you don't want to write Markdown in the configuration file, you can create a Markdown file in your includes directory. When this file is found, it will be used instead of the configuration setting.\n\n\/\/ filepath: resources\/includes\/footer.md\nSite proudly built with HydePHP \ud83c\udfa9\n\nIn both cases the parsed Markdown will be rendered in the footer Blade component.\n\n#### Customizing the Blade component\n\nThe actual footer component is rendered using the layouts\/footer.blade.php Blade template.\n\nIn this template we automatically render the configured footer Markdown text. If you want to change this behaviour, for example, HydePHP.com uses a more sophisticated footer, simply publish the footer component.\n\n#### Disabling the footer entirely\n\nIf you don't want to have a footer on your site, you can set the 'footer' configuration option to false.\n\n\/\/ filepath: config\/hyde.php\n'footer' => 'false',\n\n### Navigation Menu & Sidebar\n\nA great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation.\nHyde is designed to automatically configure these menus for you based on the content you have in your project.\n\nStill, you will likely want to customize some parts of these menus, and thankfully, Hyde makes it easy to do so.\n\n#### Customizing the navigation menu\n\n- To customize the navigation menu, use the setting navigation.order in the hyde.php config.\n- When customizing the navigation menu, you should use the route key of the page.\n\nLearn more in the Navigation Menu documentation.\n\n#### Customizing the documentation sidebar\n\n- To customize the sidebar, use the setting sidebar_order in the docs.php config.\n- When customizing the sidebar, can use the route key, or just the page identifier of the page.\n\nLearn more in the Documentation Pages documentation.\n\ninfo Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key.\n\n### Primer on priorities\n\nAll navigation menu items have an internal priority value that determines its order in the navigation.\nLower values means that the item will be higher up in the menu. The default for pages is 999 which puts them last.\nHowever, some pages are autoconfigured to have a lower priority, for example, the index page defaults to a priority of 0,\n\n#### Basic syntax for changing the priorities\n\nThe 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.\nThe offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings.\n\n[\n 'readme', \/\/ Gets priority 500\n 'installation', \/\/ Gets priority 501\n 'getting-started', \/\/ Gets priority 502\n]\n\n#### Explicit syntax for changing the priorities\n\nYou can also specify explicit priorities by adding a value to the array key:\n\n[\n 'readme' => 10, \/\/ Gets priority 10\n 'installation' => 15, \/\/ Gets priority 15\n 'getting-started' => 20, \/\/ Gets priority 20\n]\n\nYou can also combine these options if you want:\n\n[\n 'readme' => 10, \/\/ Gets priority 10\n 'installation', \/\/ Gets priority 500\n 'getting-started', \/\/ Gets priority 501\n]\n\nYou can also set the priority of a page directly in the front matter. This will override any dynamically inferred or\nconfig defined priority. While this is useful for one-offs, it can make it harder to reorder items later on.\nIt's up to you which method you prefer to use. This setting can be used both for the navigation menu and the sidebar.\n\nnavigation:\n priority: 25\n\n#### Changing the menu item labels\n\nHyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles.\nYou can override the label using the navigation.label front matter property.\n\nFrom the Hyde config you can also override the label of navigation links using the by mapping the route key\nto the desired title. Note that the front matter property will take precedence over the config property.\n\n\/\/ filepath config\/hyde.php\n'navigation' => [\n 'labels' => [\n 'index' => 'Start',\n 'docs\/index' => 'Documentation',\n ]\n]\n\n#### Excluding Items (Blacklist)\n\nSometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu.\nTo remove items from being automatically added, simply add the page's route key to the blacklist.\nAs you can see, the 404 page has already been filled in for you.\n\n\/\/ filepath config\/hyde.php\n'navigation' => [\n 'exclude' => [\n '404'\n ]\n]\n\nYou can also specify that a page should be excluded by setting the page front matter.\n\nnavigation:\n hidden: true\n\n#### Adding Custom Navigation Menu Links\n\nYou can easily add custom navigation menu links similar how we add Authors. Simply add a NavItem model to the navigation.custom array.\n\nWhen linking to an external site, you should use the NavItem::forLink() method facade. The first two arguments are the\ndestination and label, both required. Third argument is the priority, which is optional, and defaults to 500.\n\n\/\/ filepath config\/hyde.php\nuse Hyde\\Framework\\Features\\Navigation\\NavItem;\n\n'navigation' => [\n 'custom' => [\n NavItem::forLink('https:\/\/github.com\/hydephp\/hyde', 'GitHub', 200),\n ]\n]\n\nSimplified, this will then be rendered as follows:\n\nGitHub\n\n#### Automatic navigation menu dropdowns\n\nHydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories.\n\nFor pages that can be in the main site menu, ths feature needs to be enabled in the hyde.php config file.\n\n\/\/ filepath config\/hyde.php\n\n'navigation' => [\n 'subdirectories' => 'dropdown',\n],\n\nNow if you create a page called _pages\/about\/contact.md it will automatically be placed in a dropdown called \"About\".\n\n#### Automatic documentation sidebar grouping\n\nThis feature works similarly to the automatic navigation menu dropdowns, but instead place the sidebar items in named groups.\nThis feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped.\n\nFor example: _docs\/getting-started\/installation.md will be placed in a group called \"Getting Started\".\n\n## Additional Advanced Options\n\nThe following configuration options in the confg\/hyde.php file are intended for advanced users and \nshould only be modified if you fully understand their impact. The code examples show the default values.\n\n### media_extensions\n\nThis option allows you to specify file extensions considered as media files, which will be copied to the output directory. \nTo add more extensions, either append them to the existing array or override the entire array.\n\n\/\/ filepath config\/hyde.php\nuse \\Hyde\\Support\\Filesystem\\MediaFile;\n\n'mediaextensions' => arraymerge([], MediaFile::EXTENSIONS),\n\n### safeoutputdirectories\n\nThis setting defines a list of directories deemed safe to empty during the site build process as a safeguard to prevent accidental data loss.\nIf the site output directory is not in this list, the build command will prompt for confirmation before emptying it. It is preconfigured\nwith common directories including the default one, but you are free to change this to include any custom directories you may need.\n\n\/\/ filepath config\/hyde.php\n'safeoutputdirectories' => ['_site', 'docs', 'build'],\n\n### generatebuildmanifest\n\nDetermines whether a JSON build manifest with metadata about the build should be generated. Set to true to enable.\n\n\/\/ filepath config\/hyde.php\n'generatebuildmanifest' => true,\n\n### buildmanifestpath\n\nSpecifies the path where the build manifest should be saved, relative to the project root.\n\n\/\/ filepath config\/hyde.php\n'buildmanifestpath' => 'app\/storage\/framework\/cache\/build-manifest.json',\n\n### hydefrontversion and hydefrontcdn_url\n\nThese options allow you to specify the HydeFront version and CDN URL when loading app.css from the CDN.\n\nOnly change these if you know what you're doing as some versions may incompatible with your Hyde version.\n\n\/\/ filepath config\/hyde.php\nuse \\Hyde\\Framework\\Services\\AssetService;\n\n'hydefrontversion' => AssetService::HYDEFRONTVERSION,\n'hydefrontcdnurl' => AssetService::HYDEFRONTCDNURL,\n\n## Blade Views\n\nHyde uses the Laravel Blade templating engine. Most parts of the included templates have been extracted into components to be customized easily.\nBefore editing the views you should familiarize yourself with the Laravel Blade Documentation.\n\nTo edit a default Hyde component you need to publish them first using the hyde publish:views command.\n\nphp hyde publish:views\n\nThe files will then be available in the resources\/views\/vendor\/hyde directory.\n\n## Frontend Styles\n\nHyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template\nfor you to get up and running quickly. If you want to customize these, you are free to do so.\nPlease see the Managing Assets page to learn more.\n\n## Markdown Configuration\n\nHyde uses League CommonMark for converting Markdown into HTML, and\nuses the GitHub Flavored Markdown extension. The Markdown related settings are found in the config\/markdown.php file.\nBelow follows an overview of the Markdown configuration options available in Hyde.\n\n### CommonMark Extensions\n\nYou can add any extra CommonMark Extensions,\nor change the default ones, using the extensions array in the config file. They will then automatically be loaded into\nthe CommonMark converter environment when being set up by Hyde.\n\n\/\/ filepath: config\/markdown.php\n'extensions' => [\n \\League\\CommonMark\\Extension\\GithubFlavoredMarkdownExtension::class,\n \\League\\CommonMark\\Extension\\Attributes\\AttributesExtension::class,\n],\n\nRemember that you may need to install any third party extensions through Composer before you can use them.\n\n### CommonMark Configuration\n\nIn the same file you can also change the configuration values to be passed to the CommonMark converter environment.\nHyde handles many of the options automatically, but you may want to override some of them and\/or add your own.\n\n\/\/ filepath: config\/markdown.php\n'config' => [\n 'disallowedrawhtml' => [\n 'disallowed_tags' => [],\n ],\n],\n\nSee the CommonMark Configuration Docs for the available options.\nAny custom options will be merged with the defaults.\n\n### Allow Raw HTML\n\nSince Hyde uses GitHub Flavored Markdown,\nsome HTML tags are stripped out by default. If you want to allow all arbitrary HTML tags, and understand the risks involved,\nyou can use the allow_html setting to enable all HTML tags.\n\n\/\/ filepath: config\/markdown.php\n'allow_html' => true,\n\n### Allow Blade Code\n\nHydePHP also allows you to use Blade code in your Markdown files. This is disabled by default, since it allows\narbitrary PHP code specified in Markdown to be executed. It's easy to enable however, using the enable_blade setting.\n\n\/\/ filepath: config\/markdown.php\n'enable_blade' => true,\n\nSee the Blade in Markdown documentation for more information on how to use this feature.\n\n## YAML Configuration\n\nThe settings in the config\/hyde.php file can also be set by using a hyde.yml file in the root of your project directory.\n\nNote that YAML settings cannot call any PHP functions, so you can't access helpers like env() for environment variables,\nnor declare authors or navigation links, as you cannot use facades and objects. But that doesn't stop you from using both\nfiles if you want to. Just keep in mind that any duplicate settings in the YAML file override any made in the PHP file.\n\nHere is an example showing some of the config\/hyde.php file settings, and how they would be set in the YAML file.\n\n# filepath hyde.yml\nname: HydePHP\nurl: \"http:\/\/localhost\"\npretty_urls: false\ngenerate_sitemap: true\nrss:\n enabled: true\n filename: feed.xml\n description: HydePHP RSS Feed\nlanguage: en\noutputdirectory: site\n\n### Namespaced YAML Configuration\n\nIf you are running v1.2 or higher, you can also use namespaced configuration options in the YAML file.\n\nThis allows you to set the settings of any configuration file normally found in the config directory.\n\nThis feature is automatically enabled when you have a hyde: entry first in your hyde.yml file\n\n# filepath hyde.yml\nhyde:\n name: HydePHP\n\ndocs:\n sidebar:\n header: \"My Docs\"\n\nThis would set the name setting in the config\/hyde.php file, and the sidebar.header setting in the config\/docs.php file.\n\nEach top level key in the YAML file is treated as a namespace, and the settings are set in the corresponding configuration file.\nYou can of course use arrays like normal even in namespaced configuration.","destination":"customization.html"},{"slug":"navigation","title":"Navigation Menus","content":"Navigation Menus\n\nIntroduction\n\nA great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation.\nHyde is designed to automatically configure these menus for you based on the content you have in your project.\n\nThere are two types of navigation menus in Hyde:\n\nPrimary Navigation Menu**: This is the main navigation menu that appears on most pages of your site.\nDocumentation Sidebar**: This is a sidebar that appears on documentation pages and contains links to other documentation pages.\n\nHydePHP automatically generates all of these menus for you based on the content of your project,\nand does its best to automatically configure them in the way that you most likely want them to be.\n\nOf course, this won't always be perfect, so thankfully Hyde makes it a breeze to customize these menus to your liking.\nKeep on reading to learn how! To learn even more about the sidebars, visit the Documentation Pages documentation.\n\nQuick primer on the internals\n\nIt may be beneficial to understand the internal workings of the navigation menus to take full advantage of the options.\n\nIn short, both navigation menu types extend the same class (meaning they share the same base code), this means that the way\nthey are configured are very similar, making the documentation here applicable to both types of menus.\n\nSee the Digging Deeper section of this page if you want the full scoop on the internals!\n\nWhat to customize?\n\nHere is a quick overview of what you might want to customize in your navigation menus:\n\n- Navigation menu item labels - the text that appears in the menu links\n- Navigation menu item priority - control the order in which the links appear\n- Navigation menu item visibility - control if pages may show up in the menus\n- Navigation menu item grouping - group pages together in dropdowns\n\nDigging deeper into the internals\n\nWhile not required to know, you may find it interesting to learn more about how the navigation is handled internally.\nThe best way to learn about this is to look at the source code, so here is a high-level overview with details on where to look in the source code.\n\nThe main navigation menu is the NavigationMenu class, and the documentation sidebar is the DocumentationSidebar class.\nBoth extend the same BaseNavigationMenu class:\n\nuse Hyde\\Framework\\Features\\Navigation\\NavigationMenu;\nuse Hyde\\Framework\\Features\\Navigation\\DocumentationSidebar;\nuse \\Hyde\\Framework\\Features\\Navigation\\BaseNavigationMenu;\n\nWithin the BaseNavigationMenu class, you will find the main logic for how the menus are generated,\nwhile the child implementations contain the extra logic tailored for their specific use cases.\n\nAll the navigation menus store the menu items in their $items array containing instances of the NavItem class.\n\nThe NavItem class is a simple class that contains the label and URL of the menu item and is used to represent each item in the menu.\nDropdowns are represented by DropdownNavItem instances, which extend the NavItem class and contain an array of additional NavItem instances.\n\nuse Hyde\\Framework\\Features\\Navigation\\NavItem;\nuse Hyde\\Framework\\Features\\Navigation\\DropdownNavItem;","destination":"navigation.html"},{"slug":"troubleshooting","title":"Troubleshooting","content":"# Troubleshooting\n\nSince Hyde has a lot of \"magic\" features which depend on some base assumptions,\nthere might be some \"gotchas\" you might run into. Here are some I can think of,\ndid you find a new one? Send a PR to update the docs!\n\ninfo Tip: You can run php hyde validate to run a series of tests to help you catch common issues.\n\n## General Tips\n\n(In no particular order of importance)\n\n1. In general, Hyde is actually pretty forgiving. While this article makes it sound like there are a lot of rules to follow,\n honestly don't worry about it. Hyde will attempt to fix mistakes and make your life easier.\n2. You don't need to set an H1 heading in blog posts. The H1 is set by Hyde based on the front matter title.\n3. You never need front matter, though it is often useful.\n For example, Hyde makes attempts to guess the title for a page depending on the content. (Headings, filenames, etc).\n\n## Conventions to follow\n\n### File naming\n\nFor Hyde to be able to discover your files, you should follow the following conventions.\n\nMarkdown files should have the extension .md. Blade files should have the extension .blade.php.\n\nUnexpected behaviour might occur if you use conflicting file names.\nAll the following filenames are resolved into the same destination file:\nfoo-bar.md, Foo-Bar.md, foo-bar.blade.php, causing only one of them to be saved.\n\nRemember, files retain their base filenames when compiled to HTML.\n\n#### Summary\n\n- \u2714 Do use lowercase filenames and extensions\n- \u2714 Do use filenames written in kebab-case-format\n- \u2714 Do use the proper file extensions\n- \u274c Don't use conflicting source file names\n\n## Extra Information\n\n### Definitions\n\nWe will use the following definitions to describe the behaviour of Hyde.\n\n#### General\n\nHyde**: The application that you are using.\nHydeCLI**: The command-line interface for Hyde.\nFramework**: The package containing the core codebase.\n\n#### Path components\n\nIdentifier**: The filepath without the extension, relative to the page type source directory.\nRoute Key**: The page type's output directory plus the identifier. Example: posts\/hello-world\nBasename**: The filename without the extension. Example: hello-world\nFilename**: The full name of a file with the extension. Example: hello-world.md\nFilepath**: The full file path including extension. Example: _posts\/hello-world.md\n\nYou can read more about some of these in the Core Concepts article.\n\n## Common issues, causes, and solutions\n\nIssue Possible Cause \/ Issue Context Possible Solution\n\n404 error when visiting site Are you missing an index file in the pages directory? Add an index.md or index.blade.php to the pages directory\nNavigation menu not linking to the docs You probably don't have an index.md file in the docs directory. Create a docs\/index.md file\nPage not discovered when compiling The file name may be invalid Ensure you follow the correct file naming convention.\nPage compiles slowly The Torchlight extension may cause the compile times to increase as API calls need to be made. Try disabling Torchlight\nTorchlight not working Missing Composer package, missing API token, extension disabled in the config. Reinstall Torchlight, add your token in the .env file, check config\nMissing styles and\/or assets You may have accidentally deleted the files, or you have added new Tailwind classes. Run npm run dev\nImage not found You may be using a bad relative path. Ensure your relative paths are correct. See managing-assets.\nWrong layout used Hyde determines the layout template to use depending on the directory of the source file Ensure your source file is in the right directory.\nInvalid\/no permalinks or post URIs You may be missing or have an invalid site URL Set the site URL in the .env file\nNo styles in custom Blade pages When using custom blade pages need to add the styles yourself. You can do this by extending the default layout Use the app layout, or by include the Blade components directly.\nOverriding Hyde views is not working Ensure the Blade views are in the correct directory. Rerun php hyde publish:views.\nStyles not updating when deploying site It could be a caching issue. To be honest, when dealing with styles, it's always a caching issue. Clear your cache, and optionally complain to your site host\nDocumentation sidebar items are in the wrong order Double check the config, make sure the route keys are written correctly. Check that you are not overriding with front matter. Check config for typos and front matter\nDocumentation table of contents is weird The table of contents markup is generated by the League\/CommonMark extension Make sure that your Markdown headings make sense\nIssues with date in blog post front matter The date is parsed by the PHP strtotime() function. The date may be in an invalid format, or the front matter is invalid Ensure the date is in a format that strtotime() can parse. Wrap the front matter value in quotes.\nRSS 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.\nSitemap 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.\nUnable 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.\nNamespaced 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`\n\n### Extra troubleshooting information\n\n#### Fixing a broken config\n\nIf your configuration is broken, you might not be able to run any commands through the HydeCLI.\nTo remedy this you can copy the config files from the vendor directory into the project directory.\nYou can do this manually, or with the following rescue command:\n\ncopy vendor\/hyde\/framework\/config\/hyde.php config\/hyde.php","destination":"troubleshooting.html"},{"slug":"updating-hyde","title":"Updating Hyde Projects","content":"Updating Hyde Projects\n\nThis guide will help you update your HydePHP project to the latest version.\n\nBefore you start\n\nWhen updating an existing installation, first ensure that you have a backup of your project in case anything goes wrong.\nThe recommended way to do this is to use Git as that allows you to smoothly roll back any changes.\n\nVersion compatibility\n\nHydePHP follows semantic versioning, so you can expect that minor and patch releases will be backwards compatible.\nOnly major releases may introduce breaking changes, all of which are thoroughly documented in the accompanying release notes.\n\nNew features and bug fixes are added in minor and patch releases, so it is recommended to keep your project up to date.\n\nSide effects and ensuring a smooth update\n\nPlease note that due to the intricate nature of software, there is a possibility that an update contains side effects,\nhence why version controlling your site is helpful when updating versions as you can roll back changes. It can also\nbe helpful to version control the compiled HTML, so you can view a diff of the changes. Be sure to test that your site\ncan be built and that it looks as expected after updating before deploying the changes to your live site.\n\nWe of course have extensive tests in place run on each single code commit to ensure all code is functional, however,\nit is still possible that some edge cases slip through. This means that a bug fix may impact an edge case that you depend on.\n\nObligatory related XKCD: https:\/\/xkcd.com\/1172\n\nMethods\n\nWhich method?\n\nDepending on how you installed Hyde, there are a few different ways to update it.\n\nWe have a few methods documented here. The Git method is recommended as it is the easiest and safest way to\nupdate your project. If you are not using Git, you can still update your project using any of the manual methods.\n\nRegardless of the method you use, make sure you follow the post-update instructions at the end.\n\nUpdating just the Framework\n\nIf you just want to update the framework patch version, you can do so by running the following command:\n\ncomposer update hyde\/framework\n\nWhile the same can still be done for minor versions, it's best to also update your project scaffolding and resources to\nensure that everything is up to date, for which you should use the methods below.\n\nUsing Git\n\nFirst, make sure you have a remote set up for the base project repository.\n\ngit remote add upstream https:\/\/github.com\/hydephp\/hyde.git\n\nThen pull the latest release from the upstream repository.\n\ngit pull upstream master\n\nAfter this, you should update your composer dependencies:\n\ncomposer update\n\nNext, follow the post-update instructions.\n\nManual Update\n\nIf you are not using Git, you can still update your project. This is a bit more involved, but it is still possible.\n\n1. First, you will need to download the latest release archive from the releases page.\n2. Then extract the archive, and copy the contents into your project directory.\n\nSince this may overwrite modified files, it may be safer to use the hard update method.\n\nHard Update\n\nIf you are having trouble updating your project, you can try a hard update. In short, this approach consists of creating\na brand new project and copying over only your source and resource files. If you do not want to use Git, this may be\nthe safest option as you won't be overriding any of your existing files.\n\nIf you have changed any other files, for example in the App directory, you will need to update those files manually as well.\nThe same goes if you have created any custom Blade components or have modified Hyde ones.\n\nHere is an example CLI workflow, but you can do the same using a graphical file manager.\n\nmv my-project my-project-old\ncomposer create-project hyde\/hyde my-project\n\ncp -r my-old-project\/pages my-project\/content\/pages\ncp -r my-old-project\/posts my-project\/content\/posts\ncp -r my-old-project\/media my-project\/content\/media\ncp -r my-old-project\/docs my-project\/content\/docs\ncp -r my-old-project\/config my-project\/config\n\nNext, follow the post-update instructions. After verifying that everything is working, you can delete the old project directory.\n\nPost-update instructions\n\nAfter updating Hyde you should update your config and resource files. This is where things can get a tiny bit dangerous\nas existing files may be overwritten. If you are using Git, you can easily take care of any merge conflicts that arise.\n\nFirst, ensure that your dependencies are up to date. If you have already done this, you can skip this step.\n\ncomposer update\n\nThen, update your config files. This is the hardest part, as you may need to manually copy in your own changes.\n\nphp hyde publish:configs\n\nIf you have published any of the included Blade components you will need to re-publish them.\n\nphp hyde publish:views layouts\nphp hyde publish:views components\n\nNext, recompile your assets, if you are not using the built-in assets.\n\nnpm install\nnpm run dev\/prod\n\nFinally, you can rebuild your site.\n\nphp hyde build\n\nNow, you should browse your site files to ensure things are still looking as expected.","destination":"updating-hyde.html"},{"slug":"extensions","title":"Extensions & Integrations","content":"Extensions & Integrations\n\nHydePHP - Extensible by design\n\nHydePHP is designed to be extensible, and comes with a number of built-in extensions and integrations,\nas well as support for third-party extensions and integrations.\n\nFirst party extensions & integrations\n\nRealtime Compiler\n\nThe Hyde Realtime Compiler is included with Hyde installations and is what powers the php hyde serve command.\n- Learn more about the Realtime Compiler in the documentation.\n\nUI Kit\n\nThe HydePHP UI Kit is a set of minimalistic Blade & Tailwind components to kickstart development of custom Blade views for your HydePHP site.\n- Learn more at https:\/\/github.com\/hydephp\/ui-kit and see the documentation at https:\/\/hydephp.github.io\/ui-kit\n\nGitHub Action\n\nThe GitHub Action for HydePHP is hands-down the easiest way to build and deploy your Hyde site to GitHub Pages.\n- Learn more at https:\/\/github.com\/hydephp\/action and see the documentation at https:\/\/hydephp.github.io\/action\n\nIntegrations with third-party tools\n\nTorchlight\n\nTorchlight is an amazing API for syntax highlighting, and is supported natively by HydePHP.\n- Learn more about Torchlight in the documentation.\n\nContribute\n\nHave an idea for an extension or integration? Let me know! I'd love to hear from you. Get in touch on\nGitHub or send me a DM on Twitter.\nYou may also want to look at the Extension API documentation to learn how to create extensions.","destination":"extensions.html"},{"slug":"realtime-compiler","title":"Realtime Compiler","content":"Realtime Compiler\n\nThe Hyde Realtime Compiler is included with Hyde installations and is what powers the php hyde serve command,\nallowing you to preview your static site on a local development server without having to rebuild the site.\n\nUsage\n\nTo start the server, run the following command from a terminal in your project directory:\n\nphp hyde serve\n\nThis will start a local development server at http:\/\/localhost:8080\n\nwarning Please note that the server is designed for local development, and should not be used on a public network.\n\nConfiguration\n\nThe server can be configured in the config\/hyde.php file to change the port, host, and to customize its features.\n\n\/\/ filepath config\/hyde.php\n\n'server' => [\n 'port' => env('SERVER_PORT', 8080),\n 'host' => env('SERVER_HOST', 'localhost'),\n 'save_preview' => true,\n],\n\nLive dashboard\n\nUsage\n\nThe realtime compiler comes with a live dashboard that you can access at http:\/\/localhost:8080\/dashboard.\n\nFrom here, you can visually interact with your site content, including creating new pages and posts.\n\nThe live dashboard is not saved to your static site, and is only available through the development server.\n\nConfiguration\n\nThe dashboard can be customized, and disabled, in the config\/hyde.php file.\n\n\/\/ filepath config\/hyde.php\n\n'server' => [\n 'dashboard' => [\n 'enabled' => env('SERVER_DASHBOARD', true),\n 'interactive' => true,\n 'tips' => true,\n ],\n],\n\nThe dashboard was added in Realtime Compiler v3.0.0 (March 2023), with interactive features added in v3.1.0 (October 2023)\n\nLive edit\n\nUsage\n\nThe live edit feature allows you to quickly edit Markdown-based pages (posts, docs, and pages) directly in the browser.\n\nTo enter the live editor, simply double-click on the article you want to edit, and it will be replaced with a text editor.\nWhen you're done, click the save button to save the changes to the page's source file.\n\nShortcuts\n\nThe live editor supports the following keyboard shortcuts:\n- Ctrl + E - Enter\/Exit editor\n- Ctrl + S - Save changes\n- esc - Exit editor if active\n\nConfiguration\n\nThe live editor can be disabled in the config\/hyde.php file.\nThe live editor plugin code will not be saved to your static site.\n\n\/\/ filepath config\/hyde.php\n\n'server' => [\n 'liveedit' => env('SERVERLIVE_EDIT', true),\n],\n\nThe live editor was added in Hyde Realtime Compiler Server v3.2.0 (December 2023)\n\nSource code\n\nGitHub**: hydephp\/realtime-compiler\nPackagist**: hydephp\/realtime-compiler","destination":"realtime-compiler.html"},{"slug":"third-party-integrations","title":"Integrations with third-party tools","content":"Integrations with third-party tools\n\nTorchlight\n\nTorchlight is an amazing API for syntax highlighting, and is used by this site. I cannot recommend it highly enough,\nespecially for documentation sites and code-heavy blogs! As such, HydePHP has built-in support for Torchlight,\nwhich is automatically enabled once you add an API token to your .env file. Nothing else needs to be done!\n\nGetting started\n\nTo get started you need an API token which you can get at Torchlight.dev.\nIt is entirely free for personal and open source projects, as seen on their pricing page.\n\nWhen you have an API token, set it in the .env file in the root directory of your project.\nOnce a token is set, Hyde will automatically enable the CommonMark extension.\n\nTORCHLIGHTTOKEN=torch\n\nAttribution and configuration\n\nNote that for the free plan you need to provide an attribution link. Thankfully Hyde injects a customizable link\nautomatically to all pages that use Torchlight. You can of course disable and customize this in the config\/torchlight.php file.\n\n'attribution' => [\n 'enabled' => true,\n 'markdown' => 'Syntax highlighting by Torchlight.dev',\n],\n\nDon't have this file? Run php hyde vendor:publish to publish it.","destination":"third-party-integrations.html"},{"slug":"ui-kit","title":"HydePHP UI Kit - Documentation","content":"HydePHP UI Kit - Documentation\n\nThe HydePHP UI Kit is a collection of minimalistic and un-opinionated TailwindCSS components for Laravel Blade,\nindented to be used with HydePHP. Note that these components may require CSS classes not present in the bundled app.css\nfile and that you may need to recompile the CSS file using the included Laravel Mix configuration.\n\nScreenshot\n\nHere are some of the components you can use to build your next project! As you can see, all components support both light and dark mode out of the box, just like the rest of HydePHP.\n\nComponents Screenshot\n\nComponents\n\nPlease make sure you're familiar with Laravel Blade before using the HydePHP UI Kit.\n\ninfo Tip: Most components allow you to pass any additional HTML attributes to the element!\n\nButtons\n\nPrimary\n\n Primary Button\n\nSecondary\n\n Secondary Button\n\nInput\n\nThe base component is ``, any additional attributes will be passed to the input element as seen below.\n\nCard\n\nAn incredibly versatile component that can be used for a wide variety of purposes.\n\nIn the most basic form, a card is just a container with a white background and a shadow.\nHowever, it also supports two slots: title and footer.\n\n A card with some content.\n\n \n Card Title\n \n\n \n Some footer content.\n \n\nWhy not combine the components?\n\n \n My Amazing Card\n \n\n A card with some content and a footer with a button.\n\n \n \n Primary Button\n \n \n\nTypography Components\n\nHeading\n\nThis component will create a styled `` level heading centred on the page.\n\n Lorem ipsum dolor sit amet.\n\nProse\n\nThis simple component will create an `` element with TailwindCSS Typography (prose) styles applied.\n\n Prose Heading\n Prose paragraph\n\nMarkdown\n\nThis component will convert any Markdown within it to HTML using the Hyde Markdown compiler.\n\nMarkdown Heading\n\n Hello world!\n\ninfo Tip: You may also want to wrap this in the prose element or the Markdown will not be styled.\n\nWhat's Next?\n\nThe UI kit is minimal by design. It's up to you to create something amazing, we just want to give you a head start.\nYou can get surprisingly far when you combine the components. Take this newsletter signup card for example!\n\n \n Let your creativity flow!\n \n\n \n \n \n The UI kit is minimal by design. It's up to you to create something amazing.\n\n Maybe create a form to collect newsletter subscriptions?\n \n \n \n\n \n \n\n \n Subscribe\n \n \n\nNewsletter Screenshot\n\nGitHub Repository\n\nYou can find the source code for the UI Kit on GitHub at hydephp\/ui-kit.","destination":"ui-kit.html"},{"slug":"console-commands","title":"Console Commands","content":"# Console Commands\n\nThe primary way of interacting with Hyde is through the command line using the HydeCLI.\n\nIf you have ever used the Artisan Console in Laravel you will feel right at home,\nthe HydeCLI is based on Artisan after all!\n\n## Introduction\n\nTo use the HydeCLI, run php hyde from your project directory followed by a command.\n\nAll HydeCLI commands start with php hyde. Anything in [brackets] is optional.\nIf an argument or option value has a space in it, it needs to be wrapped in quotes.\n\nThe HydeCLI exists at the root of your application as the hyde script and provides a number of helpful commands that can\nassist you while you build your site. To view a list of all available Hyde commands, you may use the list command:\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde list\n\n### Got stuck? The CLI can help.\n\nEvery command also includes a \"help\" screen which displays and describes the command's available arguments and options.\nTo view a help screen, precede the name of the command with help:\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde help \n\nYou can also always add --help to a command to show detailed usage information.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde --help\n\n## Available Commands\n\nHere is a quick reference of all the available commands. You can also run php hyde list to see this list.\n\nCommand Description\n\nbuild Build the static site\nserve Start the realtime compiler server\nrebuild Run the static site builder for a single file\nbuild:rss Generate the RSS feed\nbuild:search Generate the docs\/search.json file\nbuild:sitemap Generate the sitemap.xml file\nmake:page Scaffold a new Markdown, Blade, or documentation page file\nmake:post Scaffold a new Markdown blog post file\npublish:configs Publish the default configuration files\npublish:homepage Publish one of the default homepages as index.blade.php\npublish:views Publish the hyde components for customization. Note that existing files will be overwritten\nvendor:publish Publish any publishable assets from vendor packages\nroute:list Display all registered routes\nvalidate Run a series of tests to validate your setup and help you optimize your site\nlist List all available commands\n\n## Build the static site\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build [--run-dev] [--run-prod] [--run-prettier] [--pretty-urls] [--no-api]\n\nBuild the static site\n\n#### Options\n\n\n\n--run-dev Run the NPM dev script after build\n--run-prod Run the NPM prod script after build\n--run-prettier Format the output using NPM Prettier\n--pretty-urls Should links in output use pretty URLs?\n--no-api Disable API calls, for example, Torchlight\n\n## Run the static site builder for a single file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde rebuild \n\nRun the static site builder for a single file\n\n#### Arguments\n\n\n\npath The relative file path (example: \\_posts\/hello-world.md) \\n - Is required: yes\n\n## Start the realtime compiler server\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde serve [--host [HOST]] [--port [PORT]]\n\nStart the realtime compiler server.\n\n#### Options\n\n\n\n--host= [default: \"localhost\"]\n--port= [default: 8080]\n\n## Test and validate your project to optimize your site\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde validate\n\nRun a series of tests to validate your setup and help you optimize your site.\n\n## Generate the RSS feed\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build:rss\n\nGenerate the RSS feed\n\n## Generate the docs\/search.json file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build:search\n\nGenerate the docs\/search.json file\n\n## Generate the sitemap.xml file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde build:sitemap\n\nGenerate the sitemap.xml file\n\n## Scaffold a new Markdown, Blade, or documentation page file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde make:page [--type [TYPE]] [--blade] [--docs] [--force] [--] []\n\nScaffold a new Markdown, Blade, or documentation page file\n\n#### Arguments & Options\n\n\n\ntitle The name of the page file to create. Will be used to generate the filename\n--type=markdown The type of page to create (markdown, blade, or docs)\n--blade Create a Blade page\n--docs Create a Documentation page\n--force Overwrite any existing files\n\n## Scaffold a new Markdown blog post file\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde make:post [--force] [--] []\n\nScaffold a new Markdown blog post file\n\n#### Arguments & Options\n\n\n\ntitle The title for the Post. Will also be used to generate the filename\n--force Should the generated file overwrite existing posts with the same filename?\n\n## Publish the default configuration files\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde publish:configs\n\nPublish the default configuration files\n\n## Publish one of the default homepages as index.blade.php.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde publish:homepage [--force] [--] []\n\nPublish one of the default homepages as index.blade.php.\n\n#### Arguments & Options\n\n\n\nhomepage The name of the page to publish\n--force Overwrite any existing files\n\n## Publish the hyde components for customization\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde publish:views []\n\nPublish the hyde components for customization. Note that existing files will be overwritten.\n\n#### Arguments\n\n\n\ncategory The category to publish\n\n## Display all registered routes.\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde route:list\n\nDisplay all registered routes.\n\n## Publish any publishable assets from vendor packages\n\n\/\/ torchlight! {\"lineNumbers\": false}\nphp hyde vendor:publish [--existing] [--force] [--all] [--provider [PROVIDER]] [--tag [TAG]]\n\nPublish any publishable assets from vendor packages\n\n#### Options\n\n\n\n--existing Publish and overwrite only the files that have already been published\n--force Overwrite any existing files\n--all Publish assets for all service providers without prompt\n--provider= The service provider that has assets you want to publish\n--tag= One or many tags that have assets you want to publish \\n- Is multiple: yes","destination":"console-commands.html"},{"slug":"core-concepts","title":"Core HydePHP Concepts","content":"Core HydePHP Concepts\n\nIntroduction to the Hyde Framework\n\nWhat makes HydePHP special are its \"magic\" features like autodiscovery and intelligent data generation.\nAll designed so that you can focus on your content, while the framework does the heavy lifting.\n\nThis page provides a high-level overview of the framework's capabilities, so you can quickly grasp its benefits.\nAs you delve deeper into the documentation, you'll discover the details of each feature and learn how to leverage them effectively.\n\nThe HydeCLI\n\nWhen you are not writing Markdown and Blade, most of your interactions with Hyde will be through the command line\nusing the HydeCLI, which is based on the Laravel Artisan Console that you may already be familiar with.\n\nIf you want to learn about the available commands and how to use them, you can visit the Console Commands page,\nor you can run any of the built-in help commands to get a list of available commands and their descriptions.\n\nphp hyde list\nphp hyde help \nphp hyde [--help]\n\nDirectory structure\n\nTo take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure.\n\nDirectory Purpose\n\n_docs For documentation pages\n_posts For blog posts\n_pages For static Markdown and Blade pages\n_media Store static assets to be copied to the build directory\n_site The build directory where your compiled site will be stored\nconfig Configuration files for Hyde and integrations\nresources\/assets Location for Laravel Mix source files (optional)\nresources\/views Location for Blade components (optional)\napp Location for custom PHP classes (optional)\n\nPage Models\n\nThe Hyde page models are an integral part of how HydePHP creates your static site. Each page in your site is represented\nby a page model. These are simply PHP classes that in addition to holding both the source content and computed data\nfor your pages, also house instructions to Hyde on how to parse, process, and render the pages to static HTML.\n\nThe page classes are very important and fill two roles:\n\n1. They act as blueprints containing static instructions for how to parse, process, and, render pages.\n2. Each class instance also holds the page source contents, as well as the computed data.\n\nTo learn more, you can visit the Page Models page.\n\nFile Autodiscovery\n\nContent files, meaning source Markdown and Blade files, are automatically discovered by Hyde and compiled to HTML when\nbuilding the site. This means that you don't need to worry about routing and controllers!\n\nThe directory a source file is in will determine the Blade template that is used to render it.\n\nAll source and output directories are configurable, but the defaults are as follows:\n\nPage\/File Type Source Directory Output Directory File Extensions\n\nStatic Pages pages\/ site\/ .md, .blade.php\nBlog Posts posts\/ site\/posts\/ .md\nDocumentation docs\/ site\/docs\/ .md\nMedia Assets media\/ site\/media\/ Common asset types\n\nPaths, Identifiers, and Route Keys\n\nSince HydePHP automatically discovers and compiles content files, it is important to understand how HydePHP handles paths,\nas the file names and directories they are in will directly influence how the page will be compiled.\n\nAs such, it will be helpful for you to know about the following terms:\n\nPath:** The full path to a file, including the file name, directory, and extension.\nIdentifier:** The unique identifier for a page. Unique only within the same page type.\nRoute key:** The key used to access the page in the routing system. Unique across all site pages.\n\nBoth the identifier and route key are derived from the path of the page. The identifier is the path without the file\nextension, and relative to the page type source directory. The route key is the output directory plus the identifier.\n\nThe identifier generation can be visualized as follows, where the identifier is underlined:\n\n _pages\/about\/contact.md\n\nFor a Markdown page, like the example above, the route key would be the same as the identifier, since Markdown pages are\noutput to the site root. If it was a Markdown post however, the route key would be: posts\/about\/contact.\n\nThis can be visualized as follows, assuming a blog post is stored as _posts\/hello-world.md:\n\n _site\/posts\/hello-world.html\n\nAs you can see, the route key is simply put the relative page URL, without the .html extension.\n\nConvention over Configuration\n\nHyde favours the \"Convention over Configuration\" paradigm and thus comes preconfigured with sensible defaults.\nHowever, Hyde also strives to be modular and endlessly customizable hackable if you need it.\nTake a look at the customization and configuration guide to see the endless options available!\n\nFront Matter\n\ninfo In a nutshell: Front Matter is a block of YAML containing metadata, stored at the top of a Markdown file.\n\nFront matter is heavily used in HydePHP to store metadata about pages. Hyde uses the front matter data to generate rich and dynamic content. For example, a blog post category, author website, or featured image.\n\nUsing front matter is optional, as Hyde will dynamically generate data based on the content itself. (Though any matter you provide will take precedence over the automatically generated data.)\n\nTo learn more, you can visit the Front Matter page.\n\nFront Matter in Markdown\n\nAll Markdown content files support Front Matter, and blog posts make heavy use of it. Here's what it may look like:\n\ntitle: \"My New Post\"\nauthor: \"Mr Hyde\"\ndate: \"2023-03-14\"\nMarkdown comes here\n\nLorem ipsum dolor sit amet, etc.\n\nFront Matter in Blade\n\nHydePHP has experimental support for creating front-matter in Blade templates, called BladeMatter,\nwhere code in @php directives are statically parsed into page object's front matter data where it can be accessed in your templates.\n\n@php($title = 'BladeMatter Demo') \/\/ Equivalent to title: 'BladeMatter Demo' in Yaml\n\nAutomatic Routing\n\ninfo In a nutshell: Hyde will automatically create routes for your source files.\n\nIf you've ever worked in an MVC framework, you are probably familiar with the concept of routing.\nAnd you are probably also familiar with how boring and tedious it can be. Thankfully, Hyde takes the pain out of routing by doing it for you!\n\nDuring the Autodiscovery process. Hyde will automatically discover all the content files in the source directories,\nand create routes for all of them, and store them in an index which works as a two-way link between source files and compiled files.\n\nYou can see all the routes and their corresponding source files by running the hyde route:list command.\n\nphp hyde route:list\n\nTo access routes in your code, simply use the Routes facade and specify the route key for the desired page.\n\nRoutes::get('posts\/my-post')\n\nTo learn more about the routing system, please visit the routing documentation.\n\nGlobal Page Data\n\nDuring the build of each page, Hyde will inject some data available to all Blade views. If you are not planning to write\nany custom Blade templates, you can safely ignore this section. If you are, here are the three global variables you can use:\n\n- $page: The Page Object for the current page.\n- $route: The Route Object for the current page.\n- $routeKey: The Route Key for the current page.\n\nThe $page variable is likely to the most important one, as it contains all the data for the current page.\nDepending on the page type, you will have different helpers available. But $page->matter() is likely to be very helpful.\n\nYou can see all the helpers in the Page API reference page.\n\nTerminology\n\nIn this quick reference, we'll briefly go over some terminology and concepts used in HydePHP.\nThis will help you understand the documentation and codebase better, as well as helping you know what to search for when you need help.\n\nTable of contents\n\nTools\n\n- HydePHP\n- Laravel\n- Composer\n- Tailwind CSS\n\nLanguages\n\n- Front Matter\n- Markdown\n- Blade\n- YAML\n- PHP\n- HTML\n\nGeneral Concepts\n\n- Static Sites\n- Version Control\n- Git\n\nHydePHP Features\n\n- Autodiscovery\n- Page Types\n- Page Identifiers\n- Routes\n- Route Keys\n\n[\/\/]: # (Languages and Tools)\n\nHydePHP\n\nHydePHP is a static site generator written in PHP, designed to make it easy for developers to build fast and secure websites.\nIt uses a simple directory structure and templating system to generate static websites from content files,\nand can be easily extended using PHP libraries and packages.\n\nLaravel\n\nLaravel is the PHP framework that HydePHP is built on top of. We use a specialized version called Laravel Zero,\nwhich is optimized for command-line applications.\n\nFront Matter\n\nFront Matter is a block of YAML, stored at the top of a Markdown file, enclosed by a set of triple-dashed lines.\nIt is commonly used to store metadata about the content, such as the title, author, date, etc.\n\nMarkdown\n\nMarkdown is a lightweight markup language that uses plain text formatting syntax, designed to make it easy to create\nstructured content for the web. HydePHP uses Markdown as the base for most of its content files.\n\nBlade\n\nBlade is the templating engine from Laravel, which allows developers to write clean and reusable code for the\npresentation layer of web applications. HydePHP uses Blade both for the built-in views and components,\nas well as to provide powerful templating capabilities through Blade-based pages.\n\nYAML\n\nYAML is a human-readable data serialization format used for configuration files and often used as the syntax for\nFront Matter in HydePHP content files. YAML is designed to be easily read by humans and parsed by machines,\nmaking it a popular choice for many applications and frameworks.\n\nPHP\n\nPHP is a popular server-side scripting language used for web development that can be embedded in HTML.\nHydePHP is built on top of PHP and utilizes its powerful capabilities for generating static websites.\n\nHTML\n\nHTML (Hypertext Markup Language) is the standard markup language used to create web pages and web applications.\nHydePHP uses HTML to render the static websites generated from its content files and templates.\n\nTailwind CSS\n\nTailwind CSS is a utility-first CSS framework used for rapidly building custom user interfaces.\nHydePHP supports Tailwind CSS out of the box through the built-in Blade templates,\nmaking it easy for developers to create beautiful and responsive websites without writing custom CSS.\n\nComposer\n\nComposer is a dependency manager for PHP that simplifies the process of installing and managing packages required by\nPHP applications. HydePHP uses Composer to manage its own dependencies and make it easy for users to install and use the software.\n\nStatic Sites\n\nA static website is a collection of HTML web pages that are delivered to the user's web browser exactly as they are stored\non the web server. HydePHP generates static websites, making them fast, secure, and easy to deploy.\n\nVersion Control\n\nHydePHP can be easily integrated with Git to manage website source files and track changes over time,\nas one of the many benefits with static sites is that they are designed to be version controlled.\n\nGit\n\nGit is a free and open-source distributed version control system that is widely used for software development.\nGit repositories can be hosted on GitHub, GitLab, BitBucket, or any other Git hosting service.\n\n[\/\/]: # (HydePHP Features)\n\nAutodiscovery\n\nContent files, including Markdown and Blade files, are automatically discovered and compiled to HTML during site builds.\nDuring autodiscovery, Hyde also generates dynamic data to enrich your content based on the page type.\n\nIn short the autodiscovery is split into three steps:\nFile discovery -> Page parsing -> Route generation\n\nPage Types\n\nAll pages in HydePHP are internally represented by a page object that extends the HydePage class. Each page type has its\nown page class which acts as a blueprint defining information for the framework to parse a file and generate relevant data.\n\nPage Identifiers\n\nThe page identifier is the name of the file without the file extension, relative to the page type's source directory.\nThe identifier is used to generate the route key, which is used to generate the file name for the compiled HTML file.\n\nRoutes\n\nAll pages are internally bound to a Route object, through the route key. During the build process, each route is\ncompiled to HTML using the page object's data, and saved to the output directory with a file name created from the route key.\nSince routes are generated automatically during autodiscovery, there is no need to create them manually.\n\nRoute Keys\n\nThe route key is the URL path relative to the site webroot, without the file extension. The route key is the common\nidentifier binding Page objects to Route objects, and is used to generate the file name for the compiled HTML file.\n\nRoute keys generation can be visualised as follows: \/","destination":"core-concepts.html"},{"slug":"front-matter","title":"Front Matter","content":"Front Matter\n\ninfo In a nutshell: Front Matter is a block of YAML containing metadata, stored at the top of a Markdown file.\n\nFront matter is heavily used in HydePHP to store metadata about pages. Hyde uses the front matter data to generate rich and dynamic content.\nFor example, in a blog post you may define a category, author website, or featured image. In a documentation page you may define the sidebar priority or label.\n\nUsing front matter is optional, as Hyde will dynamically generate data based on the content itself. (Though any matter you provide will take precedence over the automatically generated data.)\nWhile Hyde offers some support for front matter within Blade files, most of the time you use front matter, it will be in Markdown.\n\nFront matter syntax\n\nHere's a refresher on Yaml, and a quick reference of the syntax Hyde uses and expects:\n\nkey: value\nstring: \"quoted string\"\nboolean: true\ninteger: 100\narray:\n key: value\n key: value\n\nStrings don't need to be quoted, but it can help in certain edge cases, thus they are included here.\n\nFront Matter in Markdown\n\nAll Markdown content files support Front Matter. Blog posts for example make heavy use of it.\n\nThe specific usage and schemas used for pages are documented in their respective documentation, however, here is a primer on the fundamentals.\n\n- Front matter is stored in a block of YAML that starts and ends with a --- line.\n- The front matter should be the very first thing in the Markdown file.\n- Each key-pair value should be on its own line.\n\nTo use Front Matter, add Yaml to the top of your Markdown file:\n\ntitle: \"My New Post\"\nauthor:\n name: \"John Doe\"\n website: https:\/\/example.com\nMarkdown comes here\n\nLorem ipsum dolor sit amet, etc.\n\nFront Matter in Blade\n\nHydePHP has experimental support for creating front-matter in Blade templates, called BladeMatter.\n\nThe actual syntax does not use YAML; but instead PHP. However, the parsed end result is the same. Please note that\nBladeMatter currently does not support multidimensional arrays or multi-line directives as the data is statically parsed.\n\nTo create BladeMatter, you simply use the default Laravel Blade @php directive to declare a variable in the template.\n\n@php($title = 'BladeMatter Demo')\n\nIt will then be available through the global $page variable, $page->matter('title').\nHyde will of course also use the data for contextual autoconfiguration in the same way it would with Markdown and use the value as the page title.\n\nAnother idea is to use @php($navigation = ['hidden' => true]) if you want to hide a page from the navigation. The opportunities are limitless!","destination":"front-matter.html"},{"slug":"quickstart","title":"Quickstart Guide","content":"Quickstart Guide\n\nInstalling HydePHP using Composer\n\nThe recommended method of installing Hyde is using Composer, which installs the required dependencies on a per-project basis.\n\n\/\/ torchlight! {\"lineNumbers\": false}\ncomposer create-project hyde\/hyde\n\nRequirements\n\nHyde is based on Laravel 10\nwhich requires a minimum PHP version of 8.1.\nYou should also have Composer installed.\n\nTo use some features like compiling your own assets\nyou also need NodeJS and NPM.\n\nUsing the Hyde CLI\n\nThe main way to interact with Hyde is through the HydeCLI, a Laravel Artisan-based command-line interface. Learn more about the HydeCLI in the console commands documentation.\n\nStarting a development server\n\nTo make previewing your site a breeze you can use the realtime compiler, which builds your pages on the fly.\n\nphp hyde serve\nSimply run the serve command, and you will be able to preview your site at http:\/\/localhost:8080.\n\nCreating content\n\nDirectory structure\n\nCreating content with Hyde is easy! Simply place source files in one of the source directories,\nand Hyde will automatically discover, parse, and compile them to static HTML.\nThe directory and file extension of a source file will determine how HydePHP parses and compiles it.\nPlease see the directory structure section for more information.\n\nScaffolding files\n\nYou can scaffold blog post files using the php hyde make:post command which automatically creates the front matter, based on your input selections.\nYou can also scaffold pages with the php hyde make:page command.\n\nphp hyde make:post\nphp hyde make:page\n\nCompiling to static HTML\n\nNow that you have some amazing content, you'll want to compile your site into static HTML. Thankfully, this is as easy as executing the build command, after which your compiled site is stored in the _site directory.\n\nphp hyde build\n\nWhen building the site, Hyde will scan your source directories for files and compile them into static HTML using the appropriate layout depending\non what kind of page it is. You don't have to worry about routing as Hyde takes care of everything, including creating navigation menus!\n\nManaging assets\n\nHyde comes bundled with a precompiled and minified app.css file, containing all the Tailwind you need for the default views meaning that you don't even need to use NPM. However, Hyde is already configured to use Laravel Mix to compile your assets if you feel like there's a need to build the assets yourself. See more on the Managing Assets page.\n\nDeploying your site\n\nYou are now ready to show your site to the world! Simply copy the _site directory to your web server's document root, and you're ready to go.\n\nYou can even use GitHub Pages to host your site for free. That's what the Hyde website does, using an Actions CI workflow that automatically builds and deploys this site.\n\nFurther reading\n\nHere's some ideas of what to read next:\n\n- Architecture Concepts & Directory Structure\n- Console Commands with the HydeCLI\n- Creating Blog Posts","destination":"quickstart.html"},{"slug":"directory-structure","title":"Directory Structure","content":"Redirecting you to architecture-concepts#directory-structure","destination":"directory-structure.html"},{"slug":"getting-started","title":"Getting Started","content":"Redirecting you to quickstart","destination":"getting-started.html"},{"slug":"installation","title":"Installation","content":"Redirecting you to quickstart","destination":"installation.html"}] \ No newline at end of file diff --git a/pr-1540/dev-docs-preview/static-pages.html b/pr-1540/dev-docs-preview/static-pages.html index 64aecd2709d..9344288b8c8 100644 --- a/pr-1540/dev-docs-preview/static-pages.html +++ b/pr-1540/dev-docs-preview/static-pages.html @@ -212,7 +212,7 @@

      - Navigation + Navigation Menus

    • @@ -584,7 +584,7 @@

      Bonus: Creating HTML Pages

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/the-hydekernel.html b/pr-1540/dev-docs-preview/the-hydekernel.html index 235dd92c08b..db7b1712a93 100644 --- a/pr-1540/dev-docs-preview/the-hydekernel.html +++ b/pr-1540/dev-docs-preview/the-hydekernel.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -737,7 +737,7 @@

      booted()

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/third-party-integrations.html b/pr-1540/dev-docs-preview/third-party-integrations.html index ff1a7d0fce5..59fc8f5fee2 100644 --- a/pr-1540/dev-docs-preview/third-party-integrations.html +++ b/pr-1540/dev-docs-preview/third-party-integrations.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -426,7 +426,7 @@

      Attribution and configuration

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/troubleshooting.html b/pr-1540/dev-docs-preview/troubleshooting.html index e320da593e7..73df3c2e4f7 100644 --- a/pr-1540/dev-docs-preview/troubleshooting.html +++ b/pr-1540/dev-docs-preview/troubleshooting.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -612,7 +612,7 @@

      Fixing a broken config

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/ui-kit.html b/pr-1540/dev-docs-preview/ui-kit.html index fec295f32df..a40fd7daa08 100644 --- a/pr-1540/dev-docs-preview/ui-kit.html +++ b/pr-1540/dev-docs-preview/ui-kit.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -552,7 +552,7 @@

      GitHub Repository

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR diff --git a/pr-1540/dev-docs-preview/updating-hyde.html b/pr-1540/dev-docs-preview/updating-hyde.html index 565753e1fdd..eaba5d54dff 100644 --- a/pr-1540/dev-docs-preview/updating-hyde.html +++ b/pr-1540/dev-docs-preview/updating-hyde.html @@ -156,7 +156,7 @@

      - Navigation + Navigation Menus

    • @@ -513,7 +513,7 @@

      Post-update instructions

      Documentation preview for  PR #1540   - (#08297506855aa842c8923f176863793331958060) + (#c0f748f1124e69a8e2115eaf7623ade037347cf0)

      Back to PR