diff --git a/_drafts/how-does-it-work.md b/_drafts/how-does-it-work.md
deleted file mode 100644
index b74453a..0000000
--- a/_drafts/how-does-it-work.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# How does it work
-
-## Hyde is installed similarly to Laravel
-Installation is easy by using composer. The installer creates a directory with all the files you need to get started, including Blade views and compiled Tailwind assets.
-
-## Creating content is easy with Markdown
-Put your Markdown or Blade content in the source directories. The directory you use will determine the Blade layout and output path that will be used.
-
-> For example, a file stored as `_posts/hello-world.md` will be compiled using the `post.blade.php` layout and saved as `_site/posts/hello-world.html`.
-
-## Compiling is initiated with the HydeCLI
-When running the build command, Hyde will take your source files and intelligently compiles them into the output directory. During this build navigation menus and sidebars will be generated automatically.
-
diff --git a/architecture-concepts.md b/architecture-concepts.md
new file mode 100644
index 0000000..6fbdabc
--- /dev/null
+++ b/architecture-concepts.md
@@ -0,0 +1,94 @@
+---
+priority: 5
+category: "Getting Started"
+---
+
+# Some key concepts in Hyde
+
+## The HydeCLI
+
+When you are not writing Markdown and Blade, most of your interactions with Hyde will be through the
+Hyde Command Line Interface (CLI).
+Since the CLI is based on the Laravel Artisan Console, so you may actually already be familiar with it.
+
+You should take a look at [the Console Commands page](console-commands.html)
+to learn more and see the available commands and their usage.
+
+```bash
+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.
+
+```
+// torchlight! {"lineNumbers": false}
+├── _docs // For documentation pages
+├── _posts // For blog posts
+├── _pages // For static Markdown and Blade pages
+├── _media // Store static assets to be copied to the build directory
+├── _site // The build directory where your compiled site will be stored
+├── config // Configuration files for Hyde and integrations
+├── resources/assets // Location for Laravel Mix source files (optional)
+└── resources/views/components // Location for Blade components (optional)
+```
+
+> Note that the `_site` directory is emptied every time you run the `hyde build` command.
+> It's intended that you keep the directory out of your VCS, for example by adding it to your .gitignore file.
+
+
+## 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.
+
+Here is an overview of the content source directories, the output directory of the compiled files,
+and the file extensions supported by each. Files starting with an `_underscore` are ignored.
+
+| Page/File Type | Source Directory | Output Directory | File Extensions |
+|----------------|------------------|------------------|---------------------|
+| Static Pages | `_pages/` | `_site/` | `.md`, `.blade.php` |
+| Blog Posts | `_posts/` | `_site/posts/` | `.md` |
+| Documentation | `_docs/` | `_site/docs/` | `.md` |
+| Media Assets | `_media/` | `_site/media/` | See full list below |
+
+<small>
+<blockquote>
+Media file types supported: `.png`, `.svg`, `.jpg`, `.jpeg`, `.gif`, `.ico`, `.css`, `.js`
+</blockquote>
+</small>
+
+## 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](customization.html) to see the endless options available!
+
+## Front Matter
+
+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.
+
+**Example:**
+```markdown
+---
+title: "My New Post"
+author:
+ name: "John Doe"
+ website: https://mrhyde.example.com
+---
+
+## Markdown comes here
+
+Lorem ipsum dolor sit amet, etc.
+```
diff --git a/blog-posts.md b/blog-posts.md
new file mode 100644
index 0000000..b4f91e3
--- /dev/null
+++ b/blog-posts.md
@@ -0,0 +1,221 @@
+---
+label: "Creating Blog Posts"
+priority: 10
+category: "Creating Content"
+---
+
+# 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 scaffold posts with automatic front matter using the HydeCLI:
+```bash
+php hyde make:post
+```
+Learn more about scaffolding posts, and other files, in the [console commands](console-commands.html) documentation.
+
+
+## Short Video Tutorial
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/gjpE1U527h8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+## 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-slug` followed by the extension `.md`
+- Files prefixed with `_underscores` are ignored by Hyde
+- Your post will be stored in `_site/posts/<slug>.html`
+
+**Example:**
+```bash
+✔ _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.
+
+You can read more about the Front Matter format in the [Front Matter documentation](architecture-concepts.html#front-matter).
+Here is a quick primer:
+
+- 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.
+- 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.
+
+
+**Example:**
+```markdown
+---
+title: "My New Post"
+---
+
+## Markdown comes here
+```
+
+You can use the `php hyde make:post` command to automatically generate the front matter based on your input.
+
+
+## A first look at Front Matter
+
+Before digging in deeper on all the supported front matter options,
+let's take a look at what a basic post with front matter looks like.
+
+This file was created using the `make:post` by hitting the `Enter` key to use
+all the defaults (with some extra lorem ipsum to illustrate).
+
+```markdown {: 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.
+```
+
+### How the Front Matter is used
+
+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.
+
+### Front matter syntax
+
+Here is a quick reference of the syntax Hyde uses and expects:
+
+```markdown
+---
+key: value
+string: "quoted string"
+boolean: true
+integer: 100
+array:
+ key: value
+ key: value
+---
+```
+
+## 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 NAME** | **VALUE TYPE** | **EXAMPLE / FORMAT** |
+|----------------|----------------|----------------------------------|
+| `title` | string | "My New Post" |
+| `description` | string | "A short description" |
+| `category` | string | "my favorite recipes" |
+| `date` | string | "YYYY-MM-DD [HH:MM]" |
+| `author` | string/array | _See [author](#author) section_ |
+| `image` | string/array | _See [image](#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, thus they are included here.
+
+In the examples below, when there are multiple keys, they signify various ways to use the parameter.
+
+### Title
+
+```yaml
+title: "My New Post"
+```
+
+
+### Description
+
+```yaml
+description: "A short description used in previews and SEO"
+```
+
+
+### Category
+
+```yaml
+category: blog
+category: "My favorite recipes"
+```
+
+
+### Date
+
+```yaml
+date: "2022-01-01 12:00"
+date: "2022-01-01"
+```
+
+
+### Author
+
+```yaml
+author: "Mr. Hyde" # Arbitrary name displayed "as is"
+author: mr_hyde # Username defined in `authors.yml` config
+author: # Array of author data
+ name: "Mr. Hyde"
+ username: mr_hyde
+ website: https://mrhyde.example.com
+```
+
+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 the values in the `authors.yml` config.
+
+### Image
+
+```yaml
+image: image.jpg # Expanded by Hyde to `_media/image.jpg` and is resolved automatically
+image: https://cdn.example.com/image.jpg # Full URL starting with `http(s)://`)
+image:
+ path: image.jpg
+ uri: https://cdn.example.com/image.jpg # Takes precedence over `path`
+ description: "Alt text for image"
+ title: "Tooltip title"
+ copyright: "Copyright (c) 2022"
+ license: "CC-BY-SA-4.0"
+ licenseUrl: https://example.com/license/
+ credit: https://photographer.example.com/
+ author: "John Doe"
+```
+
+When supplying an image with a local image path, the image is expected to be stored in the `_media/` directory.
+
+The image will be used as the cover image, and any array data is constructed into a dynamic fluent caption,
+and injected into post and page metadata.
+
+> See [posts/introducing-images](https://hydephp.github.io/posts/introducing-images.html)
+> for a detailed blog post with examples and schema information!
+{ .info }
+
+
+## Using images in posts
+
+To use images stored in the `_media/` directory, you can use the following syntax:
+
+```markdown
+ # Note the relative path
+```
+
+To learn more, check out the [chapter in managing assets](managing-assets.html#managing-images)
\ No newline at end of file
diff --git a/console-commands.md b/console-commands.md
index 89eaa69..e1a1f6e 100644
--- a/console-commands.md
+++ b/console-commands.md
@@ -1,158 +1,231 @@
+---
+priority: 5
+category: "Getting Started"
+---
+
# Console Commands
-Hyde is based on [Laravel Zero](https://laravel-zero.com/), which is a micro-framework for console applications.
-As such, when you are not writing Markdown posts, most of your time with Hyde will be spent using the CLI.
+The primary way of interacting with Hyde is through the command line using the HydeCLI.
-To help in developing your site we have also included a few scripts in the `package.json`.
+If you have ever used the Artisan Console in Laravel you will feel right at home,
+the Hyde CLI is based on Artisan after all!
## Hyde Commands
-The main place you will interact with Hyde is with the Hyde Console which you access by navigating to your project directory and running the `php hyde` command. If you have ever used the Artisan Console in Laravel you will feel right at home, the Hyde CLI is based on Artisan after all!
-Let's take a quick rundown of the most common commands you will use.
+To use the HydeCLI, run `php hyde` from your project directory followed by a command.
+
+### Documentation syntax
+
+Wondering what the different formatting in examples means? Here's a quick guide:
-You can always run the base command `php hyde` to show the list of commands:
```bash
-// torchlight! {"lineNumbers": false}
- __ __ __ ___ __ _____
- / // /_ _____/ /__ / _ \/ // / _ \
- / _ / // / _ / -_) ___/ _ / ___/
- /_//_/\_, /\_,_/\__/_/ /_//_/_/
- /___/
+<argument> # Comes after the command name.
+[<argument>] # Optional argument.
- v0.1.0-pre
+--option # Sometimes referred to as a flag.
+--option=<value> # Option which takes an value.
+[--option] # Optional option.
+```
- USAGE: hyde <command> [options] [arguments]
+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.
- build Build the static site
- inspire Display an inspiring quote
- make:post Scaffold a new Markdown blog post file
-```
-> Tip: You can always add --help to a command to show detailed usage output
+### Got stuck? The CLI can help.
-### The Build Command
+You can always run the base command `php hyde`, or `php hyde list`, to show the list of commands.
-Maybe the most important command is the Build command, which -- you guessed it -- builds your static site!
+```bash
+php hyde # or `php hyde list`
+```
+You can also always add `--help` to a command to show detailed usage information.
```bash
-php hyde build
+php hyde <command> --help
```
-> If you want to to prettify the output HTML you can add the `--pretty` option. This requires that you have Node and NPM installed as it uses the Prettier NPM module.
-#### The Rebuild Command
+### Initialize a new Hyde project
+```bash
+php hyde install
+```
-Using the `php hyde build` command is great and all that, but when you just need to update that one file it gets a little... overkill.
+While Hyde doesn't need much configuration to get started, this command speeds up the little there is.
-Let's solve that! Use the `php hyde rebuild <file>` command!
+For example, it updates the config file with the supplied site name and URL,
+and can also publish a starter homepage and rebuild the site.
-In the future it will support an array of files, but for now, the rebuild command will recompile just that file.
-### The Post Make Command
-You can of course create blog posts the old fashioned way by just creating the files yourself, but what's the fun in that?
+### Build the static site
+```bash
+php hyde build
+```
-Using the Make command you will be asked a series of questions which are then used to scaffold a blog post file. It automatically takes care of YAML Front Matter formatting and generates a slug from the supplied title and even adds the current date.
+Maybe the most important command is the Build command, which -- you guessed it -- builds your static site!
-```bash
-php hyde make:post
+**Supports the following options:**
+```
+--run-dev Run the NPM dev script after build
+--run-prod Run the NPM prod script after build
+--pretty Format the output using NPM Prettier
+--no-api Disable API calls, for example, Torchlight
```
-> Tip: To overwrite existing files, supply the --force flag (at your own risk of course)
+### Build a single file
+```bash
+php hyde rebuild <filepath>
+```
+Using the php hyde build command is great and all that,
+but when you just need to update _that one file_ it gets a little... overkill.
+To solve this problem, you can use the `rebuild` command to compile a single file.
-### The Publish Command
-If you are coming from Laravel, you are probably familiar with the Artisan vendor:publish command.
+**Requires the following Arguments:**
+```
+path The relative file path
+```
-Hyde has a similar command that allows you to publish various pages.
+**Example:**
+```bash
+php hyde rebuild _posts/hello-world.md
+```
-#### Publish Configs
-To publish the default configuration files (if you mess something up, or when updating) run the following command. You may need to supply the --force option to overwrite existing files.
+### Start the realtime compiler.
```bash
-php hyde publish:config [--force]
+php hyde serve
```
-#### Publish a Homepage
-Hyde comes with 3 build in homepages. On a fresh install the page 'welcome' is installed. However, you can use the publish command to publish another one. You will probably need to supply the --force option to overwrite existing files.
+The serve command feels similar to the Laravel Artisan serve command, but works by
+starting a local PHP server. When you visit a page, the server will use the
+realtime compiler to locate the source file, recompile it, and proxy
+the resulting HTML and any media files to your browser.
-The available homepages are:
-- *blank*: This is a blank Blade page that simply contains the base layout
-- *post feed*: This is the view that this documentation site uses. It contains a listing of the latest posts and was previously the default.
-- *welcome*: This is the current welcome page. Unlike the other pages, the styles are defined inline.
+If you are missing the extension, you can always reinstall it with Composer `composer require hyde/realtime-compiler`.
+You can also learn more on the [GitHub page](https://github.com/hydephp/realtime-compiler).
-When publishing any of these pages they will be saved as index.blade.php in the `_pages` directory which the compiler will use to create the index.html page.
+**Supports the following options:**
+```
+--port[=PORT] [default: "8080"]
+--host[=HOST] [default: "localhost"]
+```
-Tip: If you want to have a /posts page you can publish the post feed homepage, rename it to `posts.blade.php` and republish another home page!
-#### Publish the Default Views & Components
-Since Hyde is based on the Laravel view system the compiler uses Blade views and components.
+### Scaffold a new blog post file
+```bash
+php hyde make:post
+```
-Laravel actually registers two locations for the Hyde views: your site's resources/views/vendor directory and the directory source directory in the Framework package.
+At the core, blog posts are just pain ol' Markdown files.
+However, by adding a special YAML syntax called Front Matter, you can add metadata to your posts.
+But who can remember the syntax? You can use the `make:post` command to scaffold a new blog post file.
+The command will ask you a series of interactive questions, letting you fill in the blanks.
+It will then create a file, converting your input into front matter. It automatically
+sets the date and time for you, and the file name will be based on the title.
-So, when compiling a site, Laravel will first check if a custom version of the view has been placed in the resources/views/vendor/hyde directory by the developer (you). Then, if the view has not been customized, Laravel will search the Hyde framework view directory. This makes it easy for you to customize / override the package's views.
-To publish the views, use
+### Scaffold a new page file
```bash
-php hyde publish:views
+php hyde make:page <title> [--type=TYPE]
```
-you will then be asked to select which views you want to publish. There are 3 options:
-- *components*: These are the reusable components used by the framework
-- *layouts*: These are the base layouts used by the framework
-- *404 page*: This is a special view, containing a beautiful Blade view from [LaravelCollective](https://github.com/LaravelCollective/errors). When published, it will be compiled into 404.html.
-> Note that when a view is updated in the framework you will need to republish the views to get the new changes! You can supply the --force tag to overwrite any existing files.
+The `make:page` command is similar to the `make:post` command and lets you quickly
+create one of the following page types:
-### The Validate Command
-Hyde ships with a very useful command that runs a series of checks to validate your setup and catch any potential issues.
+- **Markdown**:
+ Creates a Markdown file in the `_pages` directory.
+- **Blade**:
+ Creates a Blade file using the app layout in the `_pages` directory.
+- **Docs**:
+ Creates a Markdown file in the `_docs` directory.
-The command is `php hyde validate` and gives an output similar to this
+In all cases, the title will be used in the created file as the page title, and to generate the filename.
+
+**Requires the following Arguments:**
+```
+title The name of the page file to create
+```
+
+**Supports the following options:**
+```
+--type[=TYPE] The type of page to create (markdown, blade, or docs) [default: "markdown"]
+```
+
+**Example:**
```bash
-// torchlight! {"lineNumbers": false}
-$ php hyde validate
+php hyde make:page About # Defaults to Markdown
+php hyde make:page "Photo Gallery" --type=blade
+php hyde make:page "Hyde CLI Guide" --type=docs
+```
-Running validation tests!
+### Publish a default homepage
+```bash
+php hyde publish:homepage [<name>]
+```
- PASS CheckForPageConflictsTest
- ✓ check for conflicts between blade and markdown pages
+Hyde comes with three homepage options to choose from. The homepage you select is stored as
+`_pages/index.blade.php` and becomes the `index.html` file when compiling the site.
- PASS CheckThatAnIndexFileExistsTest
- ✓ check that an index file exists
+On a fresh install the page 'welcome' is installed.
+However, you can use this command to publish another one.
+If you have modified the file, you will need to supply the --force option to overwrite it.
- WARN CheckThatDocumentationPagesHaveAnIndexPageTest
- ! check that documentation pages have an index page
- → Could not find an index.md file in the _docs directory!
+The available homepages are:
- PASS CheckThatFrontendAssetsExistTest
- ✓ check that app.css exist
- ✓ check that tailwind.css exist
+- **welcome:** The default welcome page. Unlike the other pages, the styles are defined inline.
+- **posts:** A Blade feed of your latest blog posts. Perfect for a blog site!
+- **blank:** A blank Blade template with just the base app layout.
+You can supply the homepage name directly to the command, otherwise you will be prompted to select one.
- Tests: 1 warnings, 4 passed
- Time: 0.31s
-All done!
+### Publish the Hyde Blade views
+```bash
+php hyde publish:views [<category>]
```
-## NPM Commands
-The NPM commands are used to compile the frontend CSS assets and to run the realtime compiler.
+Since Hyde is based on the Laravel view system the compiler uses Blade views and components.
+Laravel actually registers two locations for the Hyde views: your site's `resources/views/vendor/hyde` directory and the `resources` directory located in the Framework package.
-Make sure you have Node and NPM installed to use these, and if it's the first time running a command, remember to run `npm install` first!
+<blockquote class="warning">
+<p>Warning: This command will overwrite any existing files in the <code>resources/views/vendor</code> directory. <br>
+You should be sure to have backups, or version control such as Git, before running this command.</p>
+</blockquote>
-If you don't have Node and NPM installed, and you don't want to install them you can download the [prebuilt styles from GitHub](https://github.com/hydephp/hyde/tree/master/_site/media).
+So, when compiling a site, Laravel will first check if a custom version of the view has been placed in the `resources/views/vendor/hyde` directory by the developer (you). Then, if the view has not been customized, Laravel will search the Hyde framework view directory. This makes it easy for you to customize / override the package's views.
-## Commands for the frontend assets
-- **`npm run dev`** - Compiles the Tailwind
-- **`npm run prod`** - Compiles the Tailwind and minifies the output.
+The available views you can publish are:
+- **all:** Publish all categories listed below
+- **layouts:** Global layout views, such as the app layout, navigation menu, and Markdown page templates.
+- **components:** More or less self-contained components, extracted for customizability and DRY code.
+- **404:** A beautiful 404 error page by the Laravel Collective. This file is already published by default.
-## Realtime compiler AKA Watching files for changes
+You can supply the category name directly to the command, otherwise you will be prompted to select one.
-Hyde has a real-time compiler that watches your files for changes and rebuilds the site on the fly.
-> Currently, all pages are rebuilt, but in a future update, only the affected files will be rebuilt.
+<blockquote class="info">
+Note that when a view is updated in the framework you will need to republish the views to get the new changes!
+</blockquote>
+
+### Republish the configuration files
+```bash
+php hyde update:configs
+```
-The real-time viewer also uses Browsersync which starts a local web server and automatically refreshes your pages once they are changed.
+When updating Hyde to a new version (or if you mess up your config files),
+you can use this command to republish the configuration files.
-**To start the preview run**
+<blockquote class="warning">
+<p>Warning: This command will overwrite any existing files in the <code>config</code> directory. <br>
+You should be sure to have backups, or version control such as Git, before running this command.</p>
+</blockquote>
+
+
+### Run validation tests to optimize your site
```bash
-npm run watch
+php hyde validate
```
-A browser page should automatically be opened. If not, just navigate to http://localhost:3000/.
+
+Hyde ships with a very useful command that runs a series of checks to validate your setup and catch any potential issues.
+
+> The validate command requires that [Pest](https://pestphp.com/) is installed.
+> Pest is by default bundled as a dev-dependency with Hyde.
\ No newline at end of file
diff --git a/customization.md b/customization.md
index 96e9ad1..975167f 100644
--- a/customization.md
+++ b/customization.md
@@ -1,12 +1,19 @@
+---
+label: "Customizing your Site"
+priority: 25
+category: "Digging Deeper"
+---
+
# Customizing your Site
-<p class="lead">
+## Introduction
+
Hyde favours <a href="https://en.wikipedia.org/wiki/Convention_over_configuration">"Convention over Configuration"</a>
and thus comes preconfigured with sensible defaults. However, Hyde also strives to be modular and endlessly customizable hackable if you need it. This page guides you through the endless options available!
-</p>
+
## Main Configuration File
-The main configuration file is in `config/hyde.php`. The [config file](https://github.com/hydephp/hyde/blob/master/config/hyde.php) is fully documented so I recommend you take a look to see all the options.
+The main configuration file is in `config/hyde.php`. The [config file](https://github.com/hydephp/hyde/blob/master/config/hyde.php) is fully documented, so I recommend you take a look to see all the options.
In this config file, you can customize the site name, what modules to enable, and programmatically customize the navigation menu and documentation sidebar.
@@ -103,7 +110,35 @@ Hyde uses the Laravel templating system called Blade. Most parts have been extra
To edit the default component you need to publish them first using the `hyde publish:views` command.
+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.
+Hyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template for you to get up and running quickly. If you want to customize these, you are free to do so. Please see the [Managing Assets](managing-assets.html) page to learn more.
+
+
+## CommonMark environment
+
+Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML.
+
+Hyde ships with the GitHub Flavored Markdown extension, and
+the Torchlight extension is enabled automatically when needed.
+
+You can add extra CommonMark extensions, or change the default ones, in the `config/markdown.php` file.
-Please see the chapter in the [Getting Started](getting-started.html) page to learn more.
+```php
+'extensions' => [
+ \League\CommonMark\Extension\GithubFlavoredMarkdownExtension::class,
+ \League\CommonMark\Extension\Attributes\AttributesExtension::class,
+ \League\CommonMark\Extension\DisallowedRawHtml\DisallowedRawHtmlExtension::class,
+],
+```
+
+In the same file you can also change the config to be passed to the CommonMark environment.
+
+```php
+'config' => [
+ 'disallowed_raw_html' => [
+ 'disallowed_tags' => [],
+ ],
+],
+```
diff --git a/directory-structure.md b/directory-structure.md
index afbed1c..9870577 100644
--- a/directory-structure.md
+++ b/directory-structure.md
@@ -1,87 +1,9 @@
-# Directory Structure
+---
+hidden: true
+---
-To take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure.
+<meta http-equiv="refresh" content="0;url=architecture-concepts.html#directory-structure" />
-## Tree Overview
-```
-// torchlight! {"lineNumbers": false}
-├── _docs
-├── _media
-├── _pages
-├── _posts
-├── _site
-├── config
-├── resources
-│ └── frontend
-│ └── views
-│ ├── components
-│ └── layouts
-```
+Redirecting you to [architecture-concepts#directory-structure](architecture-concepts.html#directory-structure)
-## Directory Explanation
-It may be helpful to separate the two types of directories we have.
-
-First, we have the content directories, these are prefixed with an underscore (`_`).
-
-Then we have the resource directories, they contain the HTML (Blade) templates and similar. If you are just getting started you may not need to dig into the second category, but they are available for you to play around with!
-
-Let's take a look!
-
-### Content Directories
-
-#### `_posts`
-This is where the blog post files are stored. Files here support YAML front matter.
-
-You can scaffold posts using the `php hyde make:post` command with automatically creates the front matter based on your input selections.
-
-A _posts directory filled with posts may look similar to this.
-```
-// torchlight! {"lineNumbers": false}
-_posts
-├── hello-world.md
-├── my-first-post.md
-├── diary-of-a-volunteer.md
-├── benefits-of-milkshakes.md
-└── a-fifth-longer-post-here.md
-```
-
-**Limitations:** Currently only top-level posts are supported. Files should use kebab-case format and must also end in .md and contain front matter to be recognized.
-
-#### `_docs`
-Hyde includes a spiritual successor of [Laradocgen](https://github.com/caendesilva/laradocgen)
-
-All you need to do to create a documentation page is to place a Markdown file in this directory and run the build command.
-The sidebar will automatically be populated with the page title which is derived from the first H1 (# Title) tag.
-
-This documentation page is built with HydeDocs, and you can take a look at the source code on https://github.com/hydephp/docs which also serves this site through GitHub Pages.
-
-**Limitations:** Currently only top-level posts are supported. Soon (hopefully) you will be able to put files in subdirectories, or specify a parent, to create a sidebar with categories.
-
-Files should use kebab-case format and must also end in .md and contain front matter to be recognized.
-
-#### `_pages`
-You can also place Markdown and Blade files here and they will be compiled into simple top-level pages.
-
-Markdown is perfect for about pages, or terms of service policy pages!
-
-Blade pages are excellent for when you want full control over the layout of your site. The default homepages are built with Blade pages.
-
-**Limitations:** Only top-level pages are supported. Files should use kebab-case format and must also end in .md and contain front matter to be recognized.
-
-> Make sure the slug does not conflict with a custom Blade page as Markdown pages are compiled first and may be overwritten.
-
-#### `_site`
-This is where the compiled static site is stored. You should not edit files here as they may get overwritten.
-
-When publishing your site this is where you should serve the site from.
-
-
-### Resource Directories
-#### `config`
-The config directory contains configuration files. The most interesting one is probably `config/hyde.php` where you can set the site name!
-
-
-#### `resources/assets`
-This directory contains the frontend source files.
-
-The default frontend resource files are as follows. Please see the chapter in the [Getting Started](getting-started.html) page to learn more.
\ No newline at end of file
+<!-- Note to self, if we need a lot of these in the future it may make more sense to put them in a CI that loads redirects from a config -->
\ No newline at end of file
diff --git a/documentation-pages.md b/documentation-pages.md
new file mode 100644
index 0000000..b6e2eb7
--- /dev/null
+++ b/documentation-pages.md
@@ -0,0 +1,192 @@
+---
+label: Documentation Pages
+priority: 12
+category: "Creating Content"
+---
+
+# Creating Documentation Pages
+
+## Introduction to Hyde Documentation Pages
+
+Hyde makes it easier than ever to create documentation sites.
+By the way, this documentation site is of course made with the Hyde Documentation module!
+
+In short, all you need to do is put standard Markdown files in the `_docs/` directory and Hyde will do the rest.
+
+What is "the rest", you may ask? Well, for starters:
+
+- Hyde compiles your Markdown content into a beautiful static HTML page based on [the Lagrafo frontend](https://github.com/caendesilva/lagrafo)
+- A sidebar (which is responsive) is automatically created based on your Markdown files
+ - If you have an `index.md` or `readme.md` in the `_docs/` directory, it will be used as the sidebar header
+ - You can even [customize the order and labels](#sidebar-page-order) of sidebar items
+- If you have an `index.md` or `readme.md` in the `_docs/` directory,
+ a link to it will be added to the site navigation menu named "Docs".
+- If you have a Torchlight API token in your .env file, Hyde will even automatically enable Syntax Highlighting for you.
+ See more about this in the [extensions page](extensions.html#torchlight).
+
+### Best Practices and Hyde Expectations
+
+Since Hyde does a lot of things automatically, there are some things you may need
+to keep in mind when creating blog posts so that you don't get unexpected results.
+
+#### 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-slug` 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/<slug>.html` unless you [change it in the config](#output-directory)
+
+
+## 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](console-commands.html).
+
+```bash
+php hyde make:page "Page Title" --type="docs"
+```
+
+This will create the following file saved as `_docs/page-title.md`
+
+```markdown
+# Page Title
+```
+
+### Front Matter is optional
+
+You don't need to use [front matter](blog-posts.html#supported-front-matter-properties) 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](#dynamic-content-generation) section to learn more.
+
+```yaml
+---
+title: "Page Title"
+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.
+
+Before we look at how to override things, here is an overview of the relevant content Hyde generates,
+and where the data is from as well as where it can be overridden.
+
+
+| Property | Description | Source | Override in |
+|----------------------|--------------------------------------------------------|--------------------------------|----------------------|
+| `title` (string) | The title of the page used in the HTML `<title>` tag | The first H1 heading (`# Foo`) | Front matter |
+| `label` (string) | The label for the page shown in the sidebar | The page filename (slug) | Front matter |
+| `hidden` (boolean) | Hides the page from the sidebar | _null_ | Front matter |
+| `priority` (integer) | The priority of the page used for ordering the sidebar | Defaults to 999 | Front matter, config |
+
+
+## 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.
+
+### Table of contents
+
+Hyde automatically generates a table of contents for the page and adds it to the sidebar.
+
+The behaviour of this can be changed in the configuration file.
+See [the customization page](customization.html#navigation-menu--sidebar) for more details.
+
+
+### Sidebar ordering
+
+The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be.
+The default priority is 999. You can override the priority using the following front matter:
+
+```yaml
+priority: 5
+```
+
+You can also change the order in the Hyde configuration file.
+See [the chapter in the customization page](customization.html#navigation-menu--sidebar) for more details. <br>
+ _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:
+
+```yaml
+label: "My Custom Sidebar Label"
+```
+
+### Hiding items
+
+You can hide items from the sidebar by adding the `hidden` property to the front matter:
+
+```yaml
+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. <br>
+> In the future, this might be disabled by setting the `hidden` property to `false` in the front matter.
+
+## Customization
+
+Please see the [customization page](customization.html) 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.
+
+```php
+'docsDirectory' => 'docs' // Default
+'docsDirectory' => 'docs/master' // What the Hyde docs use
+```
+
+### 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 Hyde configuration file.
+
+```php
+'docsSidebarHeaderTitle' => 'API Documentation',
+```
+
+### Sidebar page order
+
+To quickly arrange the order of items in the sidebar, you can reorder the page slugs 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.
+
+```php
+'documentationPageOrder' => [
+ 'readme',
+ 'installation',
+ 'getting-started',
+]
+```
+
+See [the chapter in the customization page](customization.html#navigation-menu--sidebar) for more details. <br>
+
+
+### Table of contents settings
+
+In the Hyde config you can configure the behavior, content, and the look and feel of the sidebar table of contents.
+You can also disable the feature completely.
+
+```php
+'documentationPageTableOfContents' => [
+ 'enabled' => true,
+ 'minHeadingLevel' => 2,
+ 'maxHeadingLevel' => 4,
+ 'smoothPageScrolling' => true,
+],
+```
diff --git a/extensions.md b/extensions.md
new file mode 100644
index 0000000..cd1c874
--- /dev/null
+++ b/extensions.md
@@ -0,0 +1,59 @@
+---
+label: "Extensions & Integrations"
+priority: 28
+category: "Digging Deeper"
+---
+
+# 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.
+
+- **GitHub**: [hydephp/realtime-compiler](https://github.com/hydephp/realtime-compiler)
+- **Packagist**: [hydephp/realtime-compiler](https://packagist.org/packages/hyde/realtime-compiler)
+- **YouTube video**: [Introducing the Hyde Realtime Compiler](https://www.youtube.com/watch?v=1ZM4fQMKi64)
+
+
+## Integrations with third-party tools
+
+### Torchlight
+
+#### About Torchlight
+Torchlight is an amazing API for syntax highlighting and is what this site uses.
+I cannot recommend it highly enough, especially for documentation sites and code-heavy blogs!
+
+#### Getting started
+To get started you need an API token which you can get through the [torchlight.dev website](https://torchlight.dev/).
+It is entirely [free for personal and open source projects](https://torchlight.dev/#pricing).
+
+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.
+
+```env
+TORCHLIGHT_TOKEN=torch_<your-api-token>
+```
+
+#### Attribution and configuration
+
+Note that 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 this in the `config/torchlight.php` file.
+```php
+'attribution' => [
+ 'enabled' => true,
+ 'markdown' => 'Syntax highlighting by <a href="https://torchlight.dev/" rel="noopener nofollow">Torchlight.dev</a>',
+],
+```
+
+
+
+
+
+## Contribute
+
+Have an idea for an extension or integration? Let me know! I'd love to hear from you.
+
+Get in touch on [GitHub](https://github.com/hydephp/Hyde) or send me a DM on [Twitter](https://twitter.com/StressedDev).
\ No newline at end of file
diff --git a/getting-started.md b/getting-started.md
index 2b5d9d3..507d8ca 100644
--- a/getting-started.md
+++ b/getting-started.md
@@ -1,186 +1,9 @@
-# Getting Started
-Now that you have installed Hyde, let's get to using it!
-
-> If you have not already, now may be good to familiarize yourself with the [Directory Structure](directory-structure.html).
-
-## Creating content
-
-Hyde has 3 types of content generation (though you are free to add more, submit a PR!). You can think of them as modules if you want.
-
-- Hyde Posts - For the blogging system
-- Hyde Docs - For generating documentation pages
-- Hyde Pages - For generating both simple Markdown pages and advanced Blade ones
-
-Let's jump in and take a closer look at each of them!
-
-### Hyde Posts
-This is the Blogging module. Blog Posts, or simply Posts, are Markdown files stored in the `_posts` directory.
-
-#### Creating posts
-Posts can be created in one of two ways:
-1. You can create them manually by creating the files, or
-2. you can use the ´php hyde make:post´ command which automatically fills in the front matter for you.
-
-> See the tutorial for further instructions on how to use the make:post command.
-
-In both cases, the markdown file should use the kebab-case format and end in .md. When building the static site, the post will retain the filename slug but end in .html instead of .md.
-
-For example:
-`_posts/hello-world.md` will become `_site/posts/hello-world.html`
-
-After creating your post, run `php hyde build` to build your site! You should also look at the section dedicated to building the site if you have not already.
-
-#### About Front Matter
-These posts use a YAML syntax called "Front Matter" which you may be familiar with from frameworks like Jekyll.
-
-Each post should have a front-matter section before the content. A front matter section begins and ends with rows in the markdown file that consists of three dashes (`---`). Between these lines, you place key-value pairs of data which are shown in the frontend.
-
-Only the `title` is required, though you are encouraged to add any number of the following supported attributes as they are all displayed in the front end.
-
-**Example of a front-matter section**
-```yaml
----
-title: The title is the only value that is required
-description: A short description used in previews and SEO
-category: arbitrary-category-that-a,
-author: @TheMrHyde
-date: YYYY-MM-DD 16:00
----
-
-# Actual Markdown content is placed here
-```
-
-> At the moment no nested attributes are supported. The category value does not yet contain much functionality and is safe to omit.
-
-> Masterclass: you can add arbitrary front matter key-value-pairs and access them using `$post->matter['foo']` in a Blade view
-
-#### Tutorial
-
-For a full tutorial see https://hydephp.github.io/posts/creating-a-static-html-post-using-hydephp.html
-
-<!--
-#### Deep-dive
-> Deepdives take a closer look into how a feature works behind the scenes. While not required to know it can help to understand the "magic" behind Hyde. -->
-
-### Hyde Docs
-
-The Hyde Docs is based on Laradocgen and _automagically_ turns Markdown pages into documentation pages. They are what powers this documentation site!
-
-Creating documentation pages is a piece of cake. Create a file following the format of kebab-case-version-of-the-title.md in the _docs directory. Put any content you want in it, and run the build command.
-
-The sidebar will like magic be populated with all the documentation pages. The page titles in the sidebar are generated from the filename, and the HTML page title is inferred from the first H1 tag.
-
-> **Pro tip 1:** Enable the Torchlight extension to get the beautiful syntax highlighting used here!
-
-> **Pro tip 2:** You can specify the output directory for documentation pages in the Hyde config. This site uses that feature to save the pages in the 'master' directory for easy version support!
-
-### Hyde Pages using Markdown
-
-Hyde Markdown Pages are perfect for simple content-driven pages. Some examples of this may be "About Us" pages, or legal pages such as "Terms of Service" and "Privacy Policy".
-
-The Markdown pages work similarly to Documentation pages but use a simple Blade layout, putting the focus on your content.
-To create a Markdown page, all you need to do is create a file ending in .md in the _pages directory.
-
-You can use front matter to set the page title,
-```markdown
---
-title: Hello World!
+hidden: true
---
-```
-If you don't use front matter, the page title is automatically inferred from the first # H1 heading.
-
-You can scaffold Markdown pages using
-```bash
-php hyde make:page "Page Name"
-```
-
-### Hyde Pages using Blade
-
-If you want full control over a static page you can create blade views in the pages directory `_pages`, and they will be compiled into static HTML.
-
-Currently, only top-level pages are supported. The filename of the generated file is based on the view filename.
-For example, `_pages\custom-page.blade.php` gets saved as `_site\custom-page.html`.
-
-You can scaffold Blade pages using the make:page command to automatically create the file based on the default layout.
-```bash
-php hyde make:page "Page Name" --type=blade
-```
-
-**⚠ Warning:**
-Blade pages take precedence over Markdown pages! Do not use duplicate slugs.
-For example, if you have both an `about.md` and `about.blade.php`, only the Blade page will be compiled.
-
-**Using the default layout**
-If you want to match the styles of the rest of your app you can extend the default layout.
-```blade
-@extends('hyde::layouts.app')
-@section('content')
-
-// Place content here
-
-@endsection
-```
-
-You can reference any Hyde components, or add your own templates!
-You can also set the page title using
-```blade
-@php($title = "My Custom Title")
-```
-
-### Adding Images
-
-All media files in the _media directory will get copied to the _site/media directory upon build. To reference an image in your Markdown, use the following syntax
-To reference an image in your Markdown, use the following syntax
-```markdown
- # Note the relative path
-```
-
-Since most images are probably going to be in blog posts or documentation pages you need to prepend the `../` before the "media". However, if you are referencing the image on a Markdown page you should use `media/image.png` for the path.
-
-> Nested media directories are not yet supported.
-
-
-## Building the static site
-
-To compile the site into static HTML all you have to do is execute the Hyde build command.
-```bash
-php hyde build
-```
-
-Your site will then be saved in the _site directory, which you can then upload to your static web host.
-All links use relative paths, so you can deploy to a subdirectory without any problems which also makes the site work great when browsing the HTML files locally even without a web server.
-
-If it is the first time building the site or if you have added any custom TailwindCSS classes in your Blade views you should also run `npm install && npm run dev` to build the frontend assets.
-
-> ⚠ Note that since v0.21.x the `_site` directory is emptied from all files before the site is built.
-
-## Frontend stylesheets and scripts
-
-Hyde is designed to not only serve as a framework but a whole starter kit. Hyde comes with a Tailwind starter template for you to get up and running quickly.
-
-### The default frontend resource files are as follows:
-
-- **App.css**
-This file is mostly blank and only contains the TailwindCSS imports. If you want to add your own styles, this is a great place. Running `npm run dev/prod` will compile the Tailwind styles and any custom ones you define into `./_site/media/app.css`.
-
-- **Hyde.css**
-This file contains the base styles and should be loaded after App.css as it contains some Tailwind tweaks.
-
-- **Hyde.js**
-This file contains basic scripts to make the navigation menu and sidebars interactive.
-
-You can customize all of them to your liking, however, if you edit the Hyde.css or Hyde.js you may need to merge them manually when updating to a version if they have been changed. All three files will get copied into the `./_site/media/` directory when running the build command.
-### Updating to the latest version
-When updating Hyde, you may need to update the frontend resource files. You can do this using the following command:
-```bash
-php hyde update:assets
-```
+<meta http-equiv="refresh" content="0;url=quickstart.html" />
-Note that this command will overwrite existing files!
-The following files in the `resources/assets/` directory will be overwritten:
-- hyde.css
-- hyde.js
-- app.css
-Back up your content before running the command! (use Git so you can merge any conflicts)
+Redirecting you to [quickstart](quickstart.html)
+<!-- Note to self, if we need a lot of these in the future it may make more sense to put them in a CI that loads redirects from a config -->
\ No newline at end of file
diff --git a/index.md b/index.md
index e0f648c..07d0a46 100644
--- a/index.md
+++ b/index.md
@@ -1,38 +1,34 @@
# Elegant and Powerful Static App Builder
<p>
- <a href="https://packagist.org/packages/hyde/hyde"><img style="display: inline; margin: 4px 2px;" src="https://img.shields.io/packagist/v/hyde/hyde" alt="Latest Version on Packagist" title="Latest version of Hyde/Hyde"></a>
+ <!-- <a href="https://packagist.org/packages/hyde/hyde"><img style="display: inline; margin: 4px 2px;" src="https://img.shields.io/packagist/v/hyde/hyde" alt="Latest Version on Packagist" title="Latest version of Hyde/Hyde"></a> -->
<a href="https://packagist.org/packages/hyde/framework"><img style="display: inline; margin: 4px 2px;" src="https://img.shields.io/packagist/v/hyde/framework?include_prereleases" alt="Latest Version on Packagist" title="Latest version of Hyde/Framework"></a>
<a href="https://packagist.org/packages/hyde/framework"><img style="display: inline; margin: 4px 2px;" src="https://img.shields.io/packagist/dt/hyde/framework" alt="Total Downloads on Packagist"></a>
<a href="https://github.com/hydephp/hyde/blob/master/LICENSE.md"> <img style="display: inline; margin: 4px 2px;" src="https://img.shields.io/github/license/hydephp/hyde" alt="License MIT"> </a>
<a href="https://hydephp.github.io/developer-tools/coverage-report/"><img style="display: inline; margin: 4px 2px;" src="https://cdn.desilva.se/microservices/coverbadges/badges/9b8f6a9a7a48a2df54e6751790bad8bd910015301e379f334d6ec74c4c3806d1.svg" alt="Test Coverage" title="Average coverage between categories"></a>
- <img style="display: inline; margin: 4px 2px;" src="https://github.com/hydephp/framework/actions/workflows/test-suite.yml/badge.svg" alt="Test Suite"> <img style="display: inline; margin: 4px 2px;" src="https://github.styleci.io/repos/472503421/shield?branch=master" alt="StyleCI Status"> </a>
+ <img style="display: inline; margin: 4px 2px;" src="https://github.com/hydephp/framework/actions/workflows/test-suite.yml/badge.svg" alt="Test Suite"> <img style="display: inline; margin: 4px 2px;" src="https://github.styleci.io/repos/472503421/shield?branch=master" alt="StyleCI Status">
</p>
## ⚠ Beta Software Warning
Heads up! HydePHP is still new and currently in beta. Please report any bugs and issues in the appropriate issue tracker. Versions in the 0.x series might not be stable and may change at any time. No backwards compatibility guarantees are made and there will be breaking changes without notice.
Please wait until v1.0 for production use and remember to back up your source files before updating (use Git!). See https://hydephp.github.io/docs/master/updating-hyde.html for the upgrade guide.
+
+
## 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) Blade.
-Hyde is powered by Laravel Zero which is a stripped-down version of the robust Laravel Framework. Using Blade templates the site is intelligently compiled into static HTML.
-
-Hyde is inspired by JekyllRB and is created for Developers who are comfortable writing posts in Markdown. It requires virtually no configuration out of the box as it favours convention over configuration.
-This is what makes Hyde different from other Laravel static site builders that are more focused on writing your blade views from scratch, which you can do with Hyde too if you want.
+Hyde is different from other static site builders. It's blazingly fast and stupidly simple to get started with, yet it has the full power of Laravel when you need it.
-Hyde is designed to be stupidly simple to get started with, while also remaining easily hackable and extendable. Hyde comes with a lightweight minimalist frontend layout built with TailwindCSS which you can extend and customize with the Blade components.
+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 asset management.
-Due to this powerful modularity yet elegant simplicity, Hyde is a great choice for developers no matter what their background or experience level. Here are some ideas for what you can do with Hyde:
+Hyde is powered by Laravel Zero which is a stripped-down version of the robust Laravel Framework. Using Blade templates the site is intelligently compiled into static HTML.
-- You are a Laravel developer and want to build a static site without having to learn a new framework. Why not use Hyde, and take advantage of the built-in Blade support?
-- You just want to write blog posts in Markdown and not have to worry about anything else. Give Hyde a try and see if it helps you out.
-- You want to get a documentation site up and running quickly, allowing you to focus on content.
+Hyde was inspired by JekyllRB and is created for Developers who are comfortable writing posts in Markdown. It requires virtually no configuration out of the box as it favours convention over configuration and is preconfigured with sensible defaults.
-## Installation Quick Start
-> Full installation guide is at https://hydephp.github.io/docs/master/installation.html
+## Installation
The recommended method of installation is using Composer.
@@ -42,61 +38,4 @@ composer create-project hyde/hyde --stability=dev
For the best experience you should have PHP >= 8.0, Composer, and NPM installed.
-## Getting Started
-See the [Getting Started Documentation](https://hydephp.github.io/docs/master/getting-started.html) page for the full guide, and examples.
-
-### Creating blog posts
-Blog posts are Markdown files that are stored in the `_posts` directory.
-
-They support YAML Front Matter for metadata. You can scaffold post files using the `php hyde make:post` command to automatically generate the front matter.
-
-### Creating documentation pages
-With Hyde, writing documentation is fun again! To create a documenation page, literally all you need to do is place a Markdown file in the `_docs` directory. You don't need to worry as front matter, as Hyde automatically generates the page title based on the first heading, or the filename if no heading is found.
-
-### Creating static pages
-#### Markdown pages
-You can create Markdown based pages by putting Markdown files in the `_pages` directory. They will then be compiled into a simple HTML page. Front matter is optional, as the page title can be generated in the same way as documentation pages.
-#### Blade pages
-If you want more control over your pages, you can create Blade pages by putting views in the `_pages` directory. You can of course use Blade components within your views, they are stored in the resources/views/compomnents directory same as in Laravel.
-
-#### A note on filenames
-Hyde uses the `.md` extension for Markdown files and the `.blade.php` extension for Blade files. When compiling, the files will keep their base filenames, but with the extension renamed to `.html`. For example, the file `_posts/my-post.md` will be compiled to `_site/posts/my-post.html`.
-
-
-#### Building the static site
-When you have all your content ready, you can build the static site by running the `php hyde build` command.
-
-Your site will then be saved in the `_site` directory, which you can then upload to your static web host.
-
-If your site is missing the stylesheets you may need to run `npm install && npm run dev` to build the them.
-
-### How it works
-Hyde scans the source directories prefixed with _underscores for Markdown files and intelligently compiles them into static HTML using Blade templates automatically assigned depending on the source file. The site is then saved in _site.
-
-Hyde is "blog and documentation aware" and has built-in templates for both blogging and for creating beautiful documentation pages based on Laradocgen. Since Hyde is modular you can of course disable the modules you don't need.
-
-All links use relative paths, so you can deploy to a subdirectory without any problems which also makes the site work great when browsing the HTML files locally even without a web server.
-
-### Serve a live preview
-Use `php hyde serve` to start the realtime compiler and access your site from [localhost:8080](http://localhost:8080/).
-
-### NPM Commands
-See all commands in the documentation [Console Commands](https://hydephp.github.io/docs/master/console-commands.html)
-Hyde optionally uses NPM to compile TailwindCSS using Laravel Mix. Run it with `npm run dev/prod/watch`.
-
-## Hacking Hyde
-Hyde is designed to be easy to use and easy to customize and hack. You can modify the source views and SCSS, customize the Tailwind config, and you can even create 100% custom HTML and Blade pages that get compiled into static HTML.
-
-While Hyde favours "convention over configuration" there are serveral config options in the `config/hyde.php` file. All settings are prefilled with sensible defaults so you don't need to configure anything unless you want to!
-
-## Extensions
-Hyde comes with built-in support for Torchlight Syntax Highlighting.
-All you need to do is to set your API token in your .env file and
-Hyde will automatically enable the CommonMark extension.
-
-> Note that when using Torchlight the pages will take longer to generate as API calls need to be made.
-> However, Torchlight caches the response so this mostly affects the first time running the build, or if you update the page.
-
-## Known Issues
-Currently, only top-level custom pages are supported. In the future, nested pages will be supported.
-For example, _site/directory/page.html
+### To learn more, head over to the [quickstart page](quickstart.html).
\ No newline at end of file
diff --git a/installation.md b/installation.md
index 3cc5c6b..507d8ca 100644
--- a/installation.md
+++ b/installation.md
@@ -1,68 +1,9 @@
-# Installation Guide
+---
+hidden: true
+---
-## Installing HydePHP using Composer (recommended)
-The recommended method of installing Hyde is using Composer. After the project has been created you can scaffold a new blog post using the `make` command and following the on-screen instructions, and then compile the site into static HTML using the `build` command.
-
-```bash
-// torchlight! {"lineNumbers": false}
-composer create-project hyde/hyde example-site
-
-cd example-site
-
-npm install && npm run dev
-
-php hyde make:post
-
-php hyde build
-```
-
-If you now take a look in the `_site` directory you should see that an index.html file, as well as a posts/hello-world.html file, has been created! Open them up in your browser and take a look!
-
-> If you are missing the stylesheet, run `npm install && npm run dev`
-
-
-## Installing HydePHP Git/GitHub
-
-If you want to run the latest development branch of Hyde (not recommended for production!) you can install it directly from Git/GitHub.
-
-### Clone the repo
-There are two methods for creating a new project using Git/GitHub.
-The first one is using the GitHub website where you can clone the template repository using the green button labelled "Use this template" found at https://github.com/hydephp/Hyde.
-
-Or if you want to use the CLI, run
-```bash
-// torchlight! {"lineNumbers": false}
-git clone https://github.com/hydephp/hyde.git
-```
-
-### Finalizing
-Next, navigate into the created project and install the dependencies and build the assets.
-```bash
-// torchlight! {"lineNumbers": false}
-cd hyde
-composer install
-npm install
-npm run dev
-```
-
-
-### Usage
-After the project has been created you can scaffold a new blog post using the `make` command and following the on-screen instructions, and then compile the site into static HTML using the `build` command.
-
-```bash
-// torchlight! {"lineNumbers": false}
-php hyde make:post
-
-php hyde build
-```
-
-If you now take a look in the `_site` directory you should see that an index.html file, as well as a posts/hello-world.html file, has been created! Open them up in your browser and take a look!
-
-### A note on NPM/NodeJS
-Using NPM and NodeJS is optional as Hyde comes bundled with a precompiled and minified `app.css` containing all the Tailwind you need for the default views. However, if you want to customize the Tailwind config, or if you add new classes when customizing views or creating your own Blade pages, you will need to compile the assets yourself. Hyde makes this easy by shipping everything you need to use Laravel Mix. Simply run `npm install` and `npm run dev/prod/watch` to compile the Tailwind assets.
-
-## Next steps
-
-Make sure you check out the [getting started](getting-started.html) page to learn how to use Hyde!
+<meta http-equiv="refresh" content="0;url=quickstart.html" />
+Redirecting you to [quickstart](quickstart.html)
+<!-- Note to self, if we need a lot of these in the future it may make more sense to put them in a CI that loads redirects from a config -->
\ No newline at end of file
diff --git a/managing-assets.md b/managing-assets.md
index 4badc0d..74f0f49 100644
--- a/managing-assets.md
+++ b/managing-assets.md
@@ -1,6 +1,12 @@
+---
+priority: 20
+category: "Creating Content"
+---
+
# Managing and Compiling Assets
-## Intro
+## 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.
@@ -62,6 +68,35 @@ When running the `npm run dev/prod` command, the following happens:
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`.
-
## 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.
+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
+{.warning}
+
+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`
+
+#### 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:
+
+```markdown
+ # 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](blog-posts.html#image).
+
diff --git a/quickstart.md b/quickstart.md
new file mode 100644
index 0000000..ec426dd
--- /dev/null
+++ b/quickstart.md
@@ -0,0 +1,107 @@
+---
+label: Quickstart Guide
+priority: 1
+category: "Getting Started"
+---
+
+# Quickstart Guide
+
+## Installing HydePHP using Composer
+The recommended method of installing Hyde is using Composer.
+```bash
+// torchlight! {"lineNumbers": false}
+composer create-project hyde/hyde --stability=dev
+```
+
+### Requirements
+> These requirements are for your local development environment.
+
+Hyde is based on [Laravel 9](https://laravel.com/docs/9.x/releases)
+which requires a minimum PHP version of 8.0.
+You should also have [Composer](https://getcomposer.org/) installed.
+
+To use some features like [compiling your own assets](managing-assets.html)
+you also need NodeJS and NPM.
+
+
+## Using the Hyde CLI
+The main way to interact with Hyde is through HydeCLI.
+
+If you are familiar with Laravel Artisan you will feel right at home.
+
+Learn more about the HydeCLI in the [console commands](console-commands.html) documentation.
+
+## Starting a development server
+
+To make previewing your site a breeze you can use the real-time compiler
+which builds your pages on the fly. Start it using the HydeCLI:
+```bash
+php hyde serve
+```
+
+## Creating content
+
+### Directory structure
+
+Creating content with Hyde is easy. Simply place Markdown files in one of the source directories, which are as follows:
+```
+// torchlight! {"lineNumbers": false}
+├── _docs // For documentation pages
+├── _posts // For blog posts
+└── _pages // For static Markdown and Blade pages
+```
+
+> There are a few more directories that you should know about. Please see the
+> [directory structure](architecture-concepts.html#directory-structure) section.
+
+### Scaffolding files
+
+You can scaffold blog post files using the `php hyde make:post` command with automatically creates the front matter based on your input selections.
+
+You can also scaffold pages with the `php hyde make:page` command.
+
+```bash
+php hyde make:page "Page Title" # Markdown is the default page type
+php hyde make:page --type=blade # Creates a file extending the default layout
+php hyde make:page --type=docs # Quickly creates a documentation page
+```
+
+### Autodiscovery
+
+When building the site, Hyde will 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 that, including creating navigation menus!
+
+## Compiling to static HTML
+
+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:
+```bash
+php hyde build
+```
+
+**Your site is then stored in the `_site` directory.**
+
+### Managing assets
+
+Hyde comes bundled with a precompiled and minified `app.css` 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. See more on the [Managing Assets](managing-assets.html) 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 a CI that automatically builds and deploys this site.
+
+
+## Further reading
+
+Here's some ideas of what to read next:
+
+- [Architecture Concepts & Directory Structure](architecture-concepts.html)
+- [Console Commands with the HydeCLI](console-commands.html)
+- [Creating Blog Posts](blog-posts.html)
\ No newline at end of file
diff --git a/static-pages.md b/static-pages.md
new file mode 100644
index 0000000..7822c83
--- /dev/null
+++ b/static-pages.md
@@ -0,0 +1,141 @@
+---
+priority: 11
+label: "Markdown & Blade Pages"
+category: "Creating Content"
+---
+
+# 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-slug` format, followed by the appropriate extension
+- Files prefixed with `_underscores` are ignored by Hyde
+- Your page will be stored in `_site/<slug>.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, and are similar to [blog posts](blog-posts.html).
+You may want to read that page first as it explains [how front matter works](blog-posts.html#supported-front-matter-properties)
+and how to use it.
+
+You can create a Markdown page by adding a file to the `_pages` directory where the filename ends in `.md`.
+
+### Scaffolding Markdown Pages
+Scaffolding a Markdown page is as easy as using the [HydeCLI](console-commands.html).
+
+```bash
+php hyde make:page "Page Title"
+```
+
+This will create the following file saved as `_pages/page-title.md`
+
+```markdown
+---
+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 only front matter supported 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.
+
+In the future, more front matter options such as page descriptions and meta tags will be supported.
+
+
+## Creating Blade Pages
+
+Since Hyde is based on Laravel and uses the Blade templating engine,
+you can use Blade pages to create more complex pages.
+
+If you are not familiar with Blade, you may want to read [the Laravel Blade docs](https://laravel.com/docs/9.x/blade) 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.
+
+```bash
+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.
+
+```blade
+@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
+
+| Markdown | Blade |
+|-----------------------------------------------------|------------------------------------------------------------------------------------------|
+| ➕ 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](managing-assets.html) if you add Tailwind classes |
+
+
+### Live Demos
+
+The Hyde website ([hydephp.github.io](https://hydephp.github.io/)) uses both Markdown and Blade pages.
+
+The "Privacy" which you can find at [hydephp.github.io/privacy](https://hydephp.github.io/privacy) is a Markdown page,
+which is a perfect fit for this task, where the goal was to simply inform about the privacy policy.
+
+The "Gallery" which you can find at [hydephp.github.io/gallery](https://hydephp.github.io/gallery) is a Blade page.
+While a photo gallery could be used in a Markdown page, here I opted to use a Blade page instead. This allowed me
+to create a bunch of cool and dynamic interactions and animations as I had full control over the HTML and could
+easily add scripts, styles, and iframes. I also seperated sections into components to make them easier to manage.
diff --git a/troubleshooting.md b/troubleshooting.md
new file mode 100644
index 0000000..23c3594
--- /dev/null
+++ b/troubleshooting.md
@@ -0,0 +1,93 @@
+---
+priority: 35
+category: "Digging Deeper"
+---
+
+# 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](https://github.com/hydephp/docs)!
+
+> Tip: You can run `php hyde validate` to run a series of tests to help you catch common issues.
+{.info}
+
+
+## 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. 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. 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. Currently, Hyde does not support nested directories besides those already defined.
+ This means that for example files in `_posts/foo/bar/` will not be compiled.
+ This is a feature that will be added in the future.
+
+
+## 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 slugs 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.
+Based on [this blog post](https://github.com/hydephp/DocsCI/blob/ff4589b175c2794b0dfd4eedfe975fb02d20523c/_posts/draft-developer-definitions.markdown).
+
+- **Hyde**: The application that you are using.
+- **HydeCLI**: The command-line interface for Hyde.
+- **Framework**: The Hyde core codebase.
+
+- **Slug**: The filename without the extension (basename). Example: `hello-world`
+- **Filename**: The full name of a file with the extension. Example: `hello-world.md`
+- **Filepath**: The full file path including extension (almost always relative to the Hyde project) Example: `_posts/hello-world.md`
+
+<style>
+#document-main-content > ul > li > p {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+</style>
+
+
+## Common issues, causes, and solutions
+
+| Issue | Possible Cause | Possible Solution |
+|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 404 error when visiting site | Are you missing an index file in the _pages directory? | Add an index.md or index.blade.php |
+| Navigation menu not linking to the docs | You probably don't have an index.md file in the _docs directory. | Create an index file |
+| Page not discovered when compiling | The file name may be invalid | Ensure you follow the correct file naming convention. |
+| Page compiles slowly | The Torchlight extension may cause the compile times to increase as API calls need to be made. | Try disabling Torchlight |
+| Torchlight not working | Missing Composer package, missing API token, extension disabled in the config. | Reinstall Torchlight, add your token in the .env file, check config |
+| Error in Parser.php: "unable to parse" | Could be an issue with the YAML front matter parser. | Try adding a block of front matter to the top of the file |
+| Missing styles and/or assets | You may have accidentally deleted the files, or you have added new Tailwind classes. | Run `npm run dev` |
+| Image not found | You may be using a bad relative path. See [managing-assets](managing-assets.html#referencing-images). | Ensure your relative paths are correct. |
+| Wrong layout used | Hyde determines the layout template to use depending on the directory of the source file | Ensure your source file is in the right directory. |
+| Invalid/no permalinks or post URIs | You may be missing or have an invalid site URL | Set the site URL in the .env file |
+| No styles in custom Blade pages | When using custom blade pages need to add the styles yourself. You can do this by extending the default layout | Use the app layout, or by include the Blade components directly. |
+| Overriding Hyde views is not working | Ensure the Blade views are in the correct directory. | Rerun php hyde publish:views. |
+| Styles not updating when deploying site | It could be a caching issue. To be honest, when dealing with styles, it's always a caching issue. | Clear your cache, and optionally complain to your site host |
+| Documentation sidebar items are in the wrong order | Double check the config, make sure the slugs are written correctly. Check that you are not overriding with front matter. | Check config for typos and front matter |
+| Documentation table of contents is weird | The table of contents markup is generated by the [Leauge/CommonMark extension](https://commonmark.thephpleague.com/2.3/extensions/table-of-contents/) | Make sure that your Markdown headings make sense |
+| Issues with date in blog post front matter | The date is parsed by the PHP strtotime() function. The date may be in an invalid format, or the front matter is invalid | Ensure the date is in a format that strtotime() can parse. Wrap the front matter value in quotes. |
+| Unable to do literally anything | If everything is broken, you may be missing a Composer package or your configuration files could be messed up. | Run `composer install` and/or `composer update`. If you can run HydeCLI commands, update your configs with `php hyde update:configs`, or copy them manually from GitHub or the vendor directory. |
diff --git a/updating-hyde.md b/updating-hyde.md
index a287b05..3d454a6 100644
--- a/updating-hyde.md
+++ b/updating-hyde.md
@@ -1,3 +1,8 @@
+---
+priority: 30
+category: "Digging Deeper"
+---
+
# Updating Hyde
## While Hyde is in beta, stuff can change rapidly.