From 903c3afb3939868bf5e6ad8a78e3d68f01c7d8a0 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 6 Nov 2023 16:29:45 +0100 Subject: [PATCH] Redirect master documentation to v1.x This documentation is technically for the v0.x branch, but people visiting these links now will probably look for the latest version. The master documentation is on the GitHub.io domain. Uses a meta redirect, and a canonical link to hopefully not break SEO results. Script used to do this, in case we need to make changes: ```php Redirecting... HTML; foreach ($files as $file) { $page = basename($file, '.html'); $content = str_replace('$page', $page, $template); file_put_contents($file, $content); } ``` --- docs/docs/master/README.html | 363 +---- docs/docs/master/advanced-customization.html | 538 +------- docs/docs/master/advanced-features.html | 385 +----- docs/docs/master/advanced-markdown.html | 535 +------- docs/docs/master/architecture-concepts.html | 384 +----- docs/docs/master/autodiscovery.html | 484 +------ docs/docs/master/automatic-routing.html | 421 +----- docs/docs/master/blog-posts.html | 600 +-------- docs/docs/master/build-tasks.html | 511 +------ docs/docs/master/collections.html | 601 +-------- docs/docs/master/compile-and-deploy.html | 451 +------ docs/docs/master/console-commands.html | 817 +---------- docs/docs/master/core-concepts.html | 809 +---------- docs/docs/master/customization.html | 785 +---------- docs/docs/master/directory-structure.html | 364 +---- docs/docs/master/documentation-pages.html | 734 +--------- docs/docs/master/dynamic-data-discovery.html | 454 +------ docs/docs/master/extensions.html | 432 +----- docs/docs/master/front-matter.html | 423 +----- docs/docs/master/getting-started.html | 364 +---- docs/docs/master/hyde-pages.html | 1271 +----------------- docs/docs/master/in-memory-pages.html | 410 +----- docs/docs/master/index.html | 402 +----- docs/docs/master/installation.html | 364 +---- docs/docs/master/managing-assets.html | 528 +------- docs/docs/master/page-models.html | 472 +------ docs/docs/master/quickstart.html | 457 +------ docs/docs/master/search.html | 375 +----- docs/docs/master/static-pages.html | 554 +------- docs/docs/master/the-hydekernel.html | 880 +----------- docs/docs/master/troubleshooting.html | 578 +------- docs/docs/master/updating-hyde.html | 454 +------ 32 files changed, 128 insertions(+), 17072 deletions(-) diff --git a/docs/docs/master/README.html b/docs/docs/master/README.html index 29da0bee..122441a2 100644 --- a/docs/docs/master/README.html +++ b/docs/docs/master/README.html @@ -1,363 +1,8 @@ - - -HydePHP Upcoming Documentation - Hyde Documentation - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Hyde Documentation

-
-
-

This is the source for the HydePHP Documentation. Updates here are automatically propagated to the HydePHP.com website.

-

This document is not propagated to the website. It is only for the GitHub development repository.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/advanced-customization.html b/docs/docs/master/advanced-customization.html index 74f666c5..4cb2a287 100644 --- a/docs/docs/master/advanced-customization.html +++ b/docs/docs/master/advanced-customization.html @@ -1,538 +1,8 @@ - - -HydePHP Upcoming Documentation - Advanced Customization - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Advanced Customization

-
-
-

Introduction

-

This page covers advanced usage and is intended for developers who know what they are doing. Documentation here will be -mainly example driven, as it is assumed you have somewhat of an understanding of what you are doing already.

-

Prerequisites for Customizing directories

-

Before customizing source and output directories it may be helpful to know how these settings are stored internally.

-

The following is a summary from the Page Models documentation:

-

Each page type is represented by a page model class. Each of those classes have static properties that store the source and output directories. -These properties are set when the HydeServiceProvider -is registered, at which point the provider will search for any overrides in the config file.

-

This means that there are two options to change the source and output directories:

-
    -
  1. -Recommended: You can change the values in the config file, to let the HydeServiceProvider handle it for you.
    2. -
  2. -Advanced/Overkill: You can also set the static properties directly in the page model classes if you prefer. -
      -
    • You'd probably want to do this in a service provider, as it must be done before the Kernel is booted.
      • -
    • You can use the RegistersFileLocations -trait to use the same registration logic as the HydeServiceProvider.
      • -
    -
    3. -
-

Customizing source directories

-

The directories you place your content in are important. The directory will be used to determine the proper page type and the templates used. -If you are not happy with defaults, you can change them. Note that these are relative to the source_root setting, -which is the root of your project by default.

-

Note that you need to take care of conflicts when changing the source directories. For example, if you store Markdown -posts in the same directory as documentation pages, Hyde will not know which page type to use.

-

In the config file

-
Filepath: config/hyde.php'source_directories' => [
-    HtmlPage::class => '_pages',
-    BladePage::class => '_pages',
-    MarkdownPage::class => '_pages',
-    MarkdownPost::class => '_posts',
-    DocumentationPage::class => '_docs',
-],
-
-

In a service provider

-
Filepath: app/AppServiceProvider.phpuse Hyde\Framework\Concerns\RegistersFileLocations;
-
-public function register(): void
-{
-    $this->registerSourceDirectories([
-        HtmlPage::class => '_pages',
-        BladePage::class => '_pages',
-        MarkdownPage::class => '_pages',
-        MarkdownPost::class => '_posts',
-        DocumentationPage::class => '_docs',
-    ]);
-}
-
-

Customizing output directories

-

Like source directories, the output directories are also important as they determine the output path for the compiled pages.

-

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.

-

Each option is relative to the site's output_directory setting. Setting a value to '' will output the page to the site root.

-

In the config file

-
Filepath: config/hyde.php'output_directories' => [
-    HtmlPage::class => '',
-    BladePage::class => '',
-    MarkdownPage::class => '',
-    MarkdownPost::class => 'posts',
-    DocumentationPage::class => 'docs',
-],
-
-

In a service provider

-
Filepath: app/AppServiceProvider.phpuse Hyde\Framework\Concerns\RegistersFileLocations;
-
-public function register(): void
-{
-    $this->registerOutputDirectories([
-        HtmlPage::class => '',
-        BladePage::class => '',
-        MarkdownPage::class => '',
-        MarkdownPost::class => 'posts',
-        DocumentationPage::class => 'docs',
-    ]);
-}
-
-

Route key impact

-

For example, changing the output directory of Markdown posts to blog instead of posts will change the route key base from posts to blog. -This means that a file stored as _posts/hello-world.md will have the route key blog/hello-world instead of posts/hello-world, -this may break your site's configuration, so you should always verify the impact to your site of such a change. -You can learn more about this in the route key documentation.

-

Custom source root

-

HydePHP will by default look for the source directories shown above in the root of your project. -If you're not happy with this, it's easy to change! For example, you might want everything in a 'src' subdirectory. -That's easy enough, just set the value of the source_root setting in config/hyde.php to 'src', or whatever you prefer!

-
Filepath: config/hyde.php'source_root' => '', // [TL! --]
-'source_root' => 'src', // [TL! ++]
-
-

Automatic change

-

You can even make this change automatically with the php hyde change:sourceDirectory command!

-
php hyde change:sourceDirectory <name>
-
-

When run, Hyde will update the source directory setting in the config file, then create the directory if it doesn't exist, -and move all source directories and their content into it.

-

Custom media directory

-

The media directory houses assets like images and stylesheets. The default directory is _media, and upon building the site, -Hyde will copy all files in this directory to _site/media (or whatever your configured output and media directories are).

-

You can change the path to this directory by setting the media_directory option in config/hyde.php.

-
Filepath: config/hyde.php'media_directory' => '_media',
-
-

Next steps

-
    -
  1. Note that you will likely need to manually update webpack.mix.js so Laravel Mix can compile the assets correctly.
    2. -
  2. You will of course also need to copy over any existing files from the old directory to the new one.
    3. -
-

Setting changes both source and output directories

-

Note that this change will affect both the source and output directories. For example, if you set the value to assets, -all files from assets will be copied to _site/assets. If the setting starts with an underscore, that will be removed -from the output directory, so files in _assets will be copied to _site/assets.

-

Custom output directory

-

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!

-

If you want to store your compiled website in a different directory than the default _site, you can change the path -using the following configuration option in config/hyde.php. The path is expected to be relative to your project root.

-
Filepath: config/hyde.php'output_directory' => '_site',
-
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/advanced-features.html b/docs/docs/master/advanced-features.html index 3c64c2ab..d69858fb 100644 --- a/docs/docs/master/advanced-features.html +++ b/docs/docs/master/advanced-features.html @@ -1,385 +1,8 @@ - - -HydePHP Upcoming Documentation - Advanced Features in HydePHP - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Advanced Features in HydePHP

-
-
-

Preface

-

HydePHP is a simple, yet powerful, static site generator. It is designed to be easy to use and easy to extend.

-

This section of the documentation will cover some of the more advanced (but optional) features of the framework.

-

Prerequisites

-

To fully understand the features described in these chapters, it may be beneficial to first skim through the -Architecture Concepts chapters, or at the very least, the Core Concepts page.

-

You are also expected to have a basic understanding of PHP, and object-oriented programming principles.

-

Having some familiarity with Laravel will also be beneficial, as HydePHP is built on top of the Laravel framework.

-

Table of Contents

- -
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/advanced-markdown.html b/docs/docs/master/advanced-markdown.html index b074acc0..a11fe1ca 100644 --- a/docs/docs/master/advanced-markdown.html +++ b/docs/docs/master/advanced-markdown.html @@ -1,535 +1,8 @@ - - -HydePHP Upcoming Documentation - Advanced Markdown - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Advanced Markdown

-
-
-

Introduction

-

Since 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!

-

Using Blade in Markdown

-

A special feature in Hyde, is that you can use Laravel Blade in Markdown files!

-

To use Blade in your Markdown files, simply use the Blade shortcode directive, followed by your desired Blade string.

-

Standard syntax

-
 [Blade]: {{ "Hello World!" }} // Will render: 'Hello World!'
-
-

Blade includes

-

Only single-line shortcode directives are supported. If you need to use multi-line Blade code, use an @include -directive to render a more complex Blade template. You can pass data to includes by specifying an array to the second argument.

-
 [Blade]: @include("hello-world")
- [Blade]: @include("hello", ["name" => "World"])
-
-

Enabling Blade-supported Markdown

-

The feature is disabled by default since it allows arbitrary PHP to run, which could be a security risk, depending on your setup. -However, if your Markdown is trusted, and you know it's safe, you can enable it in the config/markdown.php file.

-
Filepath: config/markdown.php'enable_blade' => true,
-
-

Limitations

-

All shortcodes must be the first word on a new line, and only single-line shortcodes are supported.

-

Coloured Blockquotes

-

The HydePHP Markdown converter also supports some extra directives and features. One of them being four different -coloured blockquotes. Simply append the desired colour after the initial > character.

-
‎> Normal Blockquote
-‎>info Info Blockquote
-‎>warning Warning Blockquote
-‎>danger Danger Blockquote
-‎>success Success Blockquote
-
-
-

Normal Blockquote

-
-

Info Blockquote

-

Warning Blockquote

-

Danger Blockquote

-

Success Blockquote

-

Customizations

-

You can easily customize these styles too by adding and editing the following in your resources/app.css file, and then recompiling your site styles. -The code examples here use the Tailwind @apply directives, but you could also use border-color: something; just as well.

-
Filepath: resources/app.css/* Markdown Features */
-
-.prose blockquote.info {
-    @apply border-blue-500;
-}
-
-.prose blockquote.success {
-    @apply border-green-500;
-}
-
-.prose blockquote.warning {
-    @apply border-amber-500;
-}
-
-.prose blockquote.danger {
-    @apply border-red-600;
-}
-
-

Markdown usage

-

The coloured blockquotes also support inline Markdown, just like normal blockquotes.

-
‎>info Formatting is **supported**!
-
-

Limitations

-

Note that these currently do not support multi-line blockquotes.

-

Code block filepaths

-

When browsing these documentation pages you may have noticed a label in the top right corner of code blocks specifying the file path. -These are also created by using a custom Hyde feature that turns code comments into automatic code blocks.

-

Usage

-

Simply add a code comment with the path in the first line of a fenced code block like so:

-
Filepath: _docs/advanced-markdown.md```php
-‎// Filepath: hello-world.php
-
-echo 'Hello World!';
-```
-
-

Which becomes:

-
Filepath: hello-world.phpecho 'Hello World!';
-
-

Alternative syntax

-

The syntax is rather forgiving, by design, and supports using both // and # for comments. -The colon is also optional, and the 'filepath' string is case-insensitive. So the following is also perfectly valid:

-
```js
-‎// filepath hello.js
-console.log('Hello World!');
-```
-
-

If you have a newline after the filepath, like in the first example, it will be removed so your code stays readable.

-

Advanced usage

-

If you have enabled HTML in Markdown by setting the allow_html option to true in your config/markdown.php file, -anything within the path label will be rendered as HTML. This means you can add links, or even images to the label.

-
Filepath: View file on Github```markdown
-‎// Filepath: <a href="https://github.com">View file on Github</a>
-```
-
-

Limitations

-

The filepaths are hidden on mobile devices using CSS to prevent them from overlapping with the code block.

-

Configuration

-

Full configuration reference

-

All Markdown-related configuration options are in the config/markdown.php file. -You can find the full reference on the Customization page.

-

Raw HTML Tags

-

To convert Markdown, HydePHP uses the GitHub Flavored Markdown extension, which strips out potentially unsafe HTML. -If you want to allow all arbitrary HTML tags, and understand the risks involved, you can enable all HTML tags by setting -the allow_html option to true in your config/markdown.php file.

-
Filepath: config/markdown.php'allow_html' => true,
-
-

This will add and configure the DisallowedRawHtml CommonMark extension so that no HTML tags are stripped out.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/architecture-concepts.html b/docs/docs/master/architecture-concepts.html index e6dccb9f..64350eb7 100644 --- a/docs/docs/master/architecture-concepts.html +++ b/docs/docs/master/architecture-concepts.html @@ -1,384 +1,8 @@ - - -HydePHP Upcoming Documentation - Advanced Architecture Concepts - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Advanced Architecture Concepts

-
-
-

Introduction

-

These chapters are written for power users and contributors. If you're just looking to get a site up and running, -you can safely skip this section. The documentation here will cover advanced topics under the presumption that -the reader has a basic to intermediate understanding of programming, as well as PHP, object-oriented design, -and to some extent Laravel, as the articles are heavily driven by code examples.

-

You are of course free to skip this entire section, as you don't need to know these things to use Hyde. -However, if you want to know the "magic" behind Hyde, or if you want to take advantage of these powerful tools, -then by all means, please read on! This is also a great place to start if you want to contribute to the source code.

-

For a high-level overview of these concepts, see the Basic Architecture Concepts page.

-

Behind the magic

-

Want to learn more about a particular feature? Click on the links below to visit the article.

- -
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/autodiscovery.html b/docs/docs/master/autodiscovery.html index e706fd9d..938a11e0 100644 --- a/docs/docs/master/autodiscovery.html +++ b/docs/docs/master/autodiscovery.html @@ -1,484 +1,8 @@ - - -HydePHP Upcoming Documentation - Autodiscovery - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Autodiscovery

-
-
-

Introduction

-

HydePHP aims to reduce the amount of configuration you need to do to get a site up and running. -To that end, Hyde uses a process called autodiscovery to automatically find and register your pages.

-

This article will go into detail about how autodiscovery works as well as the lifecycle of the HydeKernel.

-

The short version

-

Hyde will use the information in the page model classes to scan the source directories for matching files which are -parsed using instructions from the model's class, resulting in data used to construct objects that get stored in the HydeKernel.

-

Prerequisites

-

Before reading this article, you should be familiar with the following concepts:

- -

Booting pipeline

-

The autodiscovery is run when the HydeKernel boots. It does so in three distinct steps, which run in sequence as each -step depends on the previous one. Each discovery step runs in a FoundationCollection which both runs the actual -discovery process and stores the discovered data in memory.

-

The steps are as follows:

-
    -
  1. -Step one: The file collection discovers all the source files and stores them in memory
    2. -
  2. -Step two: The page collection parses all the source files into page model objects
    3. -
  3. -Step three: The route collection generates route objects for all the pages
    4. -
-

Interacting with the collections

-

Usually, you will interact with the collection data through intermediaries.

-
    -
  • For example, if you call MarkdownPost::get('my-post'), Hyde will retrieve that page from the page collection.
    • -
  • If you call Routes::get('index'), Hyde will retrieve that route from the route collection.
    • -
-

The HydeKernel

-

If you have not yet read the HydeKernel Documentation, here's a quick recap:

-

The HydeKernel encapsulates a HydePHP project, providing helpful methods for interacting with it. -It is also responsible for booting the application, which includes the autodiscovery process.

-

The kernel is created very early on in the application lifecycle, in the bootstrap.php file, where it is also bound -as a singleton into the application service container.

-

At this point you might be wondering why we're talking about the kernel when this article is about autodiscovery. -Well, as you'll see in just a moment, the kernel is responsible for initiating the autodiscovery process. -The kernel is also where the discovered data is stored in memory, so it's important to understand how it works.

-

The kernel lifecycle

-

Now that we know the role of the HydeKernel, let's take a look at its lifecycle. The kernel is "lazy-booted", meaning -that the all the heavy lifting only happens when you actually need it. Once booted, the kernel data will stay in memory -until the console application is terminated.

-

The kernel data is primarily stored in three collections that get generated during the kernel's boot process. -Let's take a look at a simplified version of the kernel's boot method to see how this works.

-
public function boot(): void
-{
-    $this->files = FileCollection::boot($this);
-    $this->pages = PageCollection::boot($this);
-    $this->routes = RouteCollection::boot($this);
-
-    // Scroll down to see what this is used for
-    $this->booted = true;
-}
-
-

Here you'll see that we boot the three collections. This is where all the autodiscovery magic happens!

-

Deep dive into lazy-booting

-

If you're curious about how the kernel is lazy-booted, here's how it works! -Feel free to skip this section if this doesn't interest you.

-
// This will boot the kernel if it hasn't been booted yet
-public function pages(): PageCollection
-{
-    $this->needsToBeBooted();
-
-    return $this->pages;
-}
-
-// This is the method that triggers the boot process
-protected function needsToBeBooted(): void
-{
-    if (! $this->booted) {
-        $this->boot();
-    }
-}
-
-

Yeah, it's really unglamorous I know. But it works! Having it like this will ensure that any time you call Hyde::pages(), -that underlying collection will always have been booted and be ready to use.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/automatic-routing.html b/docs/docs/master/automatic-routing.html index 30cdfb83..58ae753e 100644 --- a/docs/docs/master/automatic-routing.html +++ b/docs/docs/master/automatic-routing.html @@ -1,421 +1,8 @@ - - -HydePHP Upcoming Documentation - Automatic Routing - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
- -
-
-

Automatic Routing

-

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.

-

High-level overview

-

If you've ever worked in an MVC framework, you are probably familiar with the concept of routing. -And you are probably also familiar with how boring and tedious it can be. Thankfully, Hyde takes the pain out of routing -through the Hyde Autodiscovery process.

-

Internally, when booting the HydeCLI application, Hyde will automatically discover all the content files in the source -directories, and create a route index for all of them. This index works as a two-way link between source files and compiled files.

-

Don't worry if this sounds complex, as the key takeaway is that the index is created and maintained automatically. -Nevertheless, the routing system provides several helpers that you can optionally use in your Blade views to -automatically resolve relative links and other useful features.

-

You can see all the routes and their corresponding source files by running the hyde route:list command.

-
php hyde route:list
-
-

Accessing routes

-

Each 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. -There 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, -and it will return the Route object. The route key is generally <page-output-directory/page-identifier>. Here are some examples:

-
// Source file: _pages/index.md/index.blade.php
-// Compiled file: _site/index.html
-Routes::get('index')
-
-// Source file: _posts/my-post.md
-// Compiled file: _site/posts/my-post.html
-Routes::get('posts/my-post')
-
-// Source file: _docs/readme.md
-// Compiled file: _site/docs/readme.html
-Routes::get('docs/readme')
-
-

Using the x-link component

-

When designing Blade layouts it can be useful to use the x-link component to automatically resolve relative links.

-

You can of course, use it just like a normal anchor tag like so:

-
<x-link href="index.html">Home</x-link>
-
-

But 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.

-
<x-link :href="Routes::get('index')">Home</x-link>
-
-

You can of course, also supply extra attributes like classes:

-
<x-link :href="Routes::get('index')" class="btn btn-primary">Home</x-link>
-
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/blog-posts.html b/docs/docs/master/blog-posts.html index 73237cbd..c84683bc 100644 --- a/docs/docs/master/blog-posts.html +++ b/docs/docs/master/blog-posts.html @@ -1,600 +1,8 @@ - - -HydePHP Upcoming Documentation - Creating Blog Posts - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Creating Blog Posts

-
-
-

Introduction to Hyde Posts

-

Making blog posts with Hyde is easy. At the most basic level, all you need is to add a Markdown file to your _posts folder.

-

To use the full power of the Hyde post module however, you'll want to add YAML Front Matter to your posts.

-

You can interactively scaffold posts with automatic front matter using the HydeCLI:

-
php hyde make:post
-
-

Learn more about scaffolding posts, and other files, in the console commands documentation.

-

Short Video Tutorial

- -

Best Practices and Hyde Expectations

-

Since Hyde does a lot of things automatically, there are some things you may need -to keep in mind when creating blog posts so that you don't get unexpected results.

-

Filenames

-
    -
  • Markdown post files are stored in the _posts directory
    • -
  • The filename is used as the filename for the compiled HTML
    • -
  • Filenames should use kebab-case-name followed by the extension .md -
    • -
  • Files prefixed with _underscores are ignored by Hyde
    • -
  • Your post will be stored in _site/posts/<identifier>.html -
    • -
-

Example:

-
✔ _posts/hello-world.md # Valid and will be compiled to _site/posts/hello-world.html
-
-

Front Matter

-

Front matter is optional, but highly recommended for blog posts as the front matter is used to construct dynamic HTML -markup for the post as well as meta tags and post feeds.

-

You are encouraged to look at the compiled HTML to learn -and understand how your front matter is used. You can read more about the Front Matter format in the Front Matter documentation.

-

Blog Post Example

-

Before digging in deeper on all the supported options, let's take a look at what a basic post with front matter looks like.

-
Filepath: _posts/my-new-post.md---
-title: My New Post
-description: A short description used in previews and SEO
-category: blog
-author: Mr. Hyde
-date: 2022-05-09 18:38
----
-
-## Write your Markdown here
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit.
-Autem aliquid alias explicabo consequatur similique,
-animi distinctio earum ducimus minus, magnam.
-
-

Supported Front Matter properties

-

Post Front Matter Schema

-

Here is a quick reference of the supported front matter properties. -Keep on reading to see further explanations, details, and examples.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KEY NAMEVALUE TYPEEXAMPLE / FORMAT
titlestring"My New Post"
descriptionstring"A short description"
categorystring"my favorite recipes"
datestring"YYYY-MM-DD [HH:MM]"
authorstring/arraySee author section
imagestring/arraySee image section
-

Note that YAML here is pretty forgiving. In most cases you do not need to wrap strings in quotes, -but it can help in certain edge cases, for example if the text contains special Yaml characters, thus they are included here.

-

In the examples below, when there are multiple examples, they signify various ways to use the same property.

-

When specifying an array you don't need all the sub-properties. The examples generally show all the supported values.

-

Title

-
title: "My New Post"
-
-

Description

-
description: "A short description used in previews and SEO"
-
-

Category

-
category: blog
-
-
category: "My favorite recipes"
-
-

Date

-
date: "2022-01-01"
-
-
date: "2022-01-01 12:00"
-
-

Author

-

Specify a page author, either by a username for an author defined in the authors config, or by an arbitrary name, -or by an array of author data. See the Post Author section for more details.

-

Arbitrary name displayed "as is"

-
author: "Mr. Hyde"
-
-

Username defined in authors config

-
author: mr_hyde
-
-

Array of author data

-
author:
-    name: "Mr. Hyde"
-    username: mr_hyde
-    website: https://twitter.com/HydeFramework
-
-

When specifying an array you don't need all the sub-properties. The example just shows all the supported values. -Array values here will override all the values in the authors config entry.

-

Image

-

Specify a cover image for the post, either by a local image path for a file in the _media/ directory, or by a full URL. -Any array data is constructed into a dynamic fluent caption, and injected into post and page metadata.

-

Local image path

-

When supplying an image source with a local image path, the image is expected to be stored in the _media/ directory. -Like all other media files, it will be copied to _site/media/ when the site is built, so Hyde will resolve links accordingly.

-
image: image.jpg
-
-

Full URL

-

Full URL starting with http(s)://) or // (protocol-relative). -The image source will be used as-is, and no additional processing is done.

-
image: https://cdn.example.com/image.jpg
-
-

Data-rich image

-

You can also supply an array of data to construct a rich image with a fluent caption.

-
image:
-    source: Local image path or full URL
-    altText: "Alt text for image"
-    titleText: "Tooltip title"
-    copyright: "Copyright (c) 2022"
-    licenseName: "CC-BY-SA-4.0"
-    licenseUrl: https://example.com/license/
-    authorUrl: https://photographer.example.com/
-    authorName: "John Doe"
-
-
-

See posts/introducing-images -for a detailed blog post with examples and schema information!

-
-

Using images in posts

-

To use images stored in the _media/ directory, you can use the following syntax:

-
![Image Alt](../media/image.png "Image Title")
-
-

Note the relative path since the blog post is compiled to posts/example.html

-

To learn more, check out the chapter in managing assets

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/build-tasks.html b/docs/docs/master/build-tasks.html index 45316d61..28a38812 100644 --- a/docs/docs/master/build-tasks.html +++ b/docs/docs/master/build-tasks.html @@ -1,511 +1,8 @@ - - -HydePHP Upcoming Documentation - Custom Build Tasks - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Custom Build Tasks

-
-
-

Introduction

-

The Build Task API offers a simple way to hook into the build process. -The build tasks are very powerful and allow for limitless customizability.

-

The built-in Hyde features like sitemap generation and RSS feeds are created using tasks like these. -Maybe you want to create your own, to for example upload the site to FTP or copy the files to a public directory? -You can also overload the built-in tasks to customize them to your needs.

-

Good to know before you start

-

Types of tasks

-

There 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.

-

To choose which type of task you want to create, you extend either the PreBuildTask or PostBuildTask class. -Both 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.

-

About these examples

-

For most of these examples we will focus on the PostBuildTasks as they are the most common.

-

For all these examples we assume you put the file in the App/Actions directory, but you can put them anywhere.

-

Interacting with output

-

In 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.

-

In 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.

-

Creating build tasks

-

Minimal example

-

Here is a minimal example to give you an idea of what we are working with.

-
class SimpleBuildTask extends PostBuildTask
-{
-    public function handle(): void
-    {
-        //
-    }
-}
-
-

As you can see, at their core, build tasks are simple classes containing a handle() method, -which as I'm sure you have guessed, is the method that is executed when the task is run by the build command.

-

If you want the task to run before the build, you would extend the PreBuildTask class instead.

-

Automatic output

-

When running the build command, you will see the following output added after the build is complete.

-
- Generic build task... Done in 0.26ms
-
-

As 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.

-

Full example

-

Here is a full example, with all the namespaces included, as well as the most common fluent output helpers.

-
<?php
-
-namespace App\Actions;
-
-use Hyde\Framework\Features\BuildTasks\PostBuildTask;
-
-class ExampleTask extends PostBuildTask
-{
-    public static string $message = 'Say hello';
-
-    public function handle(): void
-    {
-        $this->info('Hello World!');
-    }
-
-    public function printFinishMessage(): void
-    {
-        $this->line('Goodbye World!');
-    }
-}
-
-

You 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.

-

Running this task will produce the following output:

-
-$ php hyde build
-  Say hello... Hello World!
-  Goodbye World!
-
-

As 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.

-

Registering the tasks

-

There are a few ways to register these tasks so Hyde can find them.

-

They 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.

-

Autodiscovery registration

-

The easiest way to register build tasks, is to not do it. Just let Hyde do it for you!

-

Any classes that end in BuildTask.php that are stored in app/Actions will be autoloaded and registered to run automatically.

-

For example: app/Actions/ExampleBuildTask.php.

-

Config file registration

-

If 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.

-
Filepath: config/hyde.php'build_tasks' => [
-    \App\Actions\SimpleTask::class,
-    \MyPackage\Tasks\MyBuildTask::class,
-],
-
-

Programmatic registration

-

This option assumes you are familiar with Laravel's service container and service providers.

-

If you are developing an extension, you can either instruct users register your tasks with the config option above, -or you can register the extensions programmatically, I recommend you do this in the boot method of a service provider.

-

The build tasks are registered in an internal array of the BuildService class, which is bound as a singleton in the underlying Laravel service container. -To actually register your task, provide the fully qualified class name of the task to the BuildTaskService::registerTask() method.

-

Here is an example of how to do this using in a service provider. Though you could technically do it anywhere using the app() helper, just as long as it's done early enough in the application lifecycle, so it's registered before the build command is executed.

-
class MyServiceProvider extends ServiceProvider
-{
-    public function boot(): void
-    {
-        $this->app->make(\Hyde\Framework\Services\BuildTaskService::class)
-            ->registerTask(\MyPackage\Tasks\MyBuildTask::class);
-    }
-}
-
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/collections.html b/docs/docs/master/collections.html index 4983a750..078610e8 100644 --- a/docs/docs/master/collections.html +++ b/docs/docs/master/collections.html @@ -1,601 +1,8 @@ - - -HydePHP Upcoming Documentation - File-based Collections - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

File-based Collections

-
-
-

Introduction to Hyde Data Collections

-

Hyde provides DataCollections, a subset of Laravel Collections giving you -a similar developer experience to working with Eloquent Collections. However, instead of accessing a database, -it's all entirely file-based using static data files such as Markdown, Yaml, and JSON files which get -parsed into objects that you can easily work with.

-

As you have access to all standard Laravel Collection methods, you are encouraged to read the -Laravel Collections documentation for more information.

-

This 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.

-

High-Level Concept Overview

-

To make collections easy to use and understand, Hyde makes a few assumptions about the structure of your collections. -Follow these conventions and creating dynamic static sites will be a breeze.

-
    -
  1. Collections are accessed through static methods in the DataCollections class.
    2. -
  2. Collections are stored as files in subdirectories of the resources/collections directory.
    3. -
  3. To get a collection, specify name of the subdirectory the files are stored in.
    4. -
  4. Data will be parsed into differing objects depending on which facade method you use. See the table below.
    5. -
  5. The class is aliased so that you can use it in Blade files without having to include the namespace.
    6. -
  6. While not enforced, each subdirectory should probably only have the same filetype to prevent developer confusion
    7. -
  7. Unlike source files for pages, files starting with underscores are not ignored.
    8. -
  8. You can customize the source directory for collections through a service provider.
    9. -
  9. If the base source directory does not exist, it will be created for you.
    10. -
-

Available Collection Types

-

Quick Reference Overview

-

The following facade methods for creating data collections are available:

-
\Hyde\Support\DataCollections::markdown(string $name);
-\Hyde\Support\DataCollections::yaml(string $name);
-\Hyde\Support\DataCollections::json(string $name, bool $asArray = false);
-
-

Quick Reference Table

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Collection TypeFacade MethodReturned Object TypeFile Extension
Markdown::markdown()MarkdownDocument.md
Yaml::yaml()FrontMatter.yaml,  .yml
Json::json()stdClass OR  array.json
-

Markdown Collections

-

Usage

-
$collection = \Hyde\Support\DataCollections::markdown('name');
-
-

Example returns

-

Here is an approximation of the data types contained by the variable created above:

-
\Hyde\Support\DataCollections {
-    "testimonials/1.md" => Hyde\Markdown\Models\MarkdownDocument
-    "testimonials/2.md" => Hyde\Markdown\Models\MarkdownDocument
-    "testimonials/3.md" => Hyde\Markdown\Models\MarkdownDocument
-  ]
-}
-
-

The returned MarkdownObjects look approximately like this:

-
\Hyde\Markdown\Models\MarkdownDocument {
-  +matter: Hyde\Markdown\Models\FrontMatter {
-     +data: array:1 [
-       "author" => "John Doe"
-     ]
-  }
-  +markdown: Hyde\Markdown\Models\Markdown {
-    +body: "Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
-  }
-}
-
-

Assuming the Markdown document looks like this:

-
---
-author: "John Doe"
----
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit...
-
-

Yaml Collections

-

Usage

-
$collection = \Hyde\Support\DataCollections::yaml('name');
-
-

Example returns

-

Here is an approximation of the data types contained by the variable created above:

-
\Hyde\Support\DataCollections {
-  "authors/1.yaml" => Hyde\Markdown\Models\FrontMatter {
-    +data: array:1 [
-      "name" => "John Doe",
-      "email" => "john@example.org"
-    ]
-  }
-}
-
-

Assuming the Yaml document looks like this:

-
---
-name: "John Doe"
-email: "john@example.org"
-
-

Note that the Yaml file should start with --- to be parsed correctly.

-

Json Collections

-

Usage

-
$collection = \Hyde\Support\DataCollections::json('name');
-
-

By default, the entries will be returned as stdClass objects. If you want to return an associative array instead, pass true as the second parameter:

-
$collection = \Hyde\Support\DataCollections::json('name', true);
-
-

Since 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.

-

Markdown Collections - Hands-on Guide

-

I think the best way to explain DataCollections is through examples, so let's create a Blade page with customer testimonials!

-

This example will use Markdown Collections, but the same concepts apply to all other collection types.

-

Setting up the file structure

-

We start by setting up our directory structure. We will create a testimonials subdirectory, which will be the collection name.

-

In it, we will place Markdown files. Each file will be a testimonial. -The Markdown will be parsed into a MarkdownDocument object which parses any optional YAML front matter.

-

Here is the sample Markdown we will use:

-
Filepath: resources/collections/testimonials/1.md---
-author: John Doe
----
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit...
-
-

Let's take a look at our directory structure. I just copied the same file a few times. -You can name the files anything you want, I kept it simple and just numbered them.

-
resources/collections
-└── testimonials
-    ├── 1.md
-    ├── 2.md
-    └── 3.md
-
-

Using the Facade to Access the Collections

-

Now for the fun part! We will use the DataCollections::markdown() to access all our files into a convenient object. -The class is registered with an alias, so you don't need to include any namespaces when in a Blade file.

-

The general syntax to use the facade is as follows:

-
DataCollections::markdown('subdirectory_name')
-
-

This will return a Hyde DataCollections object, containing our Markdown files as MarkdownDocument objects. Here is a quick look at the object the facade returns:

-
^ Hyde\Support\DataCollections {#651 ▼
-  #items: array:3 [▼
-    "testimonials/1.md" => Hyde\Markdown\Models\MarkdownDocument {#653 ▼
-      +matter: Hyde\Markdown\Models\FrontMatter {#652 ▶}
-      +markdown: Hyde\Markdown\Models\Markdown {#654 ▶}
-    }
-    "testimonials/2.md" => Hyde\Markdown\Models\MarkdownDocument {#656 ▶}
-    "testimonials/3.md" => Hyde\Markdown\Models\MarkdownDocument {#659 ▶}
-  ]
-}
-
-

Implementing it in a Blade view

-

Let's create a Blade page to display all our testimonials.

-
php hyde make:page "Testimonials" --type="blade"
-
-

And we can use the collection almost like any other Laravel one. As you can see, since each entry is a MarkdownDocument class, -we are able to get the author from the front matter, and the content from the body.

-
Filepath: _pages/testimonials.blade.php@foreach(DataCollections::markdown('testimonials') as $testimonial)
-    <blockquote>
-        <p>{{ $testimonial->body }}</p>
-        <small>{{ $testimonial->matter['author'] }}</small>
-    </blockquote>
-@endforeach
-
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/compile-and-deploy.html b/docs/docs/master/compile-and-deploy.html index e261bed1..686734c3 100644 --- a/docs/docs/master/compile-and-deploy.html +++ b/docs/docs/master/compile-and-deploy.html @@ -1,451 +1,8 @@ - - -HydePHP Upcoming Documentation - Compile and Deploy your site - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Compile and Deploy your site

-
-
-

Running the build command

-

Now that you have some amazing content, you'll want to compile your site into static HTML.

-

This is as easy as executing the build command:

-
php hyde build
-
-

You can also compile a single file:

-
php hyde rebuild <filepath>
-
-

And, you can even start a development server to compile your site on the fly:

-
php hyde serve
-
-

Further reading

-

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!

-

Learn more about these commands in the console commands documentation:

- -
-

Deploying your site

-

One of the things that make static sites so enjoyable to work with is how easy it is to deploy them to the web. -This list is not exhaustive, but gives you a general idea of the most common ways to deploy your site. -If you have ideas to add to the documentation, please send a pull request!

-

General deployment

-

In essence, all you need to do is copy the contents of the _site directory to a web server, and you're done.

-

Once the site is compiled there is nothing to configure or worry about.

-

FTP and File Managers

-

If you have a conventional web host, you can use FTP/SFTP/FTPS to upload your compiled site files to the web server. -Some web hosting services also have web based file managers.

-

To deploy your site using any of these methods, all you need to do is upload the entire contents of your _site -directory to the web server's public document root, which is usually the public_html, htdocs, or www directory.

-

GitHub Pages - Manually

-

GitHub Pages is a free service that allows you to host your static site on the web.

-

In general, push the entire contents of your _site directory to the gh-pages branch of your repository, -or the docs/ directory on your main branch, depending on how you set it up.

-

Please see the GitHub Pages documentation for more information.

-

GitHub Pages - CI/CD

-

Hyde works amazing with GitHub Pages and GitHub Actions and the entire build and deploy process can be automated.

- -

By the way, HydePHP.com is hosted on GitHub Pages, and the site is compiled in a GitHub Action workflow that compiles and -deploys the site automatically when the source is updated using this GitHub workflow.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/console-commands.html b/docs/docs/master/console-commands.html index 555de012..fb333fc5 100644 --- a/docs/docs/master/console-commands.html +++ b/docs/docs/master/console-commands.html @@ -1,817 +1,8 @@ - - -HydePHP Upcoming Documentation - Console Commands - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Console Commands

-
-
-

The primary way of interacting with Hyde is through the command line using the HydeCLI.

-

If you have ever used the Artisan Console in Laravel you will feel right at home, -the HydeCLI is based on Artisan after all!

-

Introduction

-

To use the HydeCLI, run php hyde from your project directory followed by a command.

-

All HydeCLI commands start with php hyde. Anything in [brackets] is optional. -If an argument or option value has a space in it, it needs to be wrapped in quotes.

-

The HydeCLI exists at the root of your application as the hyde script and provides a number of helpful commands that can -assist you while you build your site. To view a list of all available Hyde commands, you may use the list command:

-
// torchlight! {"lineNumbers": false}
-php hyde list
-
-

Got stuck? The CLI can help.

-

Every command also includes a "help" screen which displays and describes the command's available arguments and options. -To view a help screen, precede the name of the command with help:

-
// torchlight! {"lineNumbers": false}
-php hyde help <command>
-
-

You can also always add --help to a command to show detailed usage information.

-
// torchlight! {"lineNumbers": false}
-php hyde <command> --help
-
-

Available Commands

-

Here is a quick reference of all the available commands. You can also run php hyde list to see this list.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandDescription
buildBuild the static site
serveStart the realtime compiler server
rebuildRun the static site builder for a single file
build:rssGenerate the RSS feed
build:searchGenerate the docs/search.json file
build:sitemapGenerate the sitemap.xml file
make:pageScaffold a new Markdown, Blade, or documentation page file
make:postScaffold a new Markdown blog post file
publish:configsPublish the default configuration files
publish:homepagePublish one of the default homepages as index.blade.php
publish:viewsPublish the hyde components for customization. Note that existing files will be overwritten
vendor:publishPublish any publishable assets from vendor packages
route:listDisplay all registered routes
validateRun a series of tests to validate your setup and help you optimize your site
listList all available commands
-

Build the static site

-

-
// torchlight! {"lineNumbers": false}
-php hyde build [--run-dev] [--run-prod] [--run-prettier] [--pretty-urls] [--no-api]
-
-

Build the static site

-

Options

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
--run-devRun the NPM dev script after build
--run-prodRun the NPM prod script after build
--run-prettierFormat the output using NPM Prettier
--pretty-urlsShould links in output use pretty URLs?
--no-apiDisable API calls, for example, Torchlight
-

Run the static site builder for a single file

-

-
// torchlight! {"lineNumbers": false}
-php hyde rebuild <path>
-
-

Run the static site builder for a single file

-

Arguments

- - - - - - - - - - - - - -
pathThe relative file path (example: _posts/hello-world.md) \n - Is required: yes
-

Start the realtime compiler server

-

-
// torchlight! {"lineNumbers": false}
-php hyde serve [--host [HOST]] [--port [PORT]]
-
-

Start the realtime compiler server.

-

Options

- - - - - - - - - - - - - - - - - -
--host=[default: "localhost"]
--port=[default: 8080]
-

Test and validate your project to optimize your site

-

-
// torchlight! {"lineNumbers": false}
-php hyde validate
-
-

Run a series of tests to validate your setup and help you optimize your site.

-

Generate the RSS feed

-

-
// torchlight! {"lineNumbers": false}
-php hyde build:rss
-
-

Generate the RSS feed

-

Generate the docs/search.json file

-

-
// torchlight! {"lineNumbers": false}
-php hyde build:search
-
-

Generate the docs/search.json file

-

Generate the sitemap.xml file

-

-
// torchlight! {"lineNumbers": false}
-php hyde build:sitemap
-
-

Generate the sitemap.xml file

-

Scaffold a new Markdown, Blade, or documentation page file

-

-
// torchlight! {"lineNumbers": false}
-php hyde make:page [--type [TYPE]] [--blade] [--docs] [--force] [--] [<title>]
-
-

Scaffold a new Markdown, Blade, or documentation page file

-

Arguments & Options

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
titleThe name of the page file to create. Will be used to generate the filename
--type=markdownThe type of page to create (markdown, blade, or docs)
--bladeCreate a Blade page
--docsCreate a Documentation page
--forceOverwrite any existing files
-

Scaffold a new Markdown blog post file

-

-
// torchlight! {"lineNumbers": false}
-php hyde make:post [--force] [--] [<title>]
-
-

Scaffold a new Markdown blog post file

-

Arguments & Options

- - - - - - - - - - - - - - - - - -
titleThe title for the Post. Will also be used to generate the filename
--forceShould the generated file overwrite existing posts with the same filename?
-

Publish the default configuration files

-

-
// torchlight! {"lineNumbers": false}
-php hyde publish:configs
-
-

Publish the default configuration files

-

Publish one of the default homepages as index.blade.php.

-

-
// torchlight! {"lineNumbers": false}
-php hyde publish:homepage [--force] [--] [<homepage>]
-
-

Publish one of the default homepages as index.blade.php.

-

Arguments & Options

- - - - - - - - - - - - - - - - - -
homepageThe name of the page to publish
--forceOverwrite any existing files
-

Publish the hyde components for customization

-

-
// torchlight! {"lineNumbers": false}
-php hyde publish:views [<category>]
-
-

Publish the hyde components for customization. Note that existing files will be overwritten.

-

Arguments

- - - - - - - - - - - - - -
categoryThe category to publish
-

Display all registered routes.

-

-
// torchlight! {"lineNumbers": false}
-php hyde route:list
-
-

Display all registered routes.

-

Publish any publishable assets from vendor packages

-

-
// torchlight! {"lineNumbers": false}
-php hyde vendor:publish [--existing] [--force] [--all] [--provider [PROVIDER]] [--tag [TAG]]
-
-

Publish any publishable assets from vendor packages

-

Options

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
--existingPublish and overwrite only the files that have already been published
--forceOverwrite any existing files
--allPublish assets for all service providers without prompt
--provider=The service provider that has assets you want to publish
--tag=One or many tags that have assets you want to publish \n- Is multiple: yes
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/core-concepts.html b/docs/docs/master/core-concepts.html index 8c12d533..836b02ee 100644 --- a/docs/docs/master/core-concepts.html +++ b/docs/docs/master/core-concepts.html @@ -1,809 +1,8 @@ - - -HydePHP Upcoming Documentation - Core HydePHP Concepts - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Core HydePHP Concepts

-
-
-

Introduction to the Hyde Framework

-

What makes HydePHP special are its "magic" features like autodiscovery and intelligent data generation. -All designed so that you can focus on your content, while the framework does the heavy lifting.

-

This page provides a high-level overview of the framework's capabilities, so you can quickly grasp its benefits. -As you delve deeper into the documentation, you'll discover the details of each feature and learn how to leverage them effectively.

-

The HydeCLI

-

When you are not writing Markdown and Blade, most of your interactions with Hyde will be through the command line -using the HydeCLI, which is based on the Laravel Artisan Console that you may already be familiar with.

-

If you want to learn about the available commands and how to use them, you can visit the Console Commands page, -or you can run any of the built-in help commands to get a list of available commands and their descriptions.

-
php hyde list
-php hyde help <command>
-php hyde <command> [--help]
-
-

Directory structure

-

To take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DirectoryPurpose
_docsFor documentation pages
_postsFor blog posts
_pagesFor static Markdown and Blade pages
_mediaStore static assets to be copied to the build directory
_siteThe build directory where your compiled site will be stored
configConfiguration files for Hyde and integrations
resources/assetsLocation for Laravel Mix source files (optional)
resources/viewsLocation for Blade components (optional)
appLocation for custom PHP classes (optional)
-

Page Models

-

The Hyde page models are an integral part of how HydePHP creates your static site. Each page in your site is represented -by a page model. These are simply PHP classes that in addition to holding both the source content and computed data -for your pages, also house instructions to Hyde on how to parse, process, and render the pages to static HTML.

-

The page classes are very important and fill two roles:

-
    -
  1. They act as blueprints containing static instructions for how to parse, process, and, render pages.
    2. -
  2. Each class instance also holds the page source contents, as well as the computed data.
    3. -
-

To learn more, you can visit the Page Models page.

-

File Autodiscovery

-

Content files, meaning source Markdown and Blade files, are automatically discovered by Hyde and compiled to HTML when -building the site. This means that you don't need to worry about routing and controllers!

-

The directory a source file is in will determine the Blade template that is used to render it.

-

All source and output directories are configurable, but the defaults are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Page/File TypeSource DirectoryOutput DirectoryFile Extensions
Static Pages_pages/_site/.md, .blade.php
Blog Posts_posts/_site/posts/.md
Documentation_docs/_site/docs/.md
Media Assets_media/_site/media/Common asset types
-

Paths, Identifiers, and Route Keys

-

Since HydePHP automatically discovers and compiles content files, it is important to understand how HydePHP handles paths, -as the file names and directories they are in will directly influence how the page will be compiled.

-

As such, it will be helpful for you to know about the following terms:

-
    -
  • -Path: The full path to a file, including the file name, directory, and extension.
    • -
  • -Identifier: The unique identifier for a page. Unique only within the same page type.
    • -
  • -Route key: The key used to access the page in the routing system. Unique across all site pages.
    • -
-

Both the identifier and route key are derived from the path of the page. The identifier is the path without the file -extension, and relative to the page type source directory. The route key is the output directory plus the identifier.

-

The identifier generation can be visualized as follows, where the identifier is underlined:

-
  _pages/about/contact.md
-

For a Markdown page, like the example above, the route key would be the same as the identifier, since Markdown pages are -output to the site root. If it was a Markdown post however, the route key would be: posts/about/contact.

-

This can be visualized as follows, assuming a blog post is stored as _posts/hello-world.md:

-
  _site/posts/hello-world.html
-

As you can see, the route key is simply put the relative page URL, without the .html extension.

-

Convention over Configuration

-

Hyde favours the "Convention over Configuration" paradigm and thus comes preconfigured with sensible defaults. -However, Hyde also strives to be modular and endlessly customizable hackable if you need it. -Take a look at the customization and configuration guide to see the endless options available!

-

Front Matter

-

In a nutshell: Front Matter is a block of YAML containing metadata, stored at the top of a Markdown file.

-

Front 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.

-

Using 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.)

-

To learn more, you can visit the Front Matter page.

-

Front Matter in Markdown

-

All Markdown content files support Front Matter, and blog posts make heavy use of it. Here's what it may look like:

-
---
-title: "My New Post"
-author: "Mr Hyde"
-date: "2023-03-14"
----
-
-## Markdown comes here
-
-Lorem ipsum dolor sit amet, etc.
-
-

Front Matter in Blade

-

HydePHP has experimental support for creating front-matter in Blade templates, called BladeMatter, -where code in @php directives are statically parsed into page object's front matter data where it can be accessed in your templates.

-
@php($title = 'BladeMatter Demo') // Equivalent to `title: 'BladeMatter Demo'` in Yaml
-
-

Automatic Routing

-

In a nutshell: Hyde will automatically create routes for your source files.

-

If you've ever worked in an MVC framework, you are probably familiar with the concept of routing. -And 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!

-

During the Autodiscovery process. Hyde will automatically discover all the content files in the source directories, -and 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.

-

You can see all the routes and their corresponding source files by running the hyde route:list command.

-
php hyde route:list
-
-

To access routes in your code, simply use the Routes facade and specify the route key for the desired page.

-
Routes::get('posts/my-post')
-
-

To learn more about the routing system, please visit the routing documentation.

-

Global Page Data

-

During the build of each page, Hyde will inject some data available to all Blade views. If you are not planning to write -any custom Blade templates, you can safely ignore this section. If you are, here are the three global variables you can use:

- -

The $page variable is likely to the most important one, as it contains all the data for the current page. -Depending on the page type, you will have different helpers available. But $page->matter() is likely to be very helpful.

-

You can see all the helpers in the Page API reference page.

-

Terminology

-

In this quick reference, we'll briefly go over some terminology and concepts used in HydePHP. -This will help you understand the documentation and codebase better, as well as helping you know what to search for when you need help.

-

Table of contents

-
-
-

Tools

- -
-
-

Languages

- -
-
-

General Concepts

- -
-
-

HydePHP Features

- -
-
-

HydePHP

-

HydePHP is a static site generator written in PHP, designed to make it easy for developers to build fast and secure websites. -It uses a simple directory structure and templating system to generate static websites from content files, -and can be easily extended using PHP libraries and packages.

-

Laravel

-

Laravel is the PHP framework that HydePHP is built on top of. We use a specialized version called Laravel Zero, -which is optimized for command-line applications.

-

Front Matter

-

Front Matter is a block of YAML, stored at the top of a Markdown file, enclosed by a set of triple-dashed lines. -It is commonly used to store metadata about the content, such as the title, author, date, etc.

-

Markdown

-

Markdown is a lightweight markup language that uses plain text formatting syntax, designed to make it easy to create -structured content for the web. HydePHP uses Markdown as the base for most of its content files.

-

Blade

-

Blade is the templating engine from Laravel, which allows developers to write clean and reusable code for the -presentation layer of web applications. HydePHP uses Blade both for the built-in views and components, -as well as to provide powerful templating capabilities through Blade-based pages.

-

YAML

-

YAML is a human-readable data serialization format used for configuration files and often used as the syntax for -Front Matter in HydePHP content files. YAML is designed to be easily read by humans and parsed by machines, -making it a popular choice for many applications and frameworks.

-

PHP

-

PHP is a popular server-side scripting language used for web development that can be embedded in HTML. -HydePHP is built on top of PHP and utilizes its powerful capabilities for generating static websites.

-

HTML

-

HTML (Hypertext Markup Language) is the standard markup language used to create web pages and web applications. -HydePHP uses HTML to render the static websites generated from its content files and templates.

-

Tailwind CSS

-

Tailwind CSS is a utility-first CSS framework used for rapidly building custom user interfaces. -HydePHP supports Tailwind CSS out of the box through the built-in Blade templates, -making it easy for developers to create beautiful and responsive websites without writing custom CSS.

-

Composer

-

Composer is a dependency manager for PHP that simplifies the process of installing and managing packages required by -PHP applications. HydePHP uses Composer to manage its own dependencies and make it easy for users to install and use the software.

-

Static Sites

-

A static website is a collection of HTML web pages that are delivered to the user's web browser exactly as they are stored -on the web server. HydePHP generates static websites, making them fast, secure, and easy to deploy.

-

Version Control

-

HydePHP can be easily integrated with Git to manage website source files and track changes over time, -as one of the many benefits with static sites is that they are designed to be version controlled.

-

Git

-

Git is a free and open-source distributed version control system that is widely used for software development. -Git repositories can be hosted on GitHub, GitLab, BitBucket, or any other Git hosting service.

-

Autodiscovery

-

Content files, including Markdown and Blade files, are automatically discovered and compiled to HTML during site builds. -During autodiscovery, Hyde also generates dynamic data to enrich your content based on the page type.

-

In short the autodiscovery is split into three steps: -File discovery -> Page parsing -> Route generation

-

Page Types

-

All pages in HydePHP are internally represented by a page object that extends the HydePage class. Each page type has its -own page class which acts as a blueprint defining information for the framework to parse a file and generate relevant data.

-

Page Identifiers

-

The page identifier is the name of the file without the file extension, relative to the page type's source directory. -The identifier is used to generate the route key, which is used to generate the file name for the compiled HTML file.

-

Routes

-

All pages are internally bound to a Route object, through the route key. During the build process, each route is -compiled to HTML using the page object's data, and saved to the output directory with a file name created from the route key. -Since routes are generated automatically during autodiscovery, there is no need to create them manually.

-

Route Keys

-

The route key is the URL path relative to the site webroot, without the file extension. The route key is the common -identifier binding Page objects to Route objects, and is used to generate the file name for the compiled HTML file.

-

Route keys generation can be visualised as follows: <PageClass::OutputDirectory>/<PageIdentifier>

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/customization.html b/docs/docs/master/customization.html index 12ab2b65..0ffc896f 100644 --- a/docs/docs/master/customization.html +++ b/docs/docs/master/customization.html @@ -1,785 +1,8 @@ - - -HydePHP Upcoming Documentation - Customizing your Site - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Customizing your Site

-
-
-

Introduction

-

Hyde favours "Convention over Configuration" -and comes preconfigured with sensible defaults. However, Hyde also strives to be modular and endlessly customizable -if you need it. This page guides you through the many options available!

-

All the configuration files are stored in the config directory, and allow you to customize almost all aspects of your site. -Each option is documented, so feel free to look through the files and get familiar with the options available to you.

-

Accessing Configuration Values

-

Configuration API Recap

-

HydePHP uses the same configuration system as Laravel. Here's a quick recap from the Laravel Documentation:

-

You may easily access your configuration values using the global config function from anywhere in your project code. -The configuration values may be accessed using "dot notation" syntax, which includes the name of the file and option you wish to access.

-
$value = config('hyde.name');
-
-

A default value may also be specified and will be returned if the configuration option does not exist:

-
$value = config('hyde.name', 'HydePHP');
-
-

HydePHP also provides a strongly typed Config facade which extends the Laravel Config facade, but allows strict types:

-
use Hyde\Facades\Config;
-
-// Will always return a string, or it throws a TypeError
-$name = Config::getString('hyde.name', 'HydePHP'): string;
-
-

Dot Notation

-

As seen in the example above, when referencing configuration options, we often use "dot notation" to specify the configuration file. -For example, config('hyde.name') means that we are looking for the name option in the config/hyde.php file.

-

Front Matter or Configuration Files?

-

In 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.

-

A note on file paths

-

When Hyde references files, especially when passing filenames between components, the file path is almost always -relative to the root of the project. Specifying absolute paths yourself will likely lead to unforeseen problems.

-

Configuration Files Overview

-

There 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.

-

Below are two tables over the different configuration files. Click on a file name to see the default file on GitHub.

-

HydePHP Configuration Files

-

These 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. -The main configuration file, hyde.php, is used for things ranging from site name and base URL to navigation menus and what features to enable.

- - - - - - - - - - - - - - - - - - - - - - - - - -
Config FileDescription
hyde.phpMain HydePHP configuration file for customizing the overall project.
docs.phpOptions for the HydePHP documentation site generator module.
markdown.phpConfigure Markdown related services, as well as change the CommonMark extensions.
app/config.phpConfigures the underlying Laravel application. (Commonly found as config/app.php in Laravel apps)
-

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.

-

Publishable Laravel & Package Configuration Files

-

Since HydePHP is based on Laravel we also have a few configuration files related to them. As you most often don't need -to edit any of these, unless you want to make changes to the underlying application, they are not present in the -base HydePHP installation. However, you can publish them to your project by running php hyde publish:configs.

- - - - - - - - - - - - - - - - - - - - - - - - - -
Config FileDescription
view.phpConfigures the paths for the Blade View compiler.
cache.phpConfigures the cache driver and cache path locations.
commands.phpConfigures the Laravel Zero commands for the HydeCLI.
torchlight.phpConfigures settings for the Torchlight syntax highlighting integration.
-

If any of these files are missing, you can run php hyde publish:configs to copy the default files to your project.

-

Configuration Options

-

While all options are already documented within the files, here are some further explanations of some of the options.

-

RSS feed generation

-

When enabled, an RSS feed containing all your Markdown blog posts will be generated when you compile your static site. -Here are the default settings:

-
Filepath: config/hyde.php'rss' => [
-    // Should the RSS feed be generated?
-    'enabled' => true,
-
-    // What filename should the RSS file use?
-    'filename' => 'feed.xml',
-
-    // The channel description.
-    'description' => env('SITE_NAME', 'HydePHP').' RSS Feed',
-],
-
-

Note that this feature requires that a site url is set!

-

Authors

-

Hyde has support for adding authors in front matter, for example to -automatically add a link to your website or social media profiles. -However, it's tedious to have to add those to each and every -post you make, and keeping them updated is even harder.

-

You can predefine authors in the Hyde config. -When writing posts, just specify the username in the front matter, -and the rest of the data will be pulled from a matching entry.

-

Example

-
// torchlight! {"lineNumbers": false}
-'authors' => [
-    Author::create(
-        username: 'mr_hyde', // Required username
-        name: 'Mr. Hyde', // Optional display name
-        website: 'https://hydephp.com' // Optional website URL
-    ),
-],
-
-

This is equivalent to the following front matter in a blog post:

-
author:
-    username: mr_hyde
-    name: Mr. Hyde
-    website: https://hydephp.com
-
-

But you only have to specify the username:

-
author: mr_hyde
-
-

Footer

-

Most 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!

-

The footer component is made up of a few levels of components, depending on how much you want to customize.

-

Customizing the Markdown text

-

There are two ways to customize the footer text. First, you can set it in the configuration file:

-
Filepath: config/hyde.php'footer' => 'Site proudly built with [HydePHP](https://github.com/hydephp/hyde) 🎩',
-
-

If 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.

-
Filepath: resources/includes/footer.mdSite proudly built with [HydePHP](https://github.com/hydephp/hyde) 🎩
-
-

In both cases the parsed Markdown will be rendered in the footer Blade component.

-

Customizing the Blade component

-

The actual footer component is rendered using the layouts/footer.blade.php Blade template.

-

In 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.

-

Disabling the footer entirely

-

If you don't want to have a footer on your site, you can set the 'footer' configuration option to false.

-
Filepath: config/hyde.php'footer' => 'false',
-
-

Navigation Menu & Sidebar

-

One of my favourite features with Hyde is its automatic navigation menu and documentation sidebar generator.

-

How it works:

-

The sidebar works by creating a list of all the documentation pages.

-

The navigation menu is a bit more sophisticated, it adds all the top-level Blade and Markdown pages. -It also adds an automatic link to the docs if there is an index.md in the _docs directory.

-

Reordering Sidebar Items

-

Sadly, Hyde is not intelligent enough to determine what order items should be in (blame Dr Jekyll for this), -so you will probably want to set a custom order.

-

Reordering items in the documentation sidebar is as easy as can be. In the docs config, there is an array just for this. -If a page identifier is found here it will get priority calculated according to its position in the list, -plus an offset of 500. This offset allows you to pages earlier in the list using front matter.

-

If a page does not exist in the list they get priority 999, which puts them last. -You can also use front matter to set a priority for a page. -The front matter value will always take precedence.

-

Let's see an example:

-
Filepath: config/docs.php// These are the default values in the config. It puts the readme.md first in order.
-'sidebar_order' => [
-    'readme', // This is the first entry, so it gets the priority 500 + 0
-    'installation', // This gets priority 500 + 1
-    'getting-started', // And this gets priority 500 + 2
-    // Any other pages not listed will get priority 999
-]
-
-

Reordering Navigation Menu Items

-

As Hyde makes an effort to organize the menu items in a sensible way, your project comes preconfigured to put what it thinks are your most -important pages first. This may of course not always match what you want, so thankfully it's easy to reorder the menu items!

-

Simply update the navigation.order array in the Hyde config! The priorities set will determine the order of the menu items. -Lower values are higher in the menu, and any pages not listed will get priority 999, which puts them last.

-
Filepath: config/hyde.php'navigation' => [
-    'order' => [
-        'index' => 0, // _pages/index.md (or .blade.php)
-        'posts' => 10, // _pages/posts.md (or .blade.php)
-        'docs/index' => 100, // _docs/index.md
-    ]
-]
-
-

You can also set the priority of a page directly in the front matter. This will override any dynamically inferred or -config defined priority. While this is useful for one-offs, it can make it harder to reorder items later on. -It's up to you which method you prefer to use. This setting can be used both for the navigation menu and the sidebar.

-
---
-navigation:
-    priority: 10
----
-
-

Adding Custom Navigation Menu Links

-

You can easily add custom navigation menu links similar how we add Authors. Simply add a NavItem model to the navigation.custom array.

-

When linking to an external site, you should use the NavItem::forLink() method facade. The first two arguments are the -destination and label, both required. Third argument is the priority, which is optional, and defaults to 500.

-
Filepath: config/hyde.phpuse Hyde\Framework\Features\Navigation\NavItem;
-
-'navigation' => [
-    'custom' => [
-        NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
-    ]
-]
-
-

Simplified, this will then be rendered as follows:

-
<a href="https://github.com/hydephp/hyde">GitHub</a>
-
-

Excluding Items (Blacklist)

-

Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu. -To remove items from being automatically added, simply add the page's route key to the blacklist. -As you can see, the 404 page has already been filled in for you.

-
'navigation' => [
-    'exclude' => [
-        '404'
-    ]
-]
-
-

You can also specify that a page should be excluded by setting the page front matter.

-
---
-navigation:
-    hidden: true
----
-
-

Changing the menu item labels

-

Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. -You can override the label using the navigation.label front matter property.

-

From the Hyde config you can also override the label of navigation links using the by mapping the route key -to the desired title. Note that the front matter property will take precedence over the config property.

-
Filepath: config/hyde.php'navigation' => [
-    'labels' => [
-        'index' => 'Start',
-        'docs/index' => 'Documentation',
-    ]
-]
-
-

Blade Views

-

Hyde uses the Laravel Blade templating engine. Most parts of the included templates have been extracted into components to be customized easily. -Before editing the views you should familiarize yourself with the Laravel Blade Documentation.

-

To edit a default Hyde component you need to publish them first using the hyde publish:views command.

-
php hyde publish:views
-
-

The files will then be available in the resources/views/vendor/hyde directory.

-

Frontend Styles

-

Hyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template -for you to get up and running quickly. If you want to customize these, you are free to do so. -Please see the Managing Assets page to learn more.

-

Markdown Configuration

-

Hyde uses League CommonMark for converting Markdown into HTML, and -uses the GitHub Flavored Markdown extension. The Markdown related settings are found in the config/markdown.php file. -Below follows an overview of the Markdown configuration options available in Hyde.

-

CommonMark Extensions

-

You can add any extra CommonMark Extensions, -or change the default ones, using the extensions array in the config file. They will then automatically be loaded into -the CommonMark converter environment when being set up by Hyde.

-
Filepath: config/markdown.php'extensions' => [
-    \League\CommonMark\Extension\GithubFlavoredMarkdownExtension::class,
-    \League\CommonMark\Extension\Attributes\AttributesExtension::class,
-],
-
-

Remember that you may need to install any third party extensions through Composer before you can use them.

-

CommonMark Configuration

-

In the same file you can also change the configuration values to be passed to the CommonMark converter environment. -Hyde handles many of the options automatically, but you may want to override some of them and/or add your own.

-
Filepath: config/markdown.php'config' => [
-    'disallowed_raw_html' => [
-        'disallowed_tags' => [],
-    ],
-],
-
-

See the CommonMark Configuration Docs for the available options. -Any custom options will be merged with the defaults.

-

Allow Raw HTML

-

Since Hyde uses GitHub Flavored Markdown, -some HTML tags are stripped out by default. If you want to allow all arbitrary HTML tags, and understand the risks involved, -you can use the allow_html setting to enable all HTML tags.

-
Filepath: config/markdown.php'allow_html' => true,
-
-

Allow Blade Code

-

HydePHP also allows you to use Blade code in your Markdown files. This is disabled by default, since it allows -arbitrary PHP code specified in Markdown to be executed. It's easy to enable however, using the enable_blade setting.

-
Filepath: config/markdown.php'enable_blade' => true,
-
-

See the Blade in Markdown documentation for more information on how to use this feature.

-

YAML Configuration

-

The settings in the config/hyde.php file can also be set by using a hyde.yml file in the root of your project directory.

-

Note that YAML settings cannot call any PHP functions, so you can't access helpers like env() for environment variables, -nor declare authors or navigation links, as you cannot use facades and objects. But that doesn't stop you from using both -files if you want to. Just keep in mind that any duplicate settings in the YAML file override any made in the PHP file.

-

Here is an example showing some of the config/hyde.php file settings, and how they would be set in the YAML file.

-
Filepath: hyde.ymlname: HydePHP
-url: "http://localhost"
-pretty_urls: false
-generate_sitemap: true
-rss:
-  enabled: true
-  filename: feed.xml
-  description: HydePHP RSS Feed
-language: en
-output_directory: _site
-
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/directory-structure.html b/docs/docs/master/directory-structure.html index e640fa64..bf359385 100644 --- a/docs/docs/master/directory-structure.html +++ b/docs/docs/master/directory-structure.html @@ -1,364 +1,8 @@ - - -HydePHP Upcoming Documentation - Directory Structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
- -
-
- -

Redirecting you to architecture-concepts#directory-structure

- -
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/documentation-pages.html b/docs/docs/master/documentation-pages.html index e63ea9a2..be4f3927 100644 --- a/docs/docs/master/documentation-pages.html +++ b/docs/docs/master/documentation-pages.html @@ -1,734 +1,8 @@ - - -HydePHP Upcoming Documentation - Creating Documentation Pages - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Creating Documentation Pages

-
-
-

Introduction to Hyde Documentation Pages

-

Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. -Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest.

-

Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a -responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, -labels, and even groups, of the sidebar items to suit your needs.

-

Additionally, if you have a _docs/index.md file, the sidebar header will link to it, and an automatically generated -"Docs" link will be added to your site's main navigation menu, pointing to your documentation page.

-

If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, -saving you time and effort. For more information about this feature, see the extensions page.

-

Best Practices and Hyde Expectations

-

Since Hyde does a lot of things automatically, there are some things you may need -to keep in mind when creating blog posts so that you don't get unexpected results.

-

Filenames

-
    -
  • Hyde Documentation pages are files are stored in the _docs directory
    • -
  • The filename is used as the filename for the compiled HTML
    • -
  • Filenames should use kebab-case-name format, followed by the appropriate extension
    • -
  • Files prefixed with _underscores are ignored by Hyde
    • -
  • You should always have an index.md file in the _docs/ directory
    • -
  • Your page will be stored in _site/docs/<identifier>.html unless you change it in the config -
    • -
-

Advanced usage and customization

-

Like most of HydePHP, the Hyde Documentation module is highly customizable. Much of the frontend is composed using Blade templates and components, which you can customize to your heart's content. -Since there are so many components, it's hard to list them all here in the documentation, so I encourage you to check out the source code to see how it's all put together and find the customizations you are looking for.

-

Creating Documentation Pages

-

You can create a Documentation page by adding a file to the _docs directory where the filename ends in .md.

-

You can also scaffold one quickly by using the HydeCLI.

-
php hyde make:page "Page Title" --type="docs"
-
-

This will create the following file saved as _docs/page-title.md

-
# Page Title
-
-

Front Matter is optional

-

You don't need to use front matter to create a documentation page.

-

However, Hyde still supports front matter here as it allows you to quickly override the default values.

-

Here is a quick reference, however, you should take a look at the dynamic content section to learn more.

-
---
-title: "Page Title"
-navigation:
-    label: "Sidebar Label"
-    hidden: true
-    priority: 5
----
-
-

Dynamic content generation

-

Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. -If you are not happy with the results you can customize them in the config or with front matter.

-

Front Matter reference

-

Before we look at how to override things, here is an overview of the relevant content Hyde generates, -and where the data is from as well as where it can be overridden.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropertyDescriptionDynamic Data SourceOverride in
title (string)The title of the page used in the HTML <title> tagThe first H1 heading (# Foo)Front matter
navigation.label (string)The label for the page shown in the sidebarThe page basenameFront matter, config
navigation.priority (integer)The priority of the page used for ordering the sidebarDefaults to 999Front matter, config
navigation.hidden (boolean)Hides the page from the sidebarnoneFront matter, config
navigation.group (string)The group the page belongs to in the sidebarSubdirectory, if nestedFront matter
-

Sidebar

-

The sidebar is automatically generated from the files in the _docs directory. You will probably want to change the order -of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings.

-

Table of contents

-

Hyde automatically generates a table of contents for the page and adds it to the sidebar.

-

The behaviour of this can be changed in the configuration file. -See the customization page for more details.

-

Sidebar ordering

-

The sidebar is sorted/ordered by the priority property. The higher the priority the further down in the sidebar it will be. -The default priority is 999. You can override the priority using the following front matter:

-
navigation:
-    priority: 5
-
-

You can also change the order in the Docs configuration file. -See the chapter in the customization page for more details.
-I personally think the config route is easier as it gives an instant overview, however the first way is nice as well.

-

Sidebar labels

-

The sidebar items are labeled with the label property. The default label is the filename of the file. -You can change it with the following front matter:

-
navigation:
-    label: "My Custom Sidebar Label"
-
-

Sidebar grouping

-

Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. -The Hyde docs for instance use this.

-

The feature is enabled automatically when one or more of your documentation pages have the navigation.group property set -in the front matter. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. -Any pages without the group front matter will get put in the "Other" group.

-

Using Front Matter

-

To enable sidebar grouping, you can add the following front matter to your documentation pages:

-
navigation:
-    group: "Getting Started"
-
-

Automatic subdirectory-based grouping

-

You can also automatically group your documentation pages by placing source files in sub-directories.

-

For example, putting a Markdown file in _docs/getting-started/, is equivalent to adding the same front matter seen above.

-

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.

-

Hiding items

-

You can hide items from the sidebar by adding the hidden property to the front matter:

-
navigation:
-    hidden: true
-
-

This can be useful to create redirects or other items that should not be shown in the sidebar.

-

The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header.

-

Customization

-

Please see the customization page for in-depth information on how to customize Hyde, -including the documentation pages. Here is a high level overview for quick reference though.

-

Output directory

-

If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, -for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. -The path is relative to the site output, typically _site.

-
Filepath: config/hyde.php'output_directories' => [
-    \Hyde\Pages\DocumentationPage::class => 'docs' // default [tl! --]
-    \Hyde\Pages\DocumentationPage::class => 'docs/1.x' // What the Hyde docs use [tl! ++]
-]
-
-

Note that you need to take care as to not set it to something that may conflict with other parts, such as media or posts directories.

-

Automatic navigation menu

-

By default, a link to the documentation page is added to the navigation menu when an index.md file is found in the _docs directory. Please see the customization page for more information.

-

Sidebar header name

-

By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". -You can change this in the Docs configuration file.

-
'title' => 'API Documentation',
-
-

Tip: The header will link to the docs/index page, if it exists.

-

Sidebar page order

-

To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. -Link items without an entry here will have fall back to the default priority of 999, putting them last.

-
'sidebar_order' => [
-    'readme',
-    'installation',
-    'getting-started',
-]
-
-

See the chapter in the customization page for more details.

-

Table of contents settings

-

In the config/docs.php file you can configure the behavior, content, and the look and feel of the sidebar table of contents. -You can also disable the feature completely.

-
'table_of_contents' => [
-    'enabled' => true,
-    'min_heading_level' => 2,
-    'max_heading_level' => 4,
-    'smooth_page_scrolling' => true,
-],
-
-

Using flattened output paths

-

If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. -This means that you can use the automatic directory based grouping feature, but still have a "flat" output structure. -Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other.

-

If you set this to false, Hyde will match the directory structure of the source files (just like all other pages).

-
Filepath: config/docs.php'flattened_output_paths' => true,
-
-

Search feature

-

Introduction

-

The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator -that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget.

-

Tip: The HydeSearch plugin is what powers the search feature on this site! Why not try it out!

-

The search feature is enabled by default. You can disable it by removing the documentationSearch from the Hyde Features config array.

-
Filepath: config/hyde.php'features' => [
-    Features::documentationSearch(), // [tl! --]
-],
-
-

Using the search

-

The search works by generating a JSON search index which the JavaScript plugin loads asynchronously.

-

Two ways to access the search are added, one is a full page search screen that will be saved to docs/search.html.

-

The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. -Opening it will open a modal with an integrated search screen. You can also open the dialog using the keyboard shortcut /.

-

The full page can be disabled by setting create_search_page to false in the docs config.

-

Hiding pages from indexing

-

If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. -You can do this by adding the page identifier to the exclude_from_search array in the docs config, similar to how -navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file.

-
Filepath: config/docs.php'exclude_from_search' => [
-  'changelog',
-]
-
-

Search with realtime compiler

-

While the Realtime Compiler (what powers the php hyde serve command) serves the search index, however, it does not -compile the index automatically. So if you're missing the search when previewing your site, run either php hyde build -or php hyde build:search to compile the search index.

-

Automatic "Edit Page" button

-

Introduction

-

Hyde can automatically add links to documentation pages that takes the user -to a GitHub page (or similar) to edit the page. This makes it great for open-source projects -looking to allow others to contribute to the documentation in a quick and easy manner.

-

The feature is automatically enabled when you specify a base URL in the Docs configuration file. -Hyde expects this to be a GitHub path, but it will probably work with other methods as well, -if not, please send a PR and/or create an issue on the GitHub repository!

-

Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out!

-

Configuration

-

As an example configuration, let's take a practical example for how HydePHP.com uses this feature.

-
Filepath: config/docs.php'source_file_location_base' => 'https://github.com/hydephp/docs/blob/master/',
-
-

Changing the button text

-

Changing the label is easy, just change the following config setting:

-
Filepath: config/docs.php'edit_source_link_text' => 'Edit Source on GitHub',
-
-

Changing the position

-

By default, the button will be shown in both the documentation page footer. -You can change this by setting the following config setting to 'header', 'footer', or 'both'

-
Filepath: config/docs.php'edit_source_link_position' => 'header',
-
-

Adding a button icon

-

This is not included out of the box, but is easy to add with some CSS! -Just target the .edit-page-link class.

-
Filepath: e.g. app.css.edit-page-link::before {content: "✏ "}
-
-

Changing the Blade view

-

You can also publish the edit-source-button.blade.php view and change it to your liking.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/dynamic-data-discovery.html b/docs/docs/master/dynamic-data-discovery.html index 0372f8f6..0ddbf38c 100644 --- a/docs/docs/master/dynamic-data-discovery.html +++ b/docs/docs/master/dynamic-data-discovery.html @@ -1,454 +1,8 @@ - - -HydePHP Upcoming Documentation - Dynamic Data Discovery - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Dynamic Data Discovery

-
-
-

AKA: Front Matter & Filling in the Gaps

-

Introduction

-

Hyde wants to allow developers to write less, and do more. This is also a major difference between HydePHP and JekyllRB. -Jekyll will only do what you tell it to do. Hyde, on the other hand, will try to do what you want it to do.

-

As with all other chapters in this category, you don't need to know about this to use Hyde -- that's the whole point! -However, 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.

-

Hyde makes great use of front matter in both Markdown and Blade files (it's true!). However, it can quickly get tedious -and quite frankly plain boring to have to write a bunch of front matter all the time. As Hyde wants you to focus on -your content, and not your markup, front matter is optional and Hyde will try to fill in the gaps for you.

-

If you're not happy with Hyde's generated data you can always override it by adding front matter to your files.

-

How it Works

-

Now, to the fun part: getting into the nitty-gritty details of how Hyde does this!

-

To make things simple the dynamic data is created in a special stage where the page object is being created. -If you have not yet read the page models chapter you might want to do so now. -You might also want to read about the autodiscovery lifecycle for some context as to when this happens.

-

The factory pipeline, in short

-

After basic information about the page has been gathered, such as the source file information and the front matter, -the page model is run through a series of factories. These are just classes that work around the limited data -that is available at this point, and will assign the rich data needed to make your Hyde page awesome.

-

There are a few factory classes. The one we will be looking at here is the HydePageDataFactory class, which is -responsible for data applicable to all page models. Complex structures and data only relevant to some page types -have their own factories, making the code more modular and maintainable.

-

In-depth overview of a page factory

-

Let'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, -this discovery is done in the HydePageDataFactory class.

-

Factory data input

-

The factory gets one input, a CoreDataObject class. Think of this like a DTO (Data Transfer Object) that holds -immutable data known from the start of the page construction process. It also has all the information needed -to identify the page and its source file. Here's a simplified version of the class:

-
class CoreDataObject
-{
-    public readonly FrontMatter $matter;
-    public readonly Markdown|false $markdown;
-
-    public readonly string $pageClass;
-    public readonly string $identifier;
-    public readonly string $sourcePath;
-    public readonly string $outputPath;
-    public readonly string $routeKey;
-}
-
-

Processing the known data

-

Now 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.

-
private function findTitleForPage(): string
-{
-    return $this->matter('title')
-        ?? $this->findTitleFromMarkdownHeadings()
-        ?? Hyde::makeTitle(basename($this->identifier));
-}
-
-

As you can see, we are using the null coalescing operator (??) to return the first non-null value. We always want the -user to be able to set any data explicitly, so we first check the front matter in all factory methods.

-

If 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. -If that fails, the last step will generate a title from the file name. This ensures that no matter what, we always have a title.

-

Injecting the data into the page

-

Once the data has been discovered, it is injected into the page object. This is rather unglamorous but is mentioned -here for completeness. It's pretty simple. The factory will always return an array of the computed data, where the keys -always match the property names on the page object, so we just need to loop over the array and set the properties.

-
foreach ($data->toArray() as $key => $value) {
-    $this->{$key} = $value;
-}
-
-

And that's pretty much it! Hyde will do this for all the data it can discover, all so that you can focus on your content.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/extensions.html b/docs/docs/master/extensions.html index 168d8aec..1eba2994 100644 --- a/docs/docs/master/extensions.html +++ b/docs/docs/master/extensions.html @@ -1,432 +1,8 @@ - - -HydePHP Upcoming Documentation - Extensions and Integrations - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Extensions and Integrations

-
-
-

First party extensions

-

Realtime Compiler

-

The Hyde Realtime Compiler is now included with Hyde -installations and is what powers the php hyde serve command.

- -

Integrations with third-party tools

-

Torchlight

-

Torchlight is an amazing API for syntax highlighting, and is used by this site. I cannot recommend it highly enough, -especially for documentation sites and code-heavy blogs! As such, HydePHP has built-in support for Torchlight, -which is automatically enabled once you add an API token to your .env file. Nothing else needs to be done!

-

Getting started

-

To get started you need an API token which you can get at Torchlight.dev. -It is entirely free for personal and open source projects, as seen on their pricing page.

-

When you have an API token, set it in the .env file in the root directory of your project. -Once a token is set, Hyde will automatically enable the CommonMark extension.

-
TORCHLIGHT_TOKEN=torch_<your-api-token>
-
-

Attribution and configuration

-

Note that for the free plan you need to provide an attribution link. Thankfully Hyde injects a customizable link -automatically to all pages that use Torchlight. You can of course disable and customize this in the config/torchlight.php file.

-
'attribution' => [
-    'enabled' => true,
-    'markdown' => 'Syntax highlighting by <a href="https://torchlight.dev/" rel="noopener nofollow">Torchlight.dev</a>',
-],
-
-

Don't have this file? Run php hyde vendor:publish to publish it.

-

Contribute

-

Have an idea for an extension or integration? Let me know! I'd love to hear from you.

-

Get in touch on GitHub or send me a DM on Twitter.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/front-matter.html b/docs/docs/master/front-matter.html index 2133d081..30343706 100644 --- a/docs/docs/master/front-matter.html +++ b/docs/docs/master/front-matter.html @@ -1,423 +1,8 @@ - - -HydePHP Upcoming Documentation - Front Matter - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Front Matter

-
-
-

In a nutshell: Front Matter is a block of YAML containing metadata, stored at the top of a Markdown file.

-

Front 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, 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.

-

Using 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.) -While Hyde offers some support for front matter within Blade files, most of the time you use front matter, it will be in Markdown.

-

Front matter syntax

-

Here's a refresher on Yaml, and a quick reference of the syntax Hyde uses and expects:

-
---
-key: value
-string: "quoted string"
-boolean: true
-integer: 100
-array:
-  key: value
-  key: value
----
-
-

Strings don't need to be quoted, but it can help in certain edge cases, thus they are included here.

-

Front Matter in Markdown

-

All Markdown content files support Front Matter. Blog posts for example make heavy use of it.

-

The specific usage and schemas used for pages are documented in their respective documentation, however, here is a primer on the fundamentals.

-
    -
  • Front matter is stored in a block of YAML that starts and ends with a --- line.
    • -
  • The front matter should be the very first thing in the Markdown file.
    • -
  • Each key-pair value should be on its own line.
    • -
-

To use Front Matter, add Yaml to the top of your Markdown file:

-
---
-title: "My New Post"
-author:
-  name: "John Doe"
-  website: https://example.com
----
-
-## Markdown comes here
-
-Lorem ipsum dolor sit amet, etc.
-
-

Front Matter in Blade

-

HydePHP has experimental support for creating front-matter in Blade templates, called BladeMatter.

-

The actual syntax does not use YAML; but instead PHP. However, the parsed end result is the same. Please note that -BladeMatter currently does not support multidimensional arrays or multi-line directives as the data is statically parsed.

-

To create BladeMatter, you simply use the default Laravel Blade @php directive to declare a variable in the template.

-
@php($title = 'BladeMatter Demo')
-
-

It will then be available through the global $page variable, $page->matter('title').

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/getting-started.html b/docs/docs/master/getting-started.html index 2435929c..f119eb18 100644 --- a/docs/docs/master/getting-started.html +++ b/docs/docs/master/getting-started.html @@ -1,364 +1,8 @@ - - -HydePHP Upcoming Documentation - Getting Started - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
- -
-
- -

Redirecting you to quickstart

- -
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/hyde-pages.html b/docs/docs/master/hyde-pages.html index 1f3ef9be..7668b919 100644 --- a/docs/docs/master/hyde-pages.html +++ b/docs/docs/master/hyde-pages.html @@ -1,1271 +1,8 @@ - - -HydePHP Upcoming Documentation - HydePage API Reference - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

HydePage API Reference

-
-
-

This article covers advanced information, and you are expected to already be familiar with Page Models and OOP

-

Abstract

-

This page contains the full API references for the built-in HydePage classes. Most users will not need to know about -the inner workings of classes, but if you're interested in extending HydePHP, or just curious, this page is for you. -It is especially useful if you're looking to implement your own page classes, or if you are creating advanced Blade templates.

-

About the reference

-

This document is heavily based around the actual source code, as I believe the best way to understand the code is to read it. -However, large parts of the code are simplified for brevity and illustration. The code is not meant to be copy-pasted, but -rather used as a reference so that you know what to look for in the actual source code, if you want to dig deeper.

-

Inheritance

-

Since all HydePages extend the base HydePage class, those shared methods are only listed once, -under the HydePage class documentation which is conveniently located just below this section.

-

Table of Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ClassDescription
HydePageThe base class for all Hyde pages.
BaseMarkdownPageThe base class for all Markdown pages.
InMemoryPageExtendable class for in-memory pages.
BladePageClass for Blade pages.
MarkdownPageClass for Markdown pages.
MarkdownPostClass for Markdown posts.
DocumentationPageClass for documentation pages.
HtmlPageClass for HTML pages.
-

HydePage

-

The base class for all Hyde pages, all other page classes extend this class.

-

Unlike other frameworks, in general you don't instantiate pages yourself in Hyde, instead, the page models acts as -blueprints defining information for Hyde to know how to parse a file, and what data around it should be generated.

-

To create a parsed file instance, you'd typically just create a source file, and you can then access the parsed file -from the HydeKernel's page index.

-

In Blade views, you can always access the current page instance being rendered using the $page variable.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
HydePageHyde\Pages\ConcernsOpen in GitHubLive API Docs
-

Base Structure

-
/**
- * The base class for all Hyde pages. Here simplified for the sake of brevity.
- */
-abstract class HydePage
-{
-    /**
-     * The directory in which source files are stored. Relative to the project root.
-     */
-    public static string $sourceDirectory;
-
-    /**
-     * The output subdirectory to store compiled HTML. Relative to the _site output directory.
-     */
-    public static string $outputDirectory;
-
-    /**
-     * The file extension of the source files.
-     */
-    public static string $fileExtension;
-
-    /**
-     * The default template to use for rendering the page.
-     */
-    public static string $template;
-
-    /**
-     * The page instance identifier.
-     */
-    public readonly string $identifier;
-
-    /**
-     * The page instance route key.
-     */
-    public readonly string $routeKey;
-
-    /**
-     * The parsed front matter.
-     */
-    public FrontMatter $matter;
-
-    /**
-     * The generated page metadata.
-     */
-    public PageMetadataBag $metadata;
-
-    /**
-     * The generated page navigation data.
-     */
-    public NavigationData $navigation;
-}
-
-

Methods

-

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.

-
- - -

make()

-

Create a new page instance. Static alias for the constructor.

-
// torchlight! {"lineNumbers": false}
-HydePage::make(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter): static
-
-

isDiscoverable()

-

Returns whether the page type is discoverable through auto-discovery.

-
// torchlight! {"lineNumbers": false}
-HydePage::isDiscoverable(): bool
-
-

get()

-

Get a page instance from the Kernel's page index by its identifier.

-
// torchlight! {"lineNumbers": false}
-HydePage::get(string $identifier): Hyde\Pages\Concerns\HydePage
-
-
    -
  • -Throws: \Hyde\Framework\Exceptions\FileNotFoundException If the page does not exist.
    • -
-

parse()

-

Parse a source file into a new page model instance.

-
// torchlight! {"lineNumbers": false}
-/** @param string $identifier The identifier of the page to parse. */
-HydePage::parse(string $identifier): static // New page model instance for the parsed source file.
-
-
    -
  • -Throws: \Hyde\Framework\Exceptions\FileNotFoundException If the file does not exist.
    • -
-

files()

-

Get an array of all the source file identifiers for the model.

-

Note that the values do not include the source directory or file extension.

-
// torchlight! {"lineNumbers": false}
-HydePage::files(): array<string>
-
-

all()

-

Get a collection of all pages, parsed into page models.

-
// torchlight! {"lineNumbers": false}
-HydePage::all(): \Hyde\Foundation\Kernel\PageCollection<static>
-
-

sourceDirectory()

-

Get the directory where source files are stored for the page type.

-
// torchlight! {"lineNumbers": false}
-HydePage::sourceDirectory(): string
-
-

outputDirectory()

-

Get the output subdirectory to store compiled HTML files for the page type.

-
// torchlight! {"lineNumbers": false}
-HydePage::outputDirectory(): string
-
-

fileExtension()

-

Get the file extension of the source files for the page type.

-
// torchlight! {"lineNumbers": false}
-HydePage::fileExtension(): string
-
-

setSourceDirectory()

-

Set the output directory for the page type.

-
// torchlight! {"lineNumbers": false}
-HydePage::setSourceDirectory(string $sourceDirectory): void
-
-

setOutputDirectory()

-

Set the source directory for the page type.

-
// torchlight! {"lineNumbers": false}
-HydePage::setOutputDirectory(string $outputDirectory): void
-
-

setFileExtension()

-

Set the file extension for the page type.

-
// torchlight! {"lineNumbers": false}
-HydePage::setFileExtension(string $fileExtension): void
-
-

sourcePath()

-

Qualify a page identifier into file path to the source file, relative to the project root.

-
// torchlight! {"lineNumbers": false}
-HydePage::sourcePath(string $identifier): string
-
-

outputPath()

-

Qualify a page identifier into a target output file path, relative to the _site output directory.

-
// torchlight! {"lineNumbers": false}
-HydePage::outputPath(string $identifier): string
-
-

path()

-

Get an absolute file path to the page's source directory, or a file within it.

-
// torchlight! {"lineNumbers": false}
-HydePage::path(string $path): string
-
-

pathToIdentifier()

-

Format a filename to an identifier for a given model. Unlike the basename function, any nested paths within the source directory are retained in order to satisfy the page identifier definition.

-
// torchlight! {"lineNumbers": false}
-/** @param string $path Example: index.blade.php */
-HydePage::pathToIdentifier(string $path): string // Example: index
-
-

baseRouteKey()

-

Get the route key base for the page model.

-

This is the same value as the output directory.

-
// torchlight! {"lineNumbers": false}
-HydePage::baseRouteKey(): string
-
-

__construct()

-

Construct a new page instance.

-
// torchlight! {"lineNumbers": false}
-$page = new HydePage(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter): void
-
-

compile()

-

Compile the page into static HTML.

-
// torchlight! {"lineNumbers": false}
-$page->compile(): string // The compiled HTML for the page.
-
-

toArray()

-

Get the instance as an array.

-
// torchlight! {"lineNumbers": false}
-$page->toArray(): array
-
-

getSourcePath()

-

Get the path to the instance source file, relative to the project root.

-
// torchlight! {"lineNumbers": false}
-$page->getSourcePath(): string
-
-

getOutputPath()

-

Get the path where the compiled page will be saved.

-
// torchlight! {"lineNumbers": false}
-$page->getOutputPath(): string // Path relative to the site output directory.
-
-

getRouteKey()

-

Get the route key for the page.

-

The route key is the page URL path, relative to the site root, but without any file extensions. For example, if the page will be saved to _site/docs/index.html, the key is docs/index.

-

Route keys are used to identify page routes, similar to how named routes work in Laravel, only that here the name is not just arbitrary, but also defines the output location, as the route key is used to determine the output path which is $routeKey.html.

-
// torchlight! {"lineNumbers": false}
-$page->getRouteKey(): string
-
-

getRoute()

-

Get the route object for the page.

-
// torchlight! {"lineNumbers": false}
-$page->getRoute(): Hyde\Support\Models\Route
-
-

getLink()

-

Format the page instance to a URL path, with support for pretty URLs if enabled.

-

Note that the link is always relative to site root, and does not contain ../ segments.

-
// torchlight! {"lineNumbers": false}
-$page->getLink(): string
-
-

getIdentifier()

-

Get the page model's identifier property.

-

The identifier is the part between the source directory and the file extension. It may also be known as a 'slug', or previously 'basename', but it retains the nested path structure if the page is stored in a subdirectory.

-

For example, the identifier of a source file stored as '_pages/about/contact.md' would be 'about/contact', and 'pages/about.md' would simply be 'about'.

-
// torchlight! {"lineNumbers": false}
-$page->getIdentifier(): string
-
-

getBladeView()

-

Get the Blade template/view key for the page.

-
// torchlight! {"lineNumbers": false}
-$page->getBladeView(): string
-
-

title()

-

Get the page title to display in HTML tags like <title> and <meta> tags.

-
// torchlight! {"lineNumbers": false}
-$page->title(): string
-
-

metadata()

-

Get the generated metadata for the page.

-
// torchlight! {"lineNumbers": false}
-$page->metadata(): Hyde\Framework\Features\Metadata\PageMetadataBag
-
-

showInNavigation()

-

Can the page be shown in the navigation menu?

-
// torchlight! {"lineNumbers": false}
-$page->showInNavigation(): bool
-
-

navigationMenuPriority()

-

Get the priority of the page in the navigation menu.

-
// torchlight! {"lineNumbers": false}
-$page->navigationMenuPriority(): int
-
-

navigationMenuLabel()

-

Get the label of the page in the navigation menu.

-
// torchlight! {"lineNumbers": false}
-$page->navigationMenuLabel(): string
-
-

navigationMenuGroup()

-

Get the group of the page in the navigation menu, if any.

-
// torchlight! {"lineNumbers": false}
-$page->navigationMenuGroup(): string
-
- -
- -
- - -

data()

-

Get a value from the computed page data, or fallback to the page's front matter, then to the default value.

-
// torchlight! {"lineNumbers": false}
-$page->data(string $key, mixed $default): \Hyde\Markdown\Models\FrontMatter|mixed
-
-

matter()

-

Get the front matter object, or a value from within.

-
// torchlight! {"lineNumbers": false}
-$page->matter(string $key, mixed $default): \Hyde\Markdown\Models\FrontMatter|mixed
-
-

has()

-

See if a value exists in the computed page data or the front matter.

-
// torchlight! {"lineNumbers": false}
-$page->has(string $key): bool
-
- -
- -

BaseMarkdownPage

-

The base class for all Markdown-based page models, with additional helpers tailored for Markdown pages.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
BaseMarkdownPageHyde\Pages\ConcernsOpen in GitHubLive API Docs
-

Base Structure

-
/**
- * The base class for all Markdown-based page models. Here simplified for the sake of brevity.
- */
-abstract class BaseMarkdownPage extends HydePage
-{
-    public Markdown $markdown;
-
-    public static string $fileExtension = '.md';
-}
-
-

Methods

-
- - -

make()

-

Create a new page instance. Static alias for the constructor.

-
// torchlight! {"lineNumbers": false}
-BaseMarkdownPage::make(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter, Hyde\Markdown\Models\Markdown|string $markdown): static
-
-

__construct()

-

Construct a new page instance.

-
// torchlight! {"lineNumbers": false}
-$page = new BaseMarkdownPage(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter, Hyde\Markdown\Models\Markdown|string $markdown): void
-
-

markdown()

-

Return the document's Markdown object.

-
// torchlight! {"lineNumbers": false}
-$page->markdown(): Hyde\Markdown\Models\Markdown
-
-

compile()

-

Compile the page into static HTML.

-
// torchlight! {"lineNumbers": false}
-$page->compile(): string // The compiled HTML for the page.
-
-

save()

-

Save the Markdown page object to disk by compiling the front matter array to YAML and writing the body to the file.

-
// torchlight! {"lineNumbers": false}
-$page->save(): $this
-
- -
- -

InMemoryPage

-

Before 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.

-

This class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize Hyde -autodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.

-

You can learn more about the InMemoryPage class in the InMemoryPage documentation.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
InMemoryPageHyde\PagesOpen in GitHubLive API Docs
-

Base Structure

-

As the class is not discoverable, the static path properties are not initialized. Instead, you solely rely on the contents/view properties.

-

You 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.

-
/**
- * The InMemoryPage class, here simplified for the sake of brevity.
- */
-class InMemoryPage extends HydePage
-{
-    public static string $sourceDirectory;
-    public static string $outputDirectory;
-    public static string $fileExtension;
-
-    protected string $contents;
-    protected string $view;
-
-    /** @var array<string, callable> */
-    protected array $macros = [];
-}
-
-

Methods

-
- - -

make()

-

Static alias for the constructor.

-
// torchlight! {"lineNumbers": false}
-InMemoryPage::make(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter, string $contents, string $view): static
-
-

__construct()

-

Create a new in-memory/virtual page instance.

-

The in-memory page class offers two content options. You can either pass a string to the $contents parameter, Hyde will then save that literally as the page's contents. Alternatively, you can pass a view name to the $view parameter, and Hyde will use that view to render the page contents with the supplied front matter during the static site build process.

-

Note that $contents take precedence over $view, so if you pass both, only $contents will be used. You can also register a macro with the name 'compile' to overload the default compile method.

-

If the identifier for an in-memory page is "foo/bar" the page will be saved to "_site/foo/bar.html". You can then also use the route helper to get a link to it by using the route key "foo/bar". Take note that the identifier must be unique to prevent overwriting other pages. all this data will be passed to the view rendering engine.

-
    -
  • -Parameter $view: The view key or Blade file for the view to use to render the page contents.
    • -
  • -Parameter $matter: The front matter of the page. When using the Blade view rendering option,
    • -
-
// torchlight! {"lineNumbers": false}
-$page = new InMemoryPage(string $identifier, \Hyde\Markdown\Models\FrontMatter|array $matter, string $contents, string $view): void
-
-

getContents()

-

Get the contents of the page. This will be saved as-is to the output file when this strategy is used.

-
// torchlight! {"lineNumbers": false}
-$page->getContents(): string
-
-

getBladeView()

-

Get the view key or Blade file for the view to use to render the page contents when this strategy is used.

-
// torchlight! {"lineNumbers": false}
-$page->getBladeView(): string
-
-

compile()

-

Get the contents that will be saved to disk for this page.

-

In order to make your virtual page easy to use we provide a few options for how the page can be compiled. If you want even more control, you can register a macro with the name 'compile' to overload the method, or simply extend the class and override the method yourself, either in a standard or anonymous class.

-
// torchlight! {"lineNumbers": false}
-$page->compile(): string
-
-

macro()

-

Register a macro for the instance.

-

Unlike most macros you might be used to, these are not static, meaning they belong to the instance. If you have the need for a macro to be used for multiple pages, you should create a custom page class instead.

-
// torchlight! {"lineNumbers": false}
-$page->macro(string $name, callable $macro): void
-
-

hasMacro()

-

Determine if a macro with the given name is registered for the instance.

-
// torchlight! {"lineNumbers": false}
-$page->hasMacro(string $method): bool
-
-

__call()

-

Dynamically handle macro calls to the class.

-
// torchlight! {"lineNumbers": false}
-$page->__call(string $method, array $parameters): mixed
-
- -
- -

BladePage

-

Page class for Blade pages.

-

Blade pages are stored in the _pages directory and using the .blade.php extension. -They will be compiled using the Laravel Blade engine the _site/ directory.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
BladePageHyde\PagesOpen in GitHubLive API Docs
-

Base Structure

-
class BladePage extends HydePage
-{
-    public static string $sourceDirectory = '_pages';
-    public static string $outputDirectory = '';
-    public static string $fileExtension = '.blade.php';
-}
-
-

Methods

-
- - -

__construct()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-/** @param string $identifier The identifier, which also serves as the view key. */
-$page = new BladePage(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter): void
-
-

getBladeView()

-

Get the Blade template/view key for the page.

-
// torchlight! {"lineNumbers": false}
-$page->getBladeView(): string
-
-

compile()

-

Compile the page into static HTML.

-
// torchlight! {"lineNumbers": false}
-$page->compile(): string // The compiled HTML for the page.
-
- -
- -

MarkdownPage

-

Page class for Markdown pages.

-

Markdown pages are stored in the _pages directory and using the .md extension. -The Markdown will be compiled to HTML using a minimalistic layout to the _site/ directory.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
MarkdownPageHyde\PagesOpen in GitHubLive API Docs
-

Base Structure

-
class MarkdownPage extends BaseMarkdownPage
-{
-    public static string $sourceDirectory = '_pages';
-    public static string $outputDirectory = '';
-    public static string $template = 'hyde::layouts/page';
-}
-
-

Methods

-

This class does not define any additional methods.

-

MarkdownPost

-

Page class for Markdown blog posts.

-

Markdown posts are stored in the _posts directory and using the .md extension. -The Markdown will be compiled to HTML using the blog post layout to the _site/posts/ directory.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
MarkdownPostHyde\PagesOpen in GitHubLive API Docs
-

Base Structure

-
class MarkdownPost extends BaseMarkdownPage
-{
-    public static string $sourceDirectory = '_posts';
-    public static string $outputDirectory = 'posts';
-    public static string $template = 'hyde::layouts/post';
-
-    public ?string $description;
-    public ?string $category;
-    public ?DateString $date;
-    public ?PostAuthor $author;
-    public ?FeaturedImage $image;
-}
-
-

Methods

-
- - -

getLatestPosts()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-MarkdownPost::getLatestPosts(): \Hyde\Foundation\Kernel\PageCollection<\Hyde\Pages\MarkdownPost>
-
-

toArray()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-$page->toArray(): array
-
- -
- -

DocumentationPage

-

Page class for documentation pages.

-

Documentation pages are stored in the _docs directory and using the .md extension. -The Markdown will be compiled to HTML using the documentation page layout to the _site/docs/ directory.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
DocumentationPageHyde\PagesOpen in GitHubLive API Docs
-

Base Structure

-
class DocumentationPage extends BaseMarkdownPage
-{
-    public static string $sourceDirectory = '_docs';
-    public static string $outputDirectory = 'docs';
-    public static string $template = 'hyde::layouts/docs';
-}
-
-

Methods

-
- - -

home()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-DocumentationPage::home(): Hyde\Support\Models\Route
-
-

homeRouteName()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-DocumentationPage::homeRouteName(): string
-
-

hasTableOfContents()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-DocumentationPage::hasTableOfContents(): bool
-
-

getOnlineSourcePath()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-$page->getOnlineSourcePath(): string|false
-
-

getTableOfContents()

-

Generate Table of Contents as HTML from a Markdown document body.

-
// torchlight! {"lineNumbers": false}
-$page->getTableOfContents(): string
-
-

getRouteKey()

-

Get the route key for the page.

-

If flattened outputs are enabled, this will use the identifier basename so nested pages are flattened.

-
// torchlight! {"lineNumbers": false}
-$page->getRouteKey(): string
-
-

getOutputPath()

-

Get the path where the compiled page will be saved.

-

If flattened outputs are enabled, this will use the identifier basename so nested pages are flattened.

-
// torchlight! {"lineNumbers": false}
-$page->getOutputPath(): string
-
- -
- -

HtmlPage

-

Page class for HTML pages.

-

Html pages are stored in the _pages directory and using the .html extension. -These pages will be copied exactly as they are to the _site/ directory.

-

Quick Reference

- - - - - - - - - - - - - - - - - -
Class NameNamespaceSource CodeAPI Docs
HtmlPageHyde\PagesOpen in GitHubLive API Docs
-

Base Structure

-
class HtmlPage extends HydePage
-{
-    public static string $sourceDirectory = '_pages';
-    public static string $outputDirectory = '';
-    public static string $fileExtension = '.html';
-}
-
-

Methods

-
- - -

contents()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-$page->contents(): string
-
-

compile()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-$page->compile(): string
-
-

getBladeView()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-$page->getBladeView(): string
-
- -
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/in-memory-pages.html b/docs/docs/master/in-memory-pages.html index 7c5df43d..5b41ae62 100644 --- a/docs/docs/master/in-memory-pages.html +++ b/docs/docs/master/in-memory-pages.html @@ -1,410 +1,8 @@ - - -HydePHP Upcoming Documentation - InMemoryPages - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

InMemoryPages

-
-
-

Introduction

-

This class is a special page class that is not backed by a file on disk, but rather generated at runtime. While it will -probably not be useful for the majority of users, it's a great class to know about if you are a package developer, -but feel free to skip this section if you're not interested in this.

-

When to use

-

This class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize Hyde -autodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.

-

About discovery

-

Since the InMemoryPages are not present in the filesystem, they cannot be found by the auto-discovery process, -thus it's up to the developer to manually register them. If you are developing for your own project, you can do this in -the boot method of a service provider, such as the AppServiceProvider which is already present in your app/ directory.

-

If you are developing a package, you may instead want to register the page in your package extension class, within the -page collection callback. In either case, if you want your page to be able to be fully processed by Hyde, you need to -make sure you register it before the full application is booted so that routes can be generated.

-

To see how to register the page, see the examples below, first we must look at how to actually create the page.

-

Creating the page

-

To create an InMemoryPage, you need to instantiate it, and pass it the required parameters.

-

A page would not be useful without any content to render. The class offers two content options through the constructor.

-

You can either pass a string to the $contents parameter, Hyde will then save that literally as the page's contents.

-
$page = new InMemoryPage(contents: 'Hello World!');
-
-

Alternatively, you can pass a Blade view name to the $view parameter, and Hyde will use that view to render the page -contents with the supplied front matter during the static site build process.

-

Note that $contents take precedence over $view, so if you pass both, only $contents will be used.

-

You can also register a macro with the name compile to overload the default compile method.

-

API Reference

-

To see all the methods available, please see the InMemoryPage API reference.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/index.html b/docs/docs/master/index.html index d21e8d25..7e14410c 100644 --- a/docs/docs/master/index.html +++ b/docs/docs/master/index.html @@ -1,402 +1,8 @@ - - -HydePHP Upcoming Documentation - Elegant and Powerful Static Site Generator - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Elegant and Powerful Static Site Generator

-
-
- -

Latest Version on Packagist -Total Downloads on Packagist -Test Coverage -Scrutinizer Code Quality -Psalm Type Coverage -License MIT

-

About HydePHP

-

HydePHP is a new Static Site Builder focused on writing content, not markup. With Hyde, it is easy to create static -websites, blogs, and documentation pages using Markdown and (optionally) Laravel's Blade.

-

Operated entirely through the command-line, HydePHP provides developers with a fast and efficient way to create high-quality websites with ease. -Unlike traditional web development frameworks, sites compiled with HydePHP don't require any server to run, -making it an ideal choice for building lightweight and fast-loading websites.

-

Compared with other static site builders, Hyde is blazingly fast and seriously simple to get started with, yet it has the -full power of Laravel waiting for you when you need it, as Hyde is powered by Laravel Zero, a stripped-down version of -the robust and popular Laravel Framework, optimized for console applications.

-

Hyde makes creating websites easy and fun by taking care of the boring stuff, like routing, writing boilerplate, and -endless configuration. Instead, when you create a new Hyde project, everything you need to get started is already there --- including precompiled TailwindCSS, well-crafted Blade templates, and easy-to-use asset management.

-

Hyde was inspired by JekyllRB and is designed for developers who are comfortable writing posts in Markdown, and it requires -virtually no configuration out of the box as it favours convention over configuration and is preconfigured with sensible defaults.

-

Installation

-

HydePHP is a command-line interface (CLI) application that is installed on a per-project basis.

-

To use HydePHP, your system must have PHP version 8.1 or later installed, along with Composer, and access to a terminal.

-

The recommended method of installation is using Composer.

-
composer create-project hyde/hyde
-
-

Once installed, you can access the HydeCLI from the project root using the hyde command.

-
php hyde info
-
-

Usage

-

Creating static websites with HydePHP is incredibly easy. First you need some content. You can just drop Markdown files -in any of the source directories, or let Hyde scaffold the files for you using one of the many commands.

-
php hyde make:post "My First Post"
-php hyde make:page "About Me"
-
-

Once you have some content, you can run the build command to compile the content into beautiful static HTML.

-
php hyde build
-
-

And that's it, your amazing website is ready to be shared with the world!

-

To learn more, head over to the quickstart page.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/installation.html b/docs/docs/master/installation.html index 9a91ecc7..61b70888 100644 --- a/docs/docs/master/installation.html +++ b/docs/docs/master/installation.html @@ -1,364 +1,8 @@ - - -HydePHP Upcoming Documentation - Installation - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
- -
-
- -

Redirecting you to quickstart

- -
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/managing-assets.html b/docs/docs/master/managing-assets.html index 6ffd8fb1..627827b7 100644 --- a/docs/docs/master/managing-assets.html +++ b/docs/docs/master/managing-assets.html @@ -1,528 +1,8 @@ - - -HydePHP Upcoming Documentation - Managing and Compiling Assets - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Managing and Compiling Assets

-
-
-

Introduction

-

Managing and compiling assets is a very common task in web development. Unfortunately, it's rarely fun.

-

With hyde, you don't have to do it, in fact, you can skip this entire page if you are happy with how it is. -But as always with Hyde, you can customize everything if you want to.

-

Hyde ships with a complete frontend using Blade views, TailwindCSS styles, and Alpine.js interactions. -Some extra custom styles are made in the HydeFront package, which is pre-installed and bundled in the pre-configured Laravel Mix.

-

To get you started quickly, all the styles are already compiled minified into _media/app.css, which will be copied -to the _site/media/app.css directory when you run php hyde build.

-

Additional Information and Answers to Common Questions

-

Is NodeJS/NPM Required for Using Hyde?

-

No, 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.

-

When Should Assets be Compiled?

-

The _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. -If you want to customize the Tailwind settings or add custom styles, you will need to recompile the styles yourself.

-

For 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. -If you use Markdown-based pages, you do not need to compile anything as those styles are already included in the compiled CSS file.

-

How are assets stored and managed?

-

The frontend assets are separated into three places.

-
    -
  • -

    The resources/assets contains source files, meaning files that will be compiled into something else. -Here you will find the app.css file that bootstraps the TailwindCSS styles. This file is also an excellent place -to add your custom styles. It is also where we import HydeFront. If you compile this file in the base install, -it will output the same file that's already included in Hyde.

    -
    • -
  • -

    The _media folder contains compiled (and usually minified) files. When Hyde compiles your static site, -all asset files here will get copied as they are into the _site/media folder.

    -
    • -
  • -

    The _site/media folder contains the files that are served to the user.

    -
    • -
-

What is the difference between _media and _site/media?

-

It may seem weird to have two folders for storing the compiled assets, but it is quite useful.

-

The _site directory is intended to be excluded from version control, while the _media folder is included in the -version control. You are of course free to modify this behavior by editing the webpack.mix.js file to change the output directory.

-

How do I compile assets?

-

First, make sure that you have installed all the NodeJS dependencies using npm install. -Then run npm run dev to compile the assets. If you want to compile the assets for production, run npm run prod. -You can also run npm run watch to watch for changes in the source files and recompile the assets automatically.

-

How does it work?

-

Hyde uses Laravel Mix (which is a wrapper for webpack) to compile the assets.

-

When running the npm run dev/prod command, the following happens:

-
    -
  1. Laravel Mix will compile the resources/assets/app.css file into _media/app.css using PostCSS with TailwindCSS and AutoPrefixer.
    2. -
  2. 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, making blend perfectly with the realtime compiler (php hyde serve).
    3. -
-

Telling Hyde where to find assets

-

Customizing the Blade templates

-

To make it really easy to customize asset loading, the styles and scripts are loaded in dedicated Blade components.

-
    -
  • Styles are loaded in hyde::layouts.styles -
    • -
  • Scripts are loaded in hyde::layouts.scripts -
    • -
-

To customize them, run the following command:

-
php hyde publish:views layouts
-
-

Then edit the files found in resources/views/vendor/hyde/layouts directory of your project.

-

You might not even need to do anything!

-

For 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.

-

Loading from CDN

-

If you want to load the same pre-compiled file included with Hyde but from a CDN, you can set load_app_styles_from_cdn 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.

-

Using the TailwindCSS Play CDN

-

Note that the Play CDN is not meant for production use, so enabling it will add a warning to the web console.

-

If you want to use the TailwindCSS Play CDN, all you need to do is -set use_play_cdn to true in the config/hyde.php file. This will in addition to loading the standard app.css file, -also add a script tag which loads the TailwindCSS Play CDN.

-

What's even better is that Hyde will also inject the contents of the included tailwind.config.js file into the script tag, -so the Play CDN styles match the ones created by Laravel Mix.

-

All in all, this allows you to tinker around with Tailwind without having to compile anything.

-

Managing images

-

As mentioned above, assets stored in the _media folder are automatically copied to the _site/media folder, -making it the recommended place to store images. You can then easily reference them in your Markdown files.

-

Referencing images

-

The recommended way to reference images are with relative paths as this offers the most compatibility, -allowing you to browse the site both locally on your filesystem and on the web when serving from a subdirectory.

-

Note: The path is relative to the compiled file in the site output

-

The path to use depends on the location of the page. Note the subtle difference in the path prefix.

-
    -
  • If you are in a Blog Post or Documentation Page, use ../media/image.png -
    • -
  • If in a Markdown Page or Blade Page, use media/image.png -
    • -
  • While not recommended, you can also use absolute paths: /media/image.png -
    • -
  • You can of course also use full URLs, for example when using a CDN.
    • -
-

Making images accessible

-

To improve accessibility, you should always add an alt text. Here is a full example for an image in a blog post:

-
![Image Alt](../media/image.png "Image Title") # Note the relative path
-
-

Setting a featured image for blog posts

-

Hyde offers great support for creating data-rich and accessible featured images for blog posts.

-

You can read more about this in the creating blog posts page.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/page-models.html b/docs/docs/master/page-models.html index 5897c032..799e28cb 100644 --- a/docs/docs/master/page-models.html +++ b/docs/docs/master/page-models.html @@ -1,472 +1,8 @@ - - -HydePHP Upcoming Documentation - Page models - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

The Hyde Page Models

-
-
-

Introduction

-

The Hyde page models are an integral part of how HydePHP creates your static site. Each page in your site is represented -by a page model. These are simply PHP classes that in addition to holding both the source content and computed data -for your pages, also house instructions to Hyde on how to parse, process, and render the pages to static HTML.

-

In this article, you'll get a high-level overview of the page models, and some code examples to give you a look inside.

-

The short version

-

Page models are classes that have two primary concerns:

-
    -
  1. They act as blueprints containing static instructions for how to parse, process, and, render pages.
    2. -
  2. Each class instance also holds the page source contents, as well as the computed data.
    3. -
-

Other key points:

-
    -
  • HydePHP, at the time of writing, comes with five different page classes, one for each supported type.
    • -
  • You don't construct page models yourself. HydePHP does it for you by the autodiscovery process.
    • -
  • Page models are just PHP classes. You can extend them, and you can implement your own.
    • -
-

The Page Model

-

To give you an idea of what a page model class looks like, here's a simplified version of the base MarkdownPost class, -Don't worry if you don't understand everything yet, we'll talk more about these parts later.

-
class MarkdownPost extends BaseMarkdownPage
-{
-    public static string $sourceDirectory = '_posts';
-    public static string $outputDirectory = 'posts';
-    public static string $fileExtension = '.md';
-    public static string $template = 'post';
-
-    public string $identifier;
-    public string $routeKey;
-    public string $title;
-
-    public FrontMatter $matter;
-    public Markdown $markdown;
-}
-
-

Note that since Hyde pages are modular through class inheritance and traits, this example has been simplified and -edited to show all the relevant parts inlined into one class.

-

Page Models as Blueprints

-

All page models have some static properties (that is, they belong to the class, not the instance) that are used as -blueprints, defining information for Hyde to know how to parse a file, and what data around it should be generated.

-

Let's again take the simplified MarkdownPost class as an example, this time only showing the static properties:

-
class MarkdownPost extends BaseMarkdownPage
-{
-    public static string $sourceDirectory = '_posts';
-    public static string $outputDirectory = 'posts';
-    public static string $fileExtension = '.md';
-    public static string $template = 'post';
-}
-
-

What each property does

-

The properties should be self-explanatory, but here's a quick rundown to give some context on how they are used, -and how the paths relate to each other. So for the class above, Hyde will thanks to this blueprint, know to:

-
    -
  • Look for files in the _posts directory, with the .md extension
    • -
  • Compile the page using the post Blade template
    • -
  • Output the compiled page to the _site/posts directory
    • -
-

Page Models as Data Containers

-

As mentioned above, each page model instance also holds the page source contents, as well as the computed data.

-

Let's again take the simplified MarkdownPost class as an example, this time only showing the instance properties:

-
class MarkdownPost extends BaseMarkdownPage
-{
-    public string $identifier;
-    public string $routeKey;
-    public string $title;
-
-    public FrontMatter $matter;
-    public Markdown $markdown;
-}
-
-

There are some more properties than shown here, for example, various metadata properties, but these are the most common -and important ones.

-

While the static data gives instructions to Hyde on how to process all pages of the type, the instance data tells Hyde -how to process a specific page. For example, the identifier property is used to uniquely identify the page, and -the routeKey property is used to generate the URL for the page.

-

The matter and markdown properties as I'm sure you can guess, hold the page's front matter and markdown content. -These can then also be processed by page factories to generate the computed data like the -title property.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/quickstart.html b/docs/docs/master/quickstart.html index 88509190..c718483a 100644 --- a/docs/docs/master/quickstart.html +++ b/docs/docs/master/quickstart.html @@ -1,457 +1,8 @@ - - -HydePHP Upcoming Documentation - Quickstart Guide - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Quickstart Guide

-
-
-

Installing HydePHP using Composer

-

The recommended method of installing Hyde is using Composer, which installs the required dependencies on a per-project basis.

-
// torchlight! {"lineNumbers": false}
-composer create-project hyde/hyde
-
-

Requirements

-

Hyde is based on Laravel 10 -which requires a minimum PHP version of 8.1. -You should also have Composer installed.

-

To use some features like compiling your own assets -you also need NodeJS and NPM.

-

Using the Hyde CLI

-

The 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.

-

Starting a development server

-

To make previewing your site a breeze you can use the realtime compiler, which builds your pages on the fly.

-
php hyde serve
-
-

Simply run the serve command, and you will be able to preview your site at http://localhost:8080.

-

Creating content

-

Directory structure

-

Creating content with Hyde is easy! Simply place source files in one of the source directories, -and Hyde will automatically discover, parse, and compile them to static HTML. -The directory and file extension of a source file will determine how HydePHP parses and compiles it. -Please see the directory structure section for more information.

-

Scaffolding files

-

You can scaffold blog post files using the php hyde make:post command which automatically creates the front matter, based on your input selections. -You can also scaffold pages with the php hyde make:page command.

-
php hyde make:post
-php hyde make:page
-
-

Compiling to static HTML

-

Now 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.

-
php hyde build
-
-

When building the site, Hyde will scan your source directories for files and compile them into static HTML using the appropriate layout depending -on what kind of page it is. You don't have to worry about routing as Hyde takes care of everything, including creating navigation menus!

-

Managing assets

-

Hyde 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.

-

Deploying your site

-

You 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.

-

You 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.

-

Further reading

-

Here's some ideas of what to read next:

- -
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/search.html b/docs/docs/master/search.html index aca35095..a5c3c7bc 100644 --- a/docs/docs/master/search.html +++ b/docs/docs/master/search.html @@ -1,375 +1,8 @@ - - -HydePHP Upcoming Documentation - Search - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-

Search the documentation site

- -
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
- -
-
- -
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/static-pages.html b/docs/docs/master/static-pages.html index e76cd141..8c3b0e67 100644 --- a/docs/docs/master/static-pages.html +++ b/docs/docs/master/static-pages.html @@ -1,554 +1,8 @@ - - -HydePHP Upcoming Documentation - Creating Static Pages - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Creating Static Pages

-
-
-

Introduction to Hyde Pages

-

Hyde offers two ways to create static pages: -Markdown pages which are perfect for simple pages that focuses heavily on the content, -and Blade pages which are perfect for more complex pages where you want full control over the HTML, -and where you may want to include other components.

-

Let's start with the basics.

-

Best Practices and Hyde Expectations

-

Since Hyde does a lot of things automatically, there are some things you may need -to keep in mind when creating blog posts so that you don't get unexpected results.

-

Filenames

-
    -
  • Hyde Pages are files are stored in the _pages directory
    • -
  • The filename is used as the filename for the compiled HTML
    • -
  • Filenames should use kebab-case-identifier format, followed by the appropriate extension
    • -
  • Files prefixed with _underscores are ignored by Hyde
    • -
  • Your page will be stored in _site/<identifier>.html -
    • -
  • Blade pages will override any Markdown pages with the same filename when compiled
    • -
-

Creating Markdown Pages

-

Markdown pages are the easiest way to create static pages. You can create a Markdown page by adding a file to the -_pages directory where the filename ends in .md. You can also use Front Matter to add page metadata.

-

Scaffolding Markdown Pages

-

Scaffolding a Markdown page is as easy as using the HydeCLI.

-
php hyde make:page "Page Title"
-
-

This will create the following file saved as _pages/page-title.md

-
---
-title: Page Title
----
-
-# Page Title
-
-// Write your content here
-
-

You can of course also create the file yourself with your text editor.

-

Front Matter is optional

-

The most common front matter used for Markdown pages is the title, which is used as the HTML <title>.

-

If you don't supply a front matter title, Hyde will attempt to find a title in the Markdown body by searching -for the first level one heading (# Page Title), and if that fails, it will generate one from the filename.

-

Navigation Front Matter

-

Furthermore, you can customize how the page appears in the navigation menu using the following front matter options. -You can set just one or all of them, as Hyde will fill in the gaps for the rest.

-
navigation:
-    label: 'string',
-    priority: 'int',
-    hidden: 'bool',
-    group: 'string',
-
-
    -
  • -label is the text that will be displayed in the navigation menu
    • -
  • -priority is the order in which the page will appear in the navigation menu (order is also supported)
    • -
  • -hidden will hide the page from the navigation menu (visible) is also supported, but obviously invert the value)
    • -
  • -group will put the page in a dropdown menu with the specified group name (category) is also supported)
    • -
-

Creating Blade Pages

-

Since Hyde is based on Laravel and uses the powerful Blade templating engine, you can use Blade pages to create more -complex pages with both standard HTML, PHP code, and the templating opportunities provided by Blade directives.

-

If you are not familiar with Blade, you may want to read the Laravel Blade docs first.

-

Scaffolding Blade Pages

-

We can scaffold Blade pages using the same CLI command as Markdown pages, however, this time we need to specify that -we want to use the blade page type, by using the --type option.

-
php hyde make:page "Page Title" --type="blade"
-
-

This will create a file saved as _pages/page-title.blade.php

-

You can of course also create the file yourself with your text editor, however, -the scaffolding command for Blade pages is arguably even more helpful than the -one for Markdown pages, as this one automatically adds the included app Layout.

-

Let's take a look at the scaffolded file. You can also copy and paste this -if you don't want to use the scaffolding command.

-
@extends('hyde::layouts.app')
-@section('content')
-@php($title = "Page Title")
-
-<main class="mx-auto max-w-7xl py-16 px-8">
-    <h1 class="text-center text-3xl font-bold">Page Title</h1>
-</main>
-
-@endsection
-
-
-

Tip: You don't have to use Blade in Blade pages. It's also perfectly fine to use plain HTML, -however you still need to use the blade.php extension so Hyde can recognize it.

-
-

When to use which?

-

Markdown pages look great and work well for simple "about" pages and the like, but with Markdown we are still pretty limited.

-

If you are comfortable with it, and have the need for it, use Blade to create more complex pages! And mix and match between them! Some page types are better suited for Markdown, and others for Blade.

-

Comparison

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MarkdownBlade
➕ Easily created and updated➕ Full control over the HTML
➕ Very fast to create simple and lightweight pages➕ Use the default app layout or create your own
➕ Suited for content heavy pages such as "about us"➕ Use Blade templates and components to keep code DRY
➖ Not as flexible as Blade pages➕ Use arbitrary PHP right in the page to create dynamic content
➕ Access to all Blade helper directives like @foreach, @if, etc.
➖ Takes longer to create as as you need to write the markup
➖ You may need to recompile your CSS if you add Tailwind classes
-

Live Demos

-

The 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.

-

A great example of a Markdown page can be found at hydephp.github.io/portfolio-demo, you can see the page source here on GitHub.

-

Bonus: Creating HTML Pages

-

If you have an already created HTML page, simply drop it into the _pages directory and Hyde will copy it over as it is -into the _site directory. Like all other Hyde pages, the page will show up in the navigation menu using a title parsed from the filename. -You won't be able to change any settings with front matter, however.

-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/the-hydekernel.html b/docs/docs/master/the-hydekernel.html index d869df42..3caf6cca 100644 --- a/docs/docs/master/the-hydekernel.html +++ b/docs/docs/master/the-hydekernel.html @@ -1,880 +1,8 @@ - - -HydePHP Upcoming Documentation - The HydeKernel - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

The HydeKernel

-
-
-

Introduction

-

In the centre, or should I say core, of HydePHP is the HydeKernel. The kernel encapsulates a HydePHP project and -provides helpful methods for interacting with it. You can think of it as the heart of HydePHP, if you're a romantic.

-

The HydeKernel is so important that you have probably used it already. The main entry point for the HydePHP -API is the Hyde facade, which calls methods on the kernel.

-
use Hyde\Hyde;
-use Hyde\Foundation\HydeKernel;
-
-Hyde::version(); // calls $HydeKernel->version()
-
-

The kernel is created very early on in the application lifecycle, in the bootstrap.php file, where it is also bound -as a singleton into the application service container.

-

Accessing the kernel

-

The HydeKernel It is stored as a singleton in this class, and is bound into the -Laravel Application Service Container, and can be accessed in a few ways.

-

Commonly, you'll use the Hyde facade, but you can also use Dependency Injection -by type-hinting the HydeKernel::class, or use the hyde() function to get the Kernel.

-

The Kernel instance is constructed in bootstrap.php, and is available globally as $hyde.

-

Here are some examples of how you can call methods on the Kernel. All methods call the same method on the same instance, so it's just a matter of preference.

-
use Hyde\Hyde;
-use Hyde\Foundation\HydeKernel;
-
-Hyde::version();
-Hyde::kernel()->version();
-HydeKernel::getInstance()->version();
-app(HydeKernel::class)->version();
-hyde()->version();
-
-

The kernel lifecycle

-

Whenever we talk about the kernel being "booted" we are talking about the kernel's role in the autodiscovery process.

-

You can read all about it in the Autodiscovery Documentation.

-

API Reference

-

Since the most common way to interact with the kernel is through the Hyde facade, we will use that for the examples. -But you could just as well chain the methods on the accessed kernel singleton instance if you wanted.

-
- - -

version()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::version(): string
-
-

__construct()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-$hyde = new HydeKernel(string $basePath): void
-
-

features()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::features(): Hyde\Facades\Features
-
-

hasFeature()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::hasFeature(string $feature): bool
-
-

toArray()

-

Get the instance as an array.

-
// torchlight! {"lineNumbers": false}
-Hyde::toArray(): array<TKey, TValue>
-
- -
-
- - -

files()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::files(): \Hyde\Foundation\Kernel\FileCollection<string, \Hyde\Support\Filesystem\ProjectFile>
-
-

pages()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::pages(): \Hyde\Foundation\Kernel\PageCollection<string, \Hyde\Pages\Concerns\HydePage>
-
-

routes()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::routes(): \Hyde\Foundation\Kernel\RouteCollection<string, \Hyde\Support\Models\Route>
-
- -
-
- - -

makeTitle()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::makeTitle(string $value): string
-
-

normalizeNewlines()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::normalizeNewlines(string $string): string
-
-

stripNewlines()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::stripNewlines(string $string): string
-
-

trimSlashes()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::trimSlashes(string $string): string
-
-

markdown()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::markdown(string $text, bool $normalizeIndentation): Illuminate\Support\HtmlString
-
- -
- -
- - -

filesystem()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::filesystem(): Hyde\Foundation\Kernel\Filesystem
-
-

path()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::path(string $path): string
-
-

vendorPath()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::vendorPath(string $path, string $package): string
-
-

mediaPath()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::mediaPath(string $path): string
-
-

sitePath()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::sitePath(string $path): string
-
-

siteMediaPath()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::siteMediaPath(string $path): string
-
-

pathToAbsolute()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::pathToAbsolute(array|string $path): array|string
-
-

pathToRelative()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::pathToRelative(string $path): string
-
- -
-
- - -

getInstance()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getInstance(): Hyde\Foundation\HydeKernel
-
-

setInstance()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::setInstance(Hyde\Foundation\HydeKernel $instance): void
-
-

getBasePath()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getBasePath(): string
-
-

setBasePath()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::setBasePath(string $basePath): void
-
-

getSourceRoot()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getSourceRoot(): string
-
-

setSourceRoot()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::setSourceRoot(string $sourceRoot): void
-
-

getOutputDirectory()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getOutputDirectory(): string
-
-

setOutputDirectory()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::setOutputDirectory(string $outputDirectory): void
-
-

getMediaDirectory()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getMediaDirectory(): string
-
-

setMediaDirectory()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::setMediaDirectory(string $mediaDirectory): void
-
-

getMediaOutputDirectory()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getMediaOutputDirectory(): string
-
- -
-
- - -

registerExtension()

-

Register a HydePHP extension within the HydeKernel.

-

Typically, 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.

-
// torchlight! {"lineNumbers": false}
-Hyde::registerExtension(class-string&lt;\Hyde\Foundation\Concerns\HydeExtension&gt; $extension): void
-
-

getExtension()

-

Get the singleton instance of the specified extension.

-
// torchlight! {"lineNumbers": false}
-Hyde::getExtension(class-string&lt;T&gt; $extension): T
-
-

hasExtension()

-

Determine if the specified extension is registered.

-
// torchlight! {"lineNumbers": false}
-Hyde::hasExtension(class-string&lt;\Hyde\Foundation\Concerns\HydeExtension&gt; $extension): bool
-
-

getExtensions()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getExtensions(): array<\Hyde\Foundation\Concerns\HydeExtension>
-
-

getRegisteredExtensions()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getRegisteredExtensions(): array<class-string<\Hyde\Foundation\Concerns\HydeExtension>>
-
-

getRegisteredPageClasses()

-

No description provided.

-
// torchlight! {"lineNumbers": false}
-Hyde::getRegisteredPageClasses(): array<class-string<\Hyde\Pages\Concerns\HydePage>>
-
- -
-
- - -

shareViewData()

-

Share data for the page being rendered.

-
// torchlight! {"lineNumbers": false}
-Hyde::shareViewData(Hyde\Pages\Concerns\HydePage $page): void
-
-

currentRouteKey()

-

Get the route key for the page being rendered.

-
// torchlight! {"lineNumbers": false}
-Hyde::currentRouteKey(): string
-
-

currentRoute()

-

Get the route for the page being rendered.

-
// torchlight! {"lineNumbers": false}
-Hyde::currentRoute(): Hyde\Support\Models\Route
-
-

currentPage()

-

Get the page being rendered.

-
// torchlight! {"lineNumbers": false}
-Hyde::currentPage(): Hyde\Pages\Concerns\HydePage
-
- -
-
- - -

isBooted()

-

Determine if the Kernel has booted.

-
// torchlight! {"lineNumbers": false}
-Hyde::isBooted(): bool
-
-

boot()

-

Boot the Hyde Kernel and run the Auto-Discovery Process.

-
// torchlight! {"lineNumbers": false}
-Hyde::boot(): void
-
-

booting()

-

Register a new boot listener.

-

Your 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.

-
// torchlight! {"lineNumbers": false}
-/** @param callable(\Hyde\Foundation\HydeKernel): void $callback */
-Hyde::booting(callable(\Hyde\Foundation\HydeKernel): void): void
-
-

booted()

-

Register a new "booted" listener.

-

Your 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.

-
// torchlight! {"lineNumbers": false}
-/** @param callable(\Hyde\Foundation\HydeKernel): void $callback */
-Hyde::booted(callable(\Hyde\Foundation\HydeKernel): void): void
-
- -
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/troubleshooting.html b/docs/docs/master/troubleshooting.html index 1e361b30..1b3ca32c 100644 --- a/docs/docs/master/troubleshooting.html +++ b/docs/docs/master/troubleshooting.html @@ -1,578 +1,8 @@ - - -HydePHP Upcoming Documentation - Troubleshooting - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Troubleshooting

-
-
-

Since Hyde has a lot of "magic" features which depend on some base assumptions, -there might be some "gotchas" you might run into. Here are some I can think of, -did you find a new one? Send a PR to update the docs!

-

Tip: You can run php hyde validate to run a series of tests to help you catch common issues.

-

General Tips

-

(In no particular order of importance)

-
    -
  1. In general, Hyde is actually pretty forgiving. While this article makes it sound like there are a lot of rules to follow, -honestly don't worry about it. Hyde will attempt to fix mistakes and make your life easier.
    2. -
  2. You don't need to set an H1 heading in blog posts. The H1 is set by Hyde based on the front matter title.
    3. -
  3. You never need front matter, though it is often useful. -For example, Hyde makes attempts to guess the title for a page depending on the content. (Headings, filenames, etc).
    4. -
-

Conventions to follow

-

File naming

-

For Hyde to be able to discover your files, you should follow the following conventions.

-

Markdown files should have the extension .md. Blade files should have the extension .blade.php.

-

Unexpected behaviour might occur if you use conflicting file names. -All the following filenames are resolved into the same destination file: -foo-bar.md, Foo-Bar.md, foo-bar.blade.php, causing only one of them to be saved.

-

Remember, files retain their base filenames when compiled to HTML.

-

Summary

-
    -
  • ✔ Do use lowercase filenames and extensions
    • -
  • ✔ Do use filenames written in kebab-case-format
    • -
  • ✔ Do use the proper file extensions
    • -
  • ❌ Don't use conflicting source file names
    • -
-

Extra Information

-

Definitions

-

We will use the following definitions to describe the behaviour of Hyde.

-

General

-
    -
  • -Hyde: The application that you are using.
    • -
  • -HydeCLI: The command-line interface for Hyde.
    • -
  • -Framework: The package containing the core codebase.
    • -
-

Path components

-
    -
  • -Identifier: The filepath without the extension, relative to the page type source directory.
    • -
  • -Route Key: The page type's output directory plus the identifier. Example: posts/hello-world -
    • -
  • -Basename: The filename without the extension. Example: hello-world -
    • -
  • -Filename: The full name of a file with the extension. Example: hello-world.md -
    • -
  • -Filepath: The full file path including extension. Example: _posts/hello-world.md -
    • -
-

You can read more about some of these in the Core Concepts article.

-

Common issues, causes, and solutions

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IssuePossible Cause / Issue ContextPossible Solution
404 error when visiting siteAre you missing an index file in the _pages directory?Add an index.md or index.blade.php to the _pages directory
Navigation menu not linking to the docsYou probably don't have an index.md file in the _docs directory.Create a _docs/index.md file
Page not discovered when compilingThe file name may be invalidEnsure you follow the correct file naming convention.
Page compiles slowlyThe Torchlight extension may cause the compile times to increase as API calls need to be made.Try disabling Torchlight
Torchlight not workingMissing Composer package, missing API token, extension disabled in the config.Reinstall Torchlight, add your token in the .env file, check config
Missing styles and/or assetsYou may have accidentally deleted the files, or you have added new Tailwind classes.Run npm run dev
Image not foundYou may be using a bad relative path.Ensure your relative paths are correct. See managing-assets.
Wrong layout usedHyde determines the layout template to use depending on the directory of the source fileEnsure your source file is in the right directory.
Invalid/no permalinks or post URIsYou may be missing or have an invalid site URLSet the site URL in the .env file
No styles in custom Blade pagesWhen using custom blade pages need to add the styles yourself. You can do this by extending the default layoutUse the app layout, or by include the Blade components directly.
Overriding Hyde views is not workingEnsure the Blade views are in the correct directory.Rerun php hyde publish:views.
Styles not updating when deploying siteIt 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
Documentation sidebar items are in the wrong orderDouble 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
Documentation table of contents is weirdThe table of contents markup is generated by the League/CommonMark extensionMake sure that your Markdown headings make sense
Issues with date in blog post front matterThe date is parsed by the PHP strtotime() function. The date may be in an invalid format, or the front matter is invalidEnsure the date is in a format that strtotime() can parse. Wrap the front matter value in quotes.
RSS feed not being generatedThe RSS feed requires that you have set a site URL in the Hyde config or the .env file. Also check that you have blog posts, and that they are enabled.Check your configuration files.
Sitemap not being generatedThe sitemap requires that you have set a site URL in the Hyde config or the .env file.Check your configuration files.
Unable to do literally anythingIf 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.
-

Extra troubleshooting information

-

Fixing a broken config

-

If your configuration is broken, you might not be able to run any commands through the HydeCLI. -To remedy this you can copy the config files from the vendor directory into the project directory. -You can do this manually, or with the following rescue command:

-
copy vendor/hyde/framework/config/hyde.php config/hyde.php
-
-
-
- -
-
-
- -
- - - - - -
- - - - - - - - diff --git a/docs/docs/master/updating-hyde.html b/docs/docs/master/updating-hyde.html index 9de6d8a9..ad7e64a0 100644 --- a/docs/docs/master/updating-hyde.html +++ b/docs/docs/master/updating-hyde.html @@ -1,454 +1,8 @@ - - -HydePHP Upcoming Documentation - Updating Hyde Projects - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + Redirecting... - - - -
-
-
-

- WARNING - You're browsing the documentation for an upcoming version of HydePHP. - The documentation and features of this release are subject to change. -

-
- -
-

Updating Hyde Projects

-
-
-

This guide will help you update your HydePHP project to the latest version.

-

Before you start

-

When updating an existing installation, first ensure that you have a backup of your project in case anything goes wrong. -The recommended way to do this is to use Git as that allows you to smoothly roll back any changes.

-

Methods

-

Which method?

-

Depending on how you installed Hyde, there are a few different ways to update it.

-

We have a few methods documented here. The Git method is recommended as it is the easiest and safest way to -update your project. If you are not using Git, you can still update your project using any of the manual methods.

-

Regardless of the method you use, make sure you follow the post-update instructions at the end.

-

Using Git

-

First, make sure you have a remote set up for the base project repository.

-
git remote add upstream https://github.com/hydephp/hyde.git
-
-

Then pull the latest release from the upstream repository.

-
git pull upstream master
-
-

After this, you should update your composer dependencies:

-
composer update
-
-

Next, follow the post-update instructions.

-

Manual Update

-

If you are not using Git, you can still update your project. This is a bit more involved, but it is still possible.

-
    -
  1. First, you will need to download the latest release archive from the releases page.
    2. -
  2. Then extract the archive, and copy the contents into your project directory.
    3. -
-

Since this may overwrite modified files, it may be safer to use the hard update method.

-

Hard Update

-

If you are having trouble updating your project, you can try a hard update. In short, this approach consists of creating -a brand new project and copying over only your source and resource files. If you do not want to use Git, this may be -the safest option as you won't be overriding any of your existing files.

-

If you have changed any other files, for example in the App directory, you will need to update those files manually as well. -The same goes if you have created any custom Blade components or have modified Hyde ones.

-

Here is an example CLI workflow, but you can do the same using a graphical file manager.

-
mv my-project my-project-old
-composer create-project hyde/hyde my-project
-
-cp -r my-old-project/_pages my-project/content/_pages
-cp -r my-old-project/_posts my-project/content/_posts
-cp -r my-old-project/_media my-project/content/_media
-cp -r my-old-project/_docs my-project/content/_docs
-cp -r my-old-project/config my-project/config
-
-

Next, follow the post-update instructions. After verifying that everything is working, you can delete the old project directory.

-

Post-update instructions

-

After updating Hyde you should update your config and resource files. This is where things can get a tiny bit dangerous -as existing files may be overwritten. If you are using Git, you can easily take care of any merge conflicts that arise.

-

First, ensure that your dependencies are up to date. If you have already done this, you can skip this step.

-
composer update
-
-

Then, update your config files. This is the hardest part, as you may need to manually copy in your own changes.

-
php hyde publish:configs
-
-

If you have published any of the included Blade components you will need to re-publish them.

-
php hyde publish:views layouts
-php hyde publish:views components
-
-

Next, recompile your assets, if you are not using the built-in assets.

-
npm install
-npm run dev/prod
-
-

Finally, you can rebuild your site.

-
php hyde build
-
-
-
- -
-
-
- -
- - - - - -
- - - - - - - -