From bf886843a2cbbbda063feaa267c8829da0139f01 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 17:38:54 +0200 Subject: [PATCH 01/70] Create Quick Start Guide --- quick-start.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 quick-start.md diff --git a/quick-start.md b/quick-start.md new file mode 100644 index 0000000..3535c45 --- /dev/null +++ b/quick-start.md @@ -0,0 +1,85 @@ +# Quick Start 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 +``` + +## Using the Hyde CLI +The main way to interact with Hyde is through the HydeCLI. +If you are familiar with Laravel Artisan you will feel right at home. + +You access it through the command line with `php hyde `. + +## Starting a development server + +To make previewing your site a breeze you can use the realtime 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 or Blade pages +``` + +### 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 in 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. + + +## Next steps + +Make sure you check out the [getting started](getting-started.html) page to learn how to use Hyde! + + From ee967d5522e96870015e31f54def18ecff8beb2f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 17:48:06 +0200 Subject: [PATCH 02/70] Add front matter block to make Symfony happy --- getting-started.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/getting-started.md b/getting-started.md index 2b5d9d3..7deb748 100644 --- a/getting-started.md +++ b/getting-started.md @@ -1,3 +1,5 @@ +--- +--- # Getting Started Now that you have installed Hyde, let's get to using it! From e0b948f0ae34efdb35454f3c4cb67dff12e36a08 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 17:55:33 +0200 Subject: [PATCH 03/70] Change heading levels, fix grammar --- quick-start.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/quick-start.md b/quick-start.md index 3535c45..09cbe19 100644 --- a/quick-start.md +++ b/quick-start.md @@ -15,7 +15,7 @@ You access it through the command line with `php hyde `. ## Starting a development server -To make previewing your site a breeze you can use the realtime compiler +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 @@ -61,14 +61,13 @@ This is as easy as executing the `build` command: php hyde build ``` - **Your site is then stored in the `_site` directory.** -## Managing assets +### 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 in the [Managing Assets](managing-assets.html) page. +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 +### Deploying your site You are now ready to show your site to the world! From 1d01c26005091691ce742ddc2a5a1dc303f985a9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 17:58:16 +0200 Subject: [PATCH 04/70] Begin rewriting documentation --- README.markdown => 0.1x/README.markdown | 0 .../console-commands.md | 0 customization.md => 0.1x/customization.md | 0 .../directory-structure.md | 0 getting-started.md => 0.1x/getting-started.md | 0 0.1x/index.md | 102 ++++++++++++++++++ installation.md => 0.1x/installation.md | 0 managing-assets.md => 0.1x/managing-assets.md | 0 updating-hyde.md => 0.1x/updating-hyde.md | 0 9 files changed, 102 insertions(+) rename README.markdown => 0.1x/README.markdown (100%) rename console-commands.md => 0.1x/console-commands.md (100%) rename customization.md => 0.1x/customization.md (100%) rename directory-structure.md => 0.1x/directory-structure.md (100%) rename getting-started.md => 0.1x/getting-started.md (100%) create mode 100644 0.1x/index.md rename installation.md => 0.1x/installation.md (100%) rename managing-assets.md => 0.1x/managing-assets.md (100%) rename updating-hyde.md => 0.1x/updating-hyde.md (100%) diff --git a/README.markdown b/0.1x/README.markdown similarity index 100% rename from README.markdown rename to 0.1x/README.markdown diff --git a/console-commands.md b/0.1x/console-commands.md similarity index 100% rename from console-commands.md rename to 0.1x/console-commands.md diff --git a/customization.md b/0.1x/customization.md similarity index 100% rename from customization.md rename to 0.1x/customization.md diff --git a/directory-structure.md b/0.1x/directory-structure.md similarity index 100% rename from directory-structure.md rename to 0.1x/directory-structure.md diff --git a/getting-started.md b/0.1x/getting-started.md similarity index 100% rename from getting-started.md rename to 0.1x/getting-started.md diff --git a/0.1x/index.md b/0.1x/index.md new file mode 100644 index 0000000..e0f648c --- /dev/null +++ b/0.1x/index.md @@ -0,0 +1,102 @@ +# Elegant and Powerful Static App Builder + +

+ Latest Version on Packagist + Latest Version on Packagist + Total Downloads on Packagist + License MIT + Test Coverage + Test Suite StyleCI Status +

+ +## ⚠ 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 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. + +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: + +- 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. + + +## Installation Quick Start +> Full installation guide is at https://hydephp.github.io/docs/master/installation.html + +The recommended method of installation is using Composer. + +```bash +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 diff --git a/installation.md b/0.1x/installation.md similarity index 100% rename from installation.md rename to 0.1x/installation.md diff --git a/managing-assets.md b/0.1x/managing-assets.md similarity index 100% rename from managing-assets.md rename to 0.1x/managing-assets.md diff --git a/updating-hyde.md b/0.1x/updating-hyde.md similarity index 100% rename from updating-hyde.md rename to 0.1x/updating-hyde.md From cf6483a2606abab32e1cecb8a81180735b6b55d6 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 17:59:13 +0200 Subject: [PATCH 05/70] Remove Hyde/Hyde version shield --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index e0f648c..bd169d7 100644 --- a/index.md +++ b/index.md @@ -1,7 +1,7 @@ # Elegant and Powerful Static App Builder

- Latest Version on Packagist + Latest Version on Packagist Total Downloads on Packagist License MIT From a02b65aba10b4702d36dc49412eb0a553b87eea7 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 18:07:54 +0200 Subject: [PATCH 06/70] Rename quick start to quickstart --- quick-start.md => quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename quick-start.md => quickstart.md (99%) diff --git a/quick-start.md b/quickstart.md similarity index 99% rename from quick-start.md rename to quickstart.md index 09cbe19..2852101 100644 --- a/quick-start.md +++ b/quickstart.md @@ -1,4 +1,4 @@ -# Quick Start Guide +# Quickstart Guide ## Installing HydePHP using Composer The recommended method of installing Hyde is using Composer. From 867585a3d0c272494b36695713fee12913458362 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 18:10:25 +0200 Subject: [PATCH 07/70] Override label --- quickstart.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/quickstart.md b/quickstart.md index 2852101..a79e501 100644 --- a/quickstart.md +++ b/quickstart.md @@ -1,3 +1,7 @@ +--- +label: Quickstart Guide +--- + # Quickstart Guide ## Installing HydePHP using Composer From 58e436bf07ee3022e62688545281b7df7c1e7e69 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 18:10:35 +0200 Subject: [PATCH 08/70] Slim down index page --- index.md | 77 ++++++-------------------------------------------------- 1 file changed, 8 insertions(+), 69 deletions(-) diff --git a/index.md b/index.md index bd169d7..32c90f7 100644 --- a/index.md +++ b/index.md @@ -13,26 +13,22 @@ 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 From 98a5868c0410c45b87564e12f7934bdd1664a20e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Mon, 9 May 2022 19:46:18 +0200 Subject: [PATCH 09/70] Create console-commands.md --- console-commands.md | 208 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 console-commands.md diff --git a/console-commands.md b/console-commands.md new file mode 100644 index 0000000..90046f7 --- /dev/null +++ b/console-commands.md @@ -0,0 +1,208 @@ +# 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 Hyde CLI is based on Artisan after all! + +## Hyde Commands + +To use the HydeCLI, run `php hyde` from your project directory followed by a command. + +### Got stuck? The CLI can help. + +You can always run the base command `php hyde`, or `php hyde list`, to show the list of commands. + +```bash +php hyde # or `php hyde list` +``` + +You can also always add `--help` to a command to show detailed usage information. +```bash +php hyde --help +``` + + +### Initialize a new Hyde project +```bash +php hyde install +``` + +While Hyde doesn't need much configuration to get started, this command speeds up the little there is. + +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. + + +### Build the static site +```bash +php hyde build +``` + +Maybe the most important command is the Build command, which -- you guessed it -- builds your static site! + +**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 +``` + +### Build a single file +```bash +php hyde rebuild +``` +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. + +**Requires the following Arguments:** +``` +path The relative file path +``` + +**Example:** +```bash +php hyde rebuild _posts/hello-world.md +``` + +### Start the realtime compiler. +```bash +php hyde serve +``` + +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 and proxy +the resulting HTML and any media files to your browser. + +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). + +**Supports the following options:** +``` +--port[=PORT] [default: "8080"] +--host[=HOST] [default: "localhost"] +``` + + +### Scaffold a new blog post file +```bash +php hyde make:post +``` + +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. + + +### Scaffold a new page file +```bash +php hyde make:page [--type=TYPE] +``` + +The `make:page` command is similar to the `make:post` command and lets you quickly +create one of the following page types: + +- **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. + +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 +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 +``` + +### Publish a default homepage +```bash +php hyde publish:homepage [<name>] +``` + +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. + +On a fresh install the page 'welcome' is installed. +However, you can use the this command to publish another one. +If you have modified the file, you will need to supply the --force option to overwrite it. + +The available homepages are: + +- **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. + + +### Publish the Hyde Blade views +```bash +php hyde publish:views [<category>] +``` + +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 directory and the resources directory in the Framework package. + +<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> + +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. + +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. + +You can supply the category name directly to the command, otherwise you will be prompted to select one. + +<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 +``` + +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. + +<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 +php hyde validate +``` + +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 From b7e9382294a89249c795a9c5057543590c165a7a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Mon, 9 May 2022 19:46:45 +0200 Subject: [PATCH 10/70] Remove old files from dev branch --- .github/workflows/deploy.yml | 41 -------- 0.1x/README.markdown | 5 - 0.1x/console-commands.md | 158 ----------------------------- 0.1x/customization.md | 109 -------------------- 0.1x/directory-structure.md | 87 ---------------- 0.1x/getting-started.md | 188 ----------------------------------- 0.1x/index.md | 102 ------------------- 0.1x/installation.md | 68 ------------- 0.1x/managing-assets.md | 67 ------------- 0.1x/updating-hyde.md | 79 --------------- _drafts/how-does-it-work.md | 13 --- 11 files changed, 917 deletions(-) delete mode 100644 .github/workflows/deploy.yml delete mode 100644 0.1x/README.markdown delete mode 100644 0.1x/console-commands.md delete mode 100644 0.1x/customization.md delete mode 100644 0.1x/directory-structure.md delete mode 100644 0.1x/getting-started.md delete mode 100644 0.1x/index.md delete mode 100644 0.1x/installation.md delete mode 100644 0.1x/managing-assets.md delete mode 100644 0.1x/updating-hyde.md delete mode 100644 _drafts/how-does-it-work.md diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml deleted file mode 100644 index 98a68b9..0000000 --- a/.github/workflows/deploy.yml +++ /dev/null @@ -1,41 +0,0 @@ -# This is a basic workflow to help you get started with Actions -name: CI Deploy - -# Controls when the workflow will run -on: - # Triggers the workflow on push or pull request events but only for the master branch - push: - branches: [ master ] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -permissions: - contents: read - -# A workflow run is made up of one or more jobs that can run sequentially or in parallel -jobs: - # This workflow contains a single job called "deploy" - deploy: - # The type of runner that the job will run on - runs-on: ubuntu-latest - - # Steps represent a sequence of tasks that will be executed as part of the job - steps: - # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - - uses: actions/checkout@v3 - - # Copy over the root Markdown files into a new directory - - name: Copy Markdown files - run: mkdir files && cp *.md files - - - name: Push Markdown files - uses: cpina/github-action-push-to-another-repository@main - env: - API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }} - with: - source-directory: 'files' - target-directory: '_docs' - destination-github-username: 'hydephp' - destination-repository-name: 'DocsCI' - target-branch: master diff --git a/0.1x/README.markdown b/0.1x/README.markdown deleted file mode 100644 index 4b95663..0000000 --- a/0.1x/README.markdown +++ /dev/null @@ -1,5 +0,0 @@ -# Hyde Documentation -[![CI Deploy](https://github.com/hydephp/docs/actions/workflows/deploy.yml/badge.svg)](https://github.com/hydephp/docs/actions/workflows/deploy.yml) - -This is the source for the HydePHP Documentation. Updates to this repo are automatically propagated to the [DocsCI pipeline](https://github.com/hydephp/DocsCI) which uses Hyde to build the static site hosted at -https://hydephp.github.io/docs diff --git a/0.1x/console-commands.md b/0.1x/console-commands.md deleted file mode 100644 index 89eaa69..0000000 --- a/0.1x/console-commands.md +++ /dev/null @@ -1,158 +0,0 @@ -# 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. - -To help in developing your site we have also included a few scripts in the `package.json`. - -## 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. - -You can always run the base command `php hyde` to show the list of commands: -```bash -// torchlight! {"lineNumbers": false} - __ __ __ ___ __ _____ - / // /_ _____/ /__ / _ \/ // / _ \ - / _ / // / _ / -_) ___/ _ / ___/ - /_//_/\_, /\_,_/\__/_/ /_//_/_/ - /___/ - - v0.1.0-pre - - USAGE: hyde <command> [options] [arguments] - - 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 - -### The Build Command - -Maybe the most important command is the Build command, which -- you guessed it -- builds your static site! - -```bash -php hyde build -``` - -> 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 - -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. - -Let's solve that! Use the `php hyde rebuild <file>` command! - -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? - -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. - -```bash -php hyde make:post -``` - -> Tip: To overwrite existing files, supply the --force flag (at your own risk of course) - -### The Publish Command -If you are coming from Laravel, you are probably familiar with the Artisan vendor:publish command. - -Hyde has a similar command that allows you to publish various pages. - -#### 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. -```bash -php hyde publish:config [--force] -``` - -#### 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 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. - -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. - -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. - -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. - -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 -```bash -php hyde publish:views -``` -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 Validate Command -Hyde ships with a very useful command that runs a series of checks to validate your setup and catch any potential issues. - -The command is `php hyde validate` and gives an output similar to this -```bash -// torchlight! {"lineNumbers": false} -$ php hyde validate - -Running validation tests! - - PASS CheckForPageConflictsTest - ✓ check for conflicts between blade and markdown pages - - PASS CheckThatAnIndexFileExistsTest - ✓ check that an index file exists - - WARN CheckThatDocumentationPagesHaveAnIndexPageTest - ! check that documentation pages have an index page - → Could not find an index.md file in the _docs directory! - - PASS CheckThatFrontendAssetsExistTest - ✓ check that app.css exist - ✓ check that tailwind.css exist - - - Tests: 1 warnings, 4 passed - Time: 0.31s - -All done! -``` - -## NPM Commands -The NPM commands are used to compile the frontend CSS assets and to run the realtime compiler. - -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! - -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). - -## Commands for the frontend assets -- **`npm run dev`** - Compiles the Tailwind -- **`npm run prod`** - Compiles the Tailwind and minifies the output. - - -## Realtime compiler AKA Watching files for changes - -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. - -The real-time viewer also uses Browsersync which starts a local web server and automatically refreshes your pages once they are changed. - -**To start the preview run** -```bash -npm run watch -``` -A browser page should automatically be opened. If not, just navigate to http://localhost:3000/. diff --git a/0.1x/customization.md b/0.1x/customization.md deleted file mode 100644 index 96e9ad1..0000000 --- a/0.1x/customization.md +++ /dev/null @@ -1,109 +0,0 @@ -# Customizing your Site - -<p class="lead"> -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. - -In this config file, you can customize the site name, what modules to enable, and programmatically customize the navigation menu and documentation sidebar. - -Here are a few examples of the config options. - -### Modules -With a concept directly inspired by [Laravel Jetstream](https://jetstream.laravel.com/), this setting allows you to toggle various modules. -```php -// torchlight! {"lineNumbers": false} -'features' => [ - Features::blogPosts(), - Features::bladePages(), - Features::markdownPages(), - // Features::documentationPages(), -], -``` - -### Footer -The footer can be customized using Markdown, and even disabled completely. - -```php -// torchlight! {"lineNumbers": false} -'footer' => [ - 'enabled' => true, - 'markdown' => 'Site built with [HydePHP](https://github.com/hydephp/hyde).' -], -``` - -### Navigation Menu & Sidebar -One of my (the author's) 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` or `readme.md` in the `_docs` directory. - -#### Reordering 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 hyde config, there is an array just for this. When the sidebar is generated it looks through this config array. If a slug is found here it will get priority according to its position in the list. If a page does not exist in the list they get priority 999, which puts them last. - -Let's see an example: -```php -// torchlight! {"lineNumbers": false} -// This is the default values in the config. It puts the readme.md first in order. -'documentationPageOrder' => [ - 'readme', // This is the first entry, so it gets the priority 0 - 'installation', // This gets priority 1 - 'getting-started', // And this gets priority 2 - // Any other pages not listed will get priority 999 -] -``` - -> Navigation menu items will be ordered in the same way in a coming update, but for now, they can be reordered by overriding them which you can learn in the next section. - -#### Adding Custom Navigation Menu Links -> Until the navigation link order is implemented, you can use this feature to reorder navigation menu items. - -The links are added in the config/hyde.php file, and the syntax for adding custom links is documented in the config. Here are some examples: - -```php -// torchlight! {"lineNumbers": false} -// External link -[ - 'title' => 'GitHub', - 'destination' => 'https://github.com/hydephp/hyde', - 'priority' => 1200, -], - -// Internal link (Hyde automatically resolves relative paths) -[ - 'title' => 'Featured Blog Post', - 'slug' => 'posts/hello-world', - // The 'priority' is not required. -] -``` - -#### Removing 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 slug to the blacklist. As you can see, the `404` page has already been filled in for you. - -```php -'navigationMenuBlacklist' => [ - '404' -], -``` - -> Tip: You can publish the included 404 page using `php hyde publish:404`! - -## Blade Views -Hyde uses the Laravel templating system called Blade. Most parts have been extracted into components to be customized easily. - -> Before editing Blade views you should familiarize yourself with how they work in the official documentation https://laravel.com/docs/9.x/blade. - -To edit the default component you need to publish them first using the `hyde publish:views` command. - -## 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. - -Please see the chapter in the [Getting Started](getting-started.html) page to learn more. diff --git a/0.1x/directory-structure.md b/0.1x/directory-structure.md deleted file mode 100644 index afbed1c..0000000 --- a/0.1x/directory-structure.md +++ /dev/null @@ -1,87 +0,0 @@ -# Directory Structure - -To take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure. - -## Tree Overview -``` -// torchlight! {"lineNumbers": false} -├── _docs -├── _media -├── _pages -├── _posts -├── _site -├── config -├── resources -│ └── frontend -│ └── views -│ ├── components -│ └── layouts -``` - -## 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 diff --git a/0.1x/getting-started.md b/0.1x/getting-started.md deleted file mode 100644 index 7deb748..0000000 --- a/0.1x/getting-started.md +++ /dev/null @@ -1,188 +0,0 @@ ---- ---- -# 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! ---- -``` -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 -![Image Alt](../media/image.png "Image Title") # 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 -``` - -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) - diff --git a/0.1x/index.md b/0.1x/index.md deleted file mode 100644 index e0f648c..0000000 --- a/0.1x/index.md +++ /dev/null @@ -1,102 +0,0 @@ -# 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/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> -</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 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. - -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: - -- 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. - - -## Installation Quick Start -> Full installation guide is at https://hydephp.github.io/docs/master/installation.html - -The recommended method of installation is using Composer. - -```bash -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 diff --git a/0.1x/installation.md b/0.1x/installation.md deleted file mode 100644 index 3cc5c6b..0000000 --- a/0.1x/installation.md +++ /dev/null @@ -1,68 +0,0 @@ -# Installation Guide - -## 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! - - diff --git a/0.1x/managing-assets.md b/0.1x/managing-assets.md deleted file mode 100644 index 4badc0d..0000000 --- a/0.1x/managing-assets.md +++ /dev/null @@ -1,67 +0,0 @@ -# Managing and Compiling Assets - -## Intro -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 where base styles and scripts are included through [HydeFront](https://github.com/hydephp/hydefront) which adds accessibility and mobile support as well as interactions for dark mode switching and navigation and sidebar interactions. - -HydeFront is split into two files, `hyde.css` and `hyde.js`. These are loaded in the default Blade views using the [jsDelivr CDN](https://www.jsdelivr.com/package/npm/hydefront). This is the recommended way to load the base styles as the [Hyde Framework](https://github.com/hydephp/framework) automatically makes sure that the correct HydeFront version for the current version of Hyde is loaded. You can disable the CDN in the `config/hyde.php` file by setting `'loadHydeAssetsUsingCDN'` to `false`. - -The bulk of the frontend is built with [TailwindCSS](https://tailwindcss.com/). To get you started, when installing Hyde, all the Tailwind styles you need come precompiled and minified into `_media/app.css`. - -## Some extra information, and answers to possible questions - -### Do I have to use NPM to use Hyde? -No. NPM is optional as all the compiled styles you need are already installed. You only need NPM if you want to compile your own styles. - -### When do I need to compile assets? - -#### When customizing -If you want to customize the Tailwind settings or add custom styles, you will need to take care of compiling the styles yourself. - -#### When adding new classes -The `_media/app.css` file that comes with Hyde contains TailwindCSS for all classes that are used in the default Blade views, but nothing more. - -If you customize the Blade views and add new classes, or if you add new classes in Blade-based pages, you may need to compile the assets yourself to get the new styles. - -If you stick to using Markdown based pages, you don't need to compile anything. - -## How are assets stored and managed? - -Currently, 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. - -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, though you may choose to exclude the compiled files from the `_media` folder if you want to. - -You are of course free to modify this behavior by editing the `webpack.mix.js` file. - -## 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](https://laravel-mix.com/) (which is a wrapper for [webpack](https://webpack.js.org/)) 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. 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. diff --git a/0.1x/updating-hyde.md b/0.1x/updating-hyde.md deleted file mode 100644 index a287b05..0000000 --- a/0.1x/updating-hyde.md +++ /dev/null @@ -1,79 +0,0 @@ -# Updating Hyde - -## While Hyde is in beta, stuff can change rapidly. -This guide will help you update Hyde to the latest version. It is recommended to back up your source files before updating. - -## Updating Hyde/Framework - -Run the following command from your Hyde/Hyde installation: -```bash -composer update hyde/framework -``` - -Next, follow the post-update instructions for Hyde/Hyde. - -## Updating Hyde/Hyde -When updating an existing installation, first ensure you have a Git backup of your source files to revert the update. - -Depending on how you installed Hyde, there are a few different ways to update it. - -### Using Git -Make sure you have a remote set up for the repository. -```bash -git remote add upstream https://github.com/hydephp/hyde.git -``` - -Then pull the latest changes from the remote: -```bash -git pull upstream master -``` - -Next, follow the post-update instructions for Hyde/Hyde. - -### Manual Update -Since all resource files are in the content directories you can simply copy those files to the new location. - -If you have changed any other files, for example in the App directory, you will need to update those files manually as well. But if you have done that you probably know what you are doing. I hope. The same goes if you have created any custom blade components or have modified Hyde ones. - -Example CLI workflow, assuming the Hyde/Hyde project is stored as `my-project` in the home directory: -```bash -cd ~ -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 for Hyde/Hyde. 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 the files will be overwritten. However, since you should be using Git, you can take care of any merge conflicts that arise. - -```bash -php hyde update:configs -php hyde update:assets -``` - -If you have published any of the Hyde Blade components you will need to re-publish them. - -```bash -php hyde publish:views layouts -php hyde publish:views components -``` - -Next, re-build your site. - -```bash -php hyde build -``` - -And recompile your assets if applicable. - -```bash -npm install -npm run dev/prod -``` \ No newline at end of file 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. - From 353ffca766177958e3cd3309d8db34d495590cbb Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Mon, 9 May 2022 19:47:16 +0200 Subject: [PATCH 11/70] Create Readme --- readme.MARKDOWN | 1 + 1 file changed, 1 insertion(+) create mode 100644 readme.MARKDOWN diff --git a/readme.MARKDOWN b/readme.MARKDOWN new file mode 100644 index 0000000..994b290 --- /dev/null +++ b/readme.MARKDOWN @@ -0,0 +1 @@ +Hyde Documentation for versions series 0.20 and above (Work in progress) \ No newline at end of file From e2335487d79de1deb99e5d4343a45c59adff2b13 Mon Sep 17 00:00:00 2001 From: Caen De Silva <95144705+caendesilva@users.noreply.github.com> Date: Mon, 9 May 2022 19:47:50 +0200 Subject: [PATCH 12/70] Format markdown header --- readme.MARKDOWN | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.MARKDOWN b/readme.MARKDOWN index 994b290..6142cdd 100644 --- a/readme.MARKDOWN +++ b/readme.MARKDOWN @@ -1 +1 @@ -Hyde Documentation for versions series 0.20 and above (Work in progress) \ No newline at end of file +# Hyde Documentation for versions series 0.20 and above (Work in progress) From e64c65136e9909e4b4fee689a2b5210f84eaa6ad Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Mon, 9 May 2022 19:49:06 +0200 Subject: [PATCH 13/70] Remove "next steps" section --- quickstart.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/quickstart.md b/quickstart.md index a79e501..95f98fa 100644 --- a/quickstart.md +++ b/quickstart.md @@ -81,8 +81,3 @@ You can even use GitHub pages to host your site for free. That's what the Hyde w using a CI that automatically builds and deploys this site. -## Next steps - -Make sure you check out the [getting started](getting-started.html) page to learn how to use Hyde! - - From 169a9c63b123005b1223dc80cbf9c46bfd6346fa Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Mon, 9 May 2022 20:12:36 +0200 Subject: [PATCH 14/70] Update CLI section with link to further docs --- quickstart.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/quickstart.md b/quickstart.md index 95f98fa..d1cb4a5 100644 --- a/quickstart.md +++ b/quickstart.md @@ -12,10 +12,11 @@ composer create-project hyde/hyde --stability=dev ``` ## Using the Hyde CLI -The main way to interact with Hyde is through the HydeCLI. +The main way to interact with Hyde is through HydeCLI. + If you are familiar with Laravel Artisan you will feel right at home. -You access it through the command line with `php hyde <command>`. +Learn more about the HydeCLI in the [console commands](console-commands.html) documentation. ## Starting a development server From 8326c7aa2e2567c0eea426249997d496caaf269c Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Mon, 9 May 2022 23:05:09 +0200 Subject: [PATCH 15/70] Create creating-blog-posts.md --- creating-blog-posts.md | 237 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 creating-blog-posts.md diff --git a/creating-blog-posts.md b/creating-blog-posts.md new file mode 100644 index 0000000..bb34ad4 --- /dev/null +++ b/creating-blog-posts.md @@ -0,0 +1,237 @@ +--- +--- + +# 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> + +## 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 something awesome. + +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 + +It may be helpful to take a look at how the front matter data is +used so you can get a better understanding of how it works. + +Here is the compiled HTML created by Hyde with dynamically generated markup +data based on the front matter, config settings, and Hyde accessibility defaults. +This can look quite overwhelming, so we'll dig in deeper later on in the article. + +```html +<article aria-label="Article" id="https://hydephp.github.io/posts/my-new-post" itemtype="https://schema.org/Article"> + <meta itemprop="identifier" content="my-new-post"> + <meta itemprop="url" content="https://hydephp.github.io/posts/my-new-post"> + <header aria-label="Header section" role="doc-pageheader"> + <h1 itemprop="headline">My New Post</h1> + <div id="byline" aria-label="About the post" role="doc-introduction"> + Posted <time itemprop="dateCreated datePublished" datetime="2022-05-09T18:38:00+00:00" title="Monday May 9th, 2022, at 6:38pm">May 9th, 2022</time> + by author + <address itemprop="author" itemtype="https://schema.org/Person" aria-label="The post author"> + <span itemprop="name" aria-label="The author's name" title="@mr_hyde">Mr. Hyde</span> + </address> + in the category "blog" + </div> + </header> + <div aria-label="Article body" itemprop="articleBody"> + <h2>Write something awesome.</h2> + <p>Lorem ipsum dolor sit amet.</p> + </div> + <span class="sr-only">End of article</span> +</article> +``` + +## Supported Front Matter properties + +Now that we have a foundation of how Hyde uses front matter to create data-rich HTML markup, +let's take a look at the supported front matter properties and some usage examples. +Feel free to mix and match between them in your posts. + +### Quick Reference +Here is a quick reference with some examples. Duplicate properties showcase different ways to use the same property. + +```yaml +title: "My New Post" # (string) +description: "A short description" # (string) +category: blog # (string) +author: "Mr. Hyde" # (string: arbitrary name) +author: "mr_hyde" # (string: username defined in config/authors.yml) +author: # (array) + name: Mr. Hyde # (string) + username: mr_hyde # (string) + website: https://mrhyde.example.com # (string: URL/link to author) +date: "2022-05-09 18:38" # (string) +date: "2022-05-09" # (string) +image: image.jpg # (string: filename of image in `_media` directory) +image: https://example.com/media/image.jpg # (string: full URL of image) +image: # (array) + path: image.jpg # (string: filename of image in `_media` directory) + uri: https://example.com/media/image.jpg # (string: full URL of image) + title: Tooltip # (string) + description: Alt text # (string) + copyright: Copyright (c) 2022 # (string) + license: MIT # (string) + licenseUrl: https://example.org/licenses/MIT # (string: URL/link to license) + credit: https://example.org/photographers/mr_hyde # (string: URL/link to image author) + author: mr_hyde # (string: name/username of image author) +``` + +### Post Title + +#### Example +```yaml +title: "My New Post" # (string) +``` + +#### Used in +- Article `<H1>` element +- HTML `<title>` tag +- Meta `og:title` property +- Article `headline` property +- Blog post excerpt title + + +### Post Description + +#### Example +```yaml +description: "A short description used in previews and SEO" # (string) +``` + +#### Used in +- Meta `description` property +- Blog post excerpts + +### Post Category + +#### Example + +```yaml +category: blog # (string) +``` + +#### Used in +- Meta `keywords` property +- Article category in the byline + +### Post Author + +#### Examples + +```yaml +author: "Mr. Hyde" # Arbitrary name (string) +``` + +```yaml +author: mr_hyde # Username for author defined in the config file `authors.yml` (string) +``` + +```yaml +author: # Array of author data (array) + name: "Mr. Hyde" # (string) + username: mr_hyde # (string) + website: https://mrhyde.example.com # (string) +``` + +#### Used in +- Article `<address>` element +- Meta `author` property +- Article `author` property, which can contain the following if present in config or front matter array: + - Itemtype `https://schema.org/Person` + - `URL` property and `rel link` to author's website + + +### Post Date + +#### Example + +```yaml +date: "2022-01-01 12:00" # (string: YYYY-MM-DD [HH:MM]) +``` + +#### Used in +- Article `<time>` element with `datetime` attribute and `dateCreated` `datePublished` properties +- Meta `og:article:published_time` property + +### Featured Post Image + +#### Basic usage example + +```yaml +image: image.jpg # (string of file in the `_media` directory) +``` + +```yaml +image: https://cdn.example.com/image.jpg # (string of full URL starting with `http(s)://`) +``` + +#### Advanced usage example + +The image can also be set as an array which supports a whole set of options. + +> See [posts/introducing-images](https://hydephp.github.io/posts/introducing-images.html) +> for a detailed blog post with examples and schema information! + +```yaml +image: + description: "Image of a small kitten with its head tilted, sitting in a basket weaved from nature material." + title: "Kitten Gray Kitty [sic]" + uri: https://raw.githubusercontent.com/hydephp/hydephp.github.io/gh-pages/media/kitten-756956_640-min.jpg + copyright: Copyright (c) 2022 + license: Pixabay License + licenseUrl: https://pixabay.com/service/license/ + credit: https://pixabay.com/photos/kitten-gray-kitty-kitty-756956/ + author: Godsgirl_madi +``` + +#### Used in +- Article `doc-cover` image +- If supplied with extra data, the following can be added to the `ImageObject` property: + - Alt text for screenreaders using the `image.description` value + - Tooltip using `title=""` attribute + - `Person` object for the image author with `creator` property + - `copyrightNotice` property + - `license` property + - If supplied with a URL, a `rel="license` link is added + - `image` (url) property + - Meta `text` property + - Meta `name` property + - Meta `og:image` property +- All of the array data is constructed into a dynamic fluent string used in the `<figcaption>` element \ No newline at end of file From cfa23dfa419091b72004a9ea76d62ab8b84b3f2a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 10:17:53 +0200 Subject: [PATCH 16/70] Change heading Featured Post Image to Featured Image --- creating-blog-posts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index bb34ad4..8890662 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -190,7 +190,7 @@ date: "2022-01-01 12:00" # (string: YYYY-MM-DD [HH:MM]) - Article `<time>` element with `datetime` attribute and `dateCreated` `datePublished` properties - Meta `og:article:published_time` property -### Featured Post Image +### Featured Image #### Basic usage example From 13c2bd3ddf52a3e95374a4c8616b0db85412fda3 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 10:54:47 +0200 Subject: [PATCH 17/70] Add Best Practices and Hyde Expectations --- creating-blog-posts.md | 43 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index 8890662..054adeb 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -22,6 +22,47 @@ Learn more about scaffolding posts, and other files, in the [console commands](c <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 + +**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. + +- Front matter is stores 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 encouranged 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, @@ -39,7 +80,7 @@ author: Mr. Hyde date: 2022-05-09 18:38 --- -## Write something awesome. +## Write your Markdown here Lorem ipsum dolor sit amet, consectetur adipisicing elit. Autem aliquid alias explicabo consequatur similique, From f4368e2ff6a73c2226485eb021f51eb8c4a8efc5 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 11:15:47 +0200 Subject: [PATCH 18/70] Remove used in sections --- creating-blog-posts.md | 94 ++++++++++-------------------------------- 1 file changed, 22 insertions(+), 72 deletions(-) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index 054adeb..ba11c1a 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -87,36 +87,26 @@ Autem aliquid alias explicabo consequatur similique, animi distinctio earum ducimus minus, magnam. ``` -## How the Front Matter is used - -It may be helpful to take a look at how the front matter data is -used so you can get a better understanding of how it works. - -Here is the compiled HTML created by Hyde with dynamically generated markup -data based on the front matter, config settings, and Hyde accessibility defaults. -This can look quite overwhelming, so we'll dig in deeper later on in the article. - -```html -<article aria-label="Article" id="https://hydephp.github.io/posts/my-new-post" itemtype="https://schema.org/Article"> - <meta itemprop="identifier" content="my-new-post"> - <meta itemprop="url" content="https://hydephp.github.io/posts/my-new-post"> - <header aria-label="Header section" role="doc-pageheader"> - <h1 itemprop="headline">My New Post</h1> - <div id="byline" aria-label="About the post" role="doc-introduction"> - Posted <time itemprop="dateCreated datePublished" datetime="2022-05-09T18:38:00+00:00" title="Monday May 9th, 2022, at 6:38pm">May 9th, 2022</time> - by author - <address itemprop="author" itemtype="https://schema.org/Person" aria-label="The post author"> - <span itemprop="name" aria-label="The author's name" title="@mr_hyde">Mr. Hyde</span> - </address> - in the category "blog" - </div> - </header> - <div aria-label="Article body" itemprop="articleBody"> - <h2>Write something awesome.</h2> - <p>Lorem ipsum dolor sit amet.</p> - </div> - <span class="sr-only">End of article</span> -</article> +### 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 encouranged 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 @@ -161,14 +151,6 @@ image: # (array) title: "My New Post" # (string) ``` -#### Used in -- Article `<H1>` element -- HTML `<title>` tag -- Meta `og:title` property -- Article `headline` property -- Blog post excerpt title - - ### Post Description #### Example @@ -176,10 +158,6 @@ title: "My New Post" # (string) description: "A short description used in previews and SEO" # (string) ``` -#### Used in -- Meta `description` property -- Blog post excerpts - ### Post Category #### Example @@ -188,10 +166,6 @@ description: "A short description used in previews and SEO" # (string) category: blog # (string) ``` -#### Used in -- Meta `keywords` property -- Article category in the byline - ### Post Author #### Examples @@ -211,14 +185,6 @@ author: # Array of author data (array) website: https://mrhyde.example.com # (string) ``` -#### Used in -- Article `<address>` element -- Meta `author` property -- Article `author` property, which can contain the following if present in config or front matter array: - - Itemtype `https://schema.org/Person` - - `URL` property and `rel link` to author's website - - ### Post Date #### Example @@ -227,10 +193,6 @@ author: # Array of author data (array) date: "2022-01-01 12:00" # (string: YYYY-MM-DD [HH:MM]) ``` -#### Used in -- Article `<time>` element with `datetime` attribute and `dateCreated` `datePublished` properties -- Meta `og:article:published_time` property - ### Featured Image #### Basic usage example @@ -262,17 +224,5 @@ image: author: Godsgirl_madi ``` -#### Used in -- Article `doc-cover` image -- If supplied with extra data, the following can be added to the `ImageObject` property: - - Alt text for screenreaders using the `image.description` value - - Tooltip using `title=""` attribute - - `Person` object for the image author with `creator` property - - `copyrightNotice` property - - `license` property - - If supplied with a URL, a `rel="license` link is added - - `image` (url) property - - Meta `text` property - - Meta `name` property - - Meta `og:image` property -- All of the array data is constructed into a dynamic fluent string used in the `<figcaption>` element \ No newline at end of file +The image is used as the post cover image, and all the array data is constructed +into a dynamic fluent caption, and injected into post and page metadata. \ No newline at end of file From 83a26d6aaac1a485abfa20586554ab90953a2c72 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 12:08:39 +0200 Subject: [PATCH 19/70] Rewrite schema section to be more readable and clear --- creating-blog-posts.md | 133 +++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 79 deletions(-) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index ba11c1a..87775c8 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -111,118 +111,93 @@ array: ## Supported Front Matter properties -Now that we have a foundation of how Hyde uses front matter to create data-rich HTML markup, -let's take a look at the supported front matter properties and some usage examples. -Feel free to mix and match between them in your posts. +### Post Front Matter Schema -### Quick Reference -Here is a quick reference with some examples. Duplicate properties showcase different ways to use the same property. +Here is a quick reference of the supported front matter properties.<br> +Keep on reading to see further explanations, details, and examples. -```yaml -title: "My New Post" # (string) -description: "A short description" # (string) -category: blog # (string) -author: "Mr. Hyde" # (string: arbitrary name) -author: "mr_hyde" # (string: username defined in config/authors.yml) -author: # (array) - name: Mr. Hyde # (string) - username: mr_hyde # (string) - website: https://mrhyde.example.com # (string: URL/link to author) -date: "2022-05-09 18:38" # (string) -date: "2022-05-09" # (string) -image: image.jpg # (string: filename of image in `_media` directory) -image: https://example.com/media/image.jpg # (string: full URL of image) -image: # (array) - path: image.jpg # (string: filename of image in `_media` directory) - uri: https://example.com/media/image.jpg # (string: full URL of image) - title: Tooltip # (string) - description: Alt text # (string) - copyright: Copyright (c) 2022 # (string) - license: MIT # (string) - licenseUrl: https://example.org/licenses/MIT # (string: URL/link to license) - credit: https://example.org/photographers/mr_hyde # (string: URL/link to image author) - author: mr_hyde # (string: name/username of image author) -``` +| **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_ | -### Post Title -#### Example -```yaml -title: "My New Post" # (string) -``` +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. -### Post Description +### Title -#### Example ```yaml -description: "A short description used in previews and SEO" # (string) +title: "My New Post" ``` -### Post Category -#### Example +### Description ```yaml -category: blog # (string) +description: "A short description used in previews and SEO" ``` -### Post Author -#### Examples +### Category ```yaml -author: "Mr. Hyde" # Arbitrary name (string) +category: blog +category: "My favorite recipes" ``` -```yaml -author: mr_hyde # Username for author defined in the config file `authors.yml` (string) -``` + +### Date ```yaml -author: # Array of author data (array) - name: "Mr. Hyde" # (string) - username: mr_hyde # (string) - website: https://mrhyde.example.com # (string) +date: "2022-01-01 12:00" +date: "2022-01-01" ``` -### Post Date -#### Example +### Author ```yaml -date: "2022-01-01 12:00" # (string: YYYY-MM-DD [HH:MM]) +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 ``` -### Featured Image +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. -#### Basic usage example +### Image ```yaml -image: image.jpg # (string of file in the `_media` directory) -``` - -```yaml -image: https://cdn.example.com/image.jpg # (string of full URL starting with `http(s)://`) +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" ``` -#### Advanced usage example +When supplying an image with a local image path, the image is expected to be stored in the `_media/` directory. -The image can also be set as an array which supports a whole set of options. +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) +> See [posts/introducing-images](https://hydephp.github.io/posts/introducing-images.html) > for a detailed blog post with examples and schema information! - -```yaml -image: - description: "Image of a small kitten with its head tilted, sitting in a basket weaved from nature material." - title: "Kitten Gray Kitty [sic]" - uri: https://raw.githubusercontent.com/hydephp/hydephp.github.io/gh-pages/media/kitten-756956_640-min.jpg - copyright: Copyright (c) 2022 - license: Pixabay License - licenseUrl: https://pixabay.com/service/license/ - credit: https://pixabay.com/photos/kitten-gray-kitty-kitty-756956/ - author: Godsgirl_madi -``` - -The image is used as the post cover image, and all the array data is constructed -into a dynamic fluent caption, and injected into post and page metadata. \ No newline at end of file +{ .info } From 9b5eff15a1732a824996702b4aa4ba24cf4f3cfe Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 12:17:14 +0200 Subject: [PATCH 20/70] Add output path to filenames section --- creating-blog-posts.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index 87775c8..7558532 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -29,10 +29,11 @@ to keep in mind when creating blog posts so that you don't get unexpected result ### Filenames -- Markdown post files are stored in the `_posts` directory. +- 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 From c64c59938868f7c0528372a69f1b0dc7db037dfa Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 12:28:36 +0200 Subject: [PATCH 21/70] Remove <br> tag --- creating-blog-posts.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index 7558532..c1f0a31 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -114,9 +114,10 @@ array: ### Post Front Matter Schema -Here is a quick reference of the supported front matter properties.<br> +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" | From 5f741ac64409439606448298fb66b9474b472f75 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 13:16:38 +0200 Subject: [PATCH 22/70] Create creating-static-pages.md --- creating-static-pages.md | 137 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 creating-static-pages.md diff --git a/creating-static-pages.md b/creating-static-pages.md new file mode 100644 index 0000000..856acb6 --- /dev/null +++ b/creating-static-pages.md @@ -0,0 +1,137 @@ +--- +--- + +# Creating Static Pages + +## Introduction to Hyde Pages + +Hyde offers two ways to create static pages: +**Markdown pages** which are perfect for simple pagesthat focuses heavily on the content, +and **Blade pages** which are perfect for more complex pages where you want full control over the HMTL, +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 + +## Markdown Pages + +Markdown pages are the easiest way to create static pages, and are similar to [blog posts](creating-blog-posts.html). +You may want to read that page first as it explains [how front matter works](creating-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` + +``` +--- +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 searcing +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. + +### Compiled result + +Here's what a basic Markdown page looks like with some [Lorem Markdownum](https://jaspervdj.be/lorem-markdownum/). + +![Hyde Markdown Page](https://cdn.jsdelivr.net/gh/hydephp/DocsCI@ab946cbdd4d7fe87a23840868c2cc11f9855ee14/_media/a0244ea6-d5ce-4d30-b806-cd7a480303e9.png) + +As you can see, it looks great and works 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. + + +**Benefits of using Markdown pages include:** +- Easily created and updated +- Very fast to create simple and lightweight pages +- Suited for content heavy pages such as "about", "contact", "terms", etc. + +**Drawbacks of using Markdown pages include:** +- Not as flexible as Blade pages + +## 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. + +**Benefits of using Blade pages include:** +- Full control over the HTML +- Use the defauly app layout or create your own +- Use Blade templates and components to keep code DRY +- Use arbitrary PHP right in the page to create dynamic content +- Access to all Blade helper directives like @foreach, @if, etc. + +**Drawbacks of using Blade pages include:** +- Takes longer to create as as you need to write the markup +- You may need to [recompile your CSS](managing-assets.html) if adding new Tailwind classes + + +### 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. + +``` +@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 +``` + +### Using plain HTML + +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. \ No newline at end of file From cbd1356fc9e54dd8654638ecfad9fc821d6b3cdb Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 13:35:34 +0200 Subject: [PATCH 23/70] Add When to use which? section --- creating-static-pages.md | 60 +++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/creating-static-pages.md b/creating-static-pages.md index 856acb6..cbfa818 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -26,6 +26,37 @@ to keep in mind when creating blog posts so that you don't get unexpected result - Your page will be stored in `_site/<slug>.html` - Blade pages will override any Markdown pages with the same filename when compiled +### 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. + ## Markdown Pages Markdown pages are the easiest way to create static pages, and are similar to [blog posts](creating-blog-posts.html). @@ -64,24 +95,6 @@ for the first level one heading (`# Page Title`), and if that fails, it will gen In the future, more front matter options such as page descriptions and meta tags will be supported. -### Compiled result - -Here's what a basic Markdown page looks like with some [Lorem Markdownum](https://jaspervdj.be/lorem-markdownum/). - -![Hyde Markdown Page](https://cdn.jsdelivr.net/gh/hydephp/DocsCI@ab946cbdd4d7fe87a23840868c2cc11f9855ee14/_media/a0244ea6-d5ce-4d30-b806-cd7a480303e9.png) - -As you can see, it looks great and works 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. - - -**Benefits of using Markdown pages include:** -- Easily created and updated -- Very fast to create simple and lightweight pages -- Suited for content heavy pages such as "about", "contact", "terms", etc. - -**Drawbacks of using Markdown pages include:** -- Not as flexible as Blade pages ## Blade Pages @@ -90,17 +103,6 @@ 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. -**Benefits of using Blade pages include:** -- Full control over the HTML -- Use the defauly app layout or create your own -- Use Blade templates and components to keep code DRY -- Use arbitrary PHP right in the page to create dynamic content -- Access to all Blade helper directives like @foreach, @if, etc. - -**Drawbacks of using Blade pages include:** -- Takes longer to create as as you need to write the markup -- You may need to [recompile your CSS](managing-assets.html) if adding new Tailwind classes - ### Scaffolding Blade Pages We can scaffold Blade pages using the same CLI command as Markdown pages, however, From ae46f925e537c1801e4077f87af86b70c210e25d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 13:41:09 +0200 Subject: [PATCH 24/70] Update headings --- creating-static-pages.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/creating-static-pages.md b/creating-static-pages.md index cbfa818..bdb2bb6 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -26,13 +26,13 @@ to keep in mind when creating blog posts so that you don't get unexpected result - Your page will be stored in `_site/<slug>.html` - Blade pages will override any Markdown pages with the same filename when compiled -### When to use which? +## 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 +### Comparison | Markdown | Blade | |-----------------------------------------------------|------------------------------------------------------------------------------------------| @@ -45,7 +45,7 @@ If you are comfortable with it, and have the need for it, use Blade to create mo | | ➖ You may need to [recompile your CSS](managing-assets.html) if you add Tailwind classes | -#### Live Demos +### Live Demos The Hyde website ([hydephp.github.io](https://hydephp.github.io/)) uses both Markdown and Blade pages. @@ -57,7 +57,7 @@ While a photo gallery could be used in a Markdown page, here I opted to use a Bl 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. -## Markdown Pages +## Creating Markdown Pages Markdown pages are the easiest way to create static pages, and are similar to [blog posts](creating-blog-posts.html). You may want to read that page first as it explains [how front matter works](creating-blog-posts.html#supported-front-matter-properties) @@ -96,7 +96,7 @@ for the first level one heading (`# Page Title`), and if that fails, it will gen In the future, more front matter options such as page descriptions and meta tags will be supported. -## Blade Pages +## 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. From be91f2353969ae303c8cae9cce376055fbd3f8d5 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 13:47:02 +0200 Subject: [PATCH 25/70] Change HTML heading to blockquote tip --- creating-static-pages.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/creating-static-pages.md b/creating-static-pages.md index bdb2bb6..b9f76a3 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -133,7 +133,5 @@ if you don't want to use the scaffolding command. @endsection ``` -### Using plain HTML - -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. \ No newline at end of file +> 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. \ No newline at end of file From cabe97783b28e4d84f3e6f2656b908a93a69ec9b Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 13:49:09 +0200 Subject: [PATCH 26/70] Add code block language types --- creating-static-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/creating-static-pages.md b/creating-static-pages.md index b9f76a3..e63ce8e 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -74,7 +74,7 @@ php hyde make:page "Page Title" This will create the following file saved as `_pages/page-title.md` -``` +```markdown --- title: Page Title --- @@ -121,7 +121,7 @@ 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") From d7c8569abed11688cf0b7b6317610c88cd4b13fe Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 13:50:01 +0200 Subject: [PATCH 27/70] Reorder sections --- creating-static-pages.md | 65 ++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 32 deletions(-) diff --git a/creating-static-pages.md b/creating-static-pages.md index e63ce8e..06f1fd9 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -26,37 +26,6 @@ to keep in mind when creating blog posts so that you don't get unexpected result - Your page will be stored in `_site/<slug>.html` - Blade pages will override any Markdown pages with the same filename when compiled -## 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. - ## Creating Markdown Pages Markdown pages are the easiest way to create static pages, and are similar to [blog posts](creating-blog-posts.html). @@ -134,4 +103,36 @@ if you don't want to use the scaffolding command. ``` > 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. \ No newline at end of file +> 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. From 6bf130aad647a42721bed6df9ae97d8b09e429bd Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 15:03:24 +0200 Subject: [PATCH 28/70] Fix spacing typo --- creating-static-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/creating-static-pages.md b/creating-static-pages.md index 06f1fd9..7b29505 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -29,7 +29,7 @@ to keep in mind when creating blog posts so that you don't get unexpected result ## Creating Markdown Pages Markdown pages are the easiest way to create static pages, and are similar to [blog posts](creating-blog-posts.html). -You may want to read that page first as it explains [how front matter works](creating-blog-posts.html#supported-front-matter-properties) +You may want to read that page first as it explains [how front matter works](creating-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`. From f2dea85b990d6f19ed32a3f5c9b7489ba16a6018 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 16:01:43 +0200 Subject: [PATCH 29/70] Create creating-documentation-pages.md --- creating-documentation-pages.md | 190 ++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 creating-documentation-pages.md diff --git a/creating-documentation-pages.md b/creating-documentation-pages.md new file mode 100644 index 0000000..84d3cee --- /dev/null +++ b/creating-documentation-pages.md @@ -0,0 +1,190 @@ +--- +--- + +# 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 be used as the sidebar header + - You can even [customize the order and labels](#sidebar-customization) 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](extensions.html) 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-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](creating-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 overriden. + + +| 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/documentation-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/documentation-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 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/documentation-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, +], +``` + From bca68d8f58b0de4c1015dacdf5b68b1da015115c Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 16:27:07 +0200 Subject: [PATCH 30/70] Remove unintended backticks --- creating-documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/creating-documentation-pages.md b/creating-documentation-pages.md index 84d3cee..568a211 100644 --- a/creating-documentation-pages.md +++ b/creating-documentation-pages.md @@ -126,7 +126,7 @@ label: "My Custom Sidebar Label" You can hide items from the sidebar by adding the `hidden` property to the front matter: ```yaml -`hidden: true` +hidden: true ``` This can be useful to create redirects or other items that should not be shown in the sidebar. From eb16c0d93ee517c789014f51666b404defd8a1c8 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 16:27:41 +0200 Subject: [PATCH 31/70] Create markdown.md, fixes #17 --- markdown.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 markdown.md diff --git a/markdown.md b/markdown.md new file mode 100644 index 0000000..59d1d59 --- /dev/null +++ b/markdown.md @@ -0,0 +1,61 @@ +--- +--- + +# Markdown with Hyde + +Hyde makes heavy use of Markdown. While this page won't teach you how to use Markdown, +it will hopefully shed some light about how Hyde uses it, and how you can extend it using Front Matter. + +## 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. +``` + +## CommonMark environment + +Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML. + +### Customizing the environment + +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. + +```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' => [], + ], +], +``` From 79433706929252a1e6bdf1ff6ca9f6ed7281eb26 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 16:28:21 +0200 Subject: [PATCH 32/70] Add link to Markdown page --- creating-blog-posts.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index c1f0a31..9e4a9d0 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -44,7 +44,10 @@ to keep in mind when creating blog posts so that you don't get unexpected result Front matter is optional, but highly recommended for blog posts. -- Front matter is stores in a block of YAML that starts and ends with a `---` line. +You can read more about the Front Matter format in the [Markdown documentation](markdown.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. @@ -63,7 +66,6 @@ title: "My New Post" 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, From dc41e5d865f59f30a49fb9966ca8747f6c6e1970 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 16:29:57 +0200 Subject: [PATCH 33/70] Fix links --- creating-documentation-pages.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/creating-documentation-pages.md b/creating-documentation-pages.md index 568a211..e15fb86 100644 --- a/creating-documentation-pages.md +++ b/creating-documentation-pages.md @@ -15,7 +15,7 @@ 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 be used as the sidebar header - - You can even [customize the order and labels](#sidebar-customization) of sidebar items + - 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. @@ -96,7 +96,7 @@ of these items. You can do this in two ways, either in the config or with front 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/documentation-sidebar) for more details. +See [the customization page](customization.html#documentation-sidebar) for more details. ### Sidebar ordering @@ -109,7 +109,7 @@ priority: 5 ``` You can also change the order in the Hyde configuration file. -See [the chapter in the customization page](customization.html/documentation-sidebar) for more details. <br> +See [the chapter in the customization page](customization.html#documentation-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 @@ -171,7 +171,7 @@ Link items without an entry here will have fall back to the default priority of ] ``` -See [the chapter in the customization page](customization.html/documentation-sidebar) for more details. <br> +See [the chapter in the customization page](customization.html#documentation-sidebar) for more details. <br> ### Table of contents settings @@ -187,4 +187,3 @@ You can also disable the feature completely. 'smoothPageScrolling' => true, ], ``` - From 9984f181e18f69cbfee7175596920c8fcaed4e86 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 16:31:48 +0200 Subject: [PATCH 34/70] Update labels --- creating-documentation-pages.md | 1 + markdown.md | 1 + 2 files changed, 2 insertions(+) diff --git a/creating-documentation-pages.md b/creating-documentation-pages.md index e15fb86..c3f4523 100644 --- a/creating-documentation-pages.md +++ b/creating-documentation-pages.md @@ -1,4 +1,5 @@ --- +label: Documentation Pages --- # Creating Documentation Pages diff --git a/markdown.md b/markdown.md index 59d1d59..7d489a8 100644 --- a/markdown.md +++ b/markdown.md @@ -1,4 +1,5 @@ --- +label: "Using Markdown" --- # Markdown with Hyde From 0e72725def3910283c24c9b67c6c6f67a77f596d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 16:45:01 +0200 Subject: [PATCH 35/70] Add Documentation syntax section --- console-commands.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/console-commands.md b/console-commands.md index 90046f7..4fe2501 100644 --- a/console-commands.md +++ b/console-commands.md @@ -9,6 +9,24 @@ the Hyde CLI is based on Artisan after all! To use the HydeCLI, run `php hyde` from your project directory followed by a command. +### Documentation syntax + +Wondering what the diffrent formatting in examples means? Here's a quick guide: + +```bash +<argument> # Comes after the command name. +[<argument>] # Optional argument. + +--option # Sometimes refered to as a flag. +--option=<value> # Option which takes an value. +[--option] # Optional option. +``` + +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. + + + ### Got stuck? The CLI can help. You can always run the base command `php hyde`, or `php hyde list`, to show the list of commands. From 6739ebf8ee5250d3fb63c0c4b5bbbc314a59bf0d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:10:31 +0200 Subject: [PATCH 36/70] Create managing-assets.md --- managing-assets.md | 100 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 managing-assets.md diff --git a/managing-assets.md b/managing-assets.md new file mode 100644 index 0000000..13485a4 --- /dev/null +++ b/managing-assets.md @@ -0,0 +1,100 @@ +--- +--- + +# 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 where base styles and scripts are included through [HydeFront](https://github.com/hydephp/hydefront) which adds accessibility and mobile support as well as interactions for dark mode switching and navigation and sidebar interactions. + +HydeFront is split into two files, `hyde.css` and `hyde.js`. These are loaded in the default Blade views using the [jsDelivr CDN](https://www.jsdelivr.com/package/npm/hydefront). This is the recommended way to load the base styles as the [Hyde Framework](https://github.com/hydephp/framework) automatically makes sure that the correct HydeFront version for the current version of Hyde is loaded. You can disable the CDN in the `config/hyde.php` file by setting `'loadHydeAssetsUsingCDN'` to `false`. + +The bulk of the frontend is built with [TailwindCSS](https://tailwindcss.com/). To get you started, when installing Hyde, all the Tailwind styles you need come precompiled and minified into `_media/app.css`. + +## Some extra information, and answers to possible questions + +### Do I have to use NPM to use Hyde? +No. NPM is optional as all the compiled styles you need are already installed. You only need NPM if you want to compile your own styles. + +### When do I need to compile assets? + +#### When customizing +If you want to customize the Tailwind settings or add custom styles, you will need to take care of compiling the styles yourself. + +#### When adding new classes +The `_media/app.css` file that comes with Hyde contains TailwindCSS for all classes that are used in the default Blade views, but nothing more. + +If you customize the Blade views and add new classes, or if you add new classes in Blade-based pages, you may need to compile the assets yourself to get the new styles. + +If you stick to using Markdown based pages, you don't need to compile anything. + +## How are assets stored and managed? + +Currently, 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. + +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, though you may choose to exclude the compiled files from the `_media` folder if you want to. + +You are of course free to modify this behavior by editing the `webpack.mix.js` file. + +## 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](https://laravel-mix.com/) (which is a wrapper for [webpack](https://webpack.js.org/)) 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. 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. + +### Referencing images + +The reccomended 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 +![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](creating-blog-posts.html#image). + From 425448778de0b91fc79efd62e0178a1b98b0c93e Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:14:56 +0200 Subject: [PATCH 37/70] Set sidepar priorities in front matter --- console-commands.md | 4 ++++ creating-blog-posts.md | 1 + creating-documentation-pages.md | 1 + creating-static-pages.md | 1 + managing-assets.md | 1 + markdown.md | 1 + quickstart.md | 1 + 7 files changed, 10 insertions(+) diff --git a/console-commands.md b/console-commands.md index 4fe2501..763c6e4 100644 --- a/console-commands.md +++ b/console-commands.md @@ -1,3 +1,7 @@ +--- +priority: 5 +--- + # Console Commands The primary way of interacting with Hyde is through the command line using the HydeCLI. diff --git a/creating-blog-posts.md b/creating-blog-posts.md index 9e4a9d0..0ef7ae8 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -1,4 +1,5 @@ --- +priority: 10 --- # Creating Blog Posts diff --git a/creating-documentation-pages.md b/creating-documentation-pages.md index c3f4523..93e5f34 100644 --- a/creating-documentation-pages.md +++ b/creating-documentation-pages.md @@ -1,5 +1,6 @@ --- label: Documentation Pages +priority: 12 --- # Creating Documentation Pages diff --git a/creating-static-pages.md b/creating-static-pages.md index 7b29505..28d6816 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -1,4 +1,5 @@ --- +priority: 11 --- # Creating Static Pages diff --git a/managing-assets.md b/managing-assets.md index 13485a4..9c4fb49 100644 --- a/managing-assets.md +++ b/managing-assets.md @@ -1,4 +1,5 @@ --- +priority: 20 --- # Managing and Compiling Assets diff --git a/markdown.md b/markdown.md index 7d489a8..9ea1516 100644 --- a/markdown.md +++ b/markdown.md @@ -1,5 +1,6 @@ --- label: "Using Markdown" +priority: 25 --- # Markdown with Hyde diff --git a/quickstart.md b/quickstart.md index d1cb4a5..5f7eafe 100644 --- a/quickstart.md +++ b/quickstart.md @@ -1,5 +1,6 @@ --- label: Quickstart Guide +priority: 1 --- # Quickstart Guide From 02e2a5e8b0755d516799a192a955e88e7de67014 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:19:48 +0200 Subject: [PATCH 38/70] Split Markdown.md into new files --- markdown.md | 63 ----------------------------------------------------- 1 file changed, 63 deletions(-) delete mode 100644 markdown.md diff --git a/markdown.md b/markdown.md deleted file mode 100644 index 9ea1516..0000000 --- a/markdown.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -label: "Using Markdown" -priority: 25 ---- - -# Markdown with Hyde - -Hyde makes heavy use of Markdown. While this page won't teach you how to use Markdown, -it will hopefully shed some light about how Hyde uses it, and how you can extend it using Front Matter. - -## 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. -``` - -## CommonMark environment - -Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML. - -### Customizing the environment - -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. - -```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' => [], - ], -], -``` From f5dfeec91b8bb3c0da0595ae784585d699c93363 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:19:52 +0200 Subject: [PATCH 39/70] Create customization.md --- customization.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 customization.md diff --git a/customization.md b/customization.md new file mode 100644 index 0000000..2e76536 --- /dev/null +++ b/customization.md @@ -0,0 +1,31 @@ +--- +label: "Customizing your Site" +priority: 25 +--- + +## 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. + +```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' => [], + ], +], +``` From 13b8c5e9f151c1fd9efc0775e8bedba8e222a74d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:19:54 +0200 Subject: [PATCH 40/70] Create architecture-concepts.md --- architecture-concepts.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 architecture-concepts.md diff --git a/architecture-concepts.md b/architecture-concepts.md new file mode 100644 index 0000000..cf6201e --- /dev/null +++ b/architecture-concepts.md @@ -0,0 +1,28 @@ +--- +priority: 5 +--- + +## 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. +``` From 0fcc376ecd27de925904e802d23a6fd1173befdf Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:22:27 +0200 Subject: [PATCH 41/70] Add categories (NYI) --- architecture-concepts.md | 1 + console-commands.md | 1 + creating-blog-posts.md | 1 + creating-documentation-pages.md | 1 + creating-static-pages.md | 1 + customization.md | 1 + managing-assets.md | 1 + quickstart.md | 1 + 8 files changed, 8 insertions(+) diff --git a/architecture-concepts.md b/architecture-concepts.md index cf6201e..1ba4187 100644 --- a/architecture-concepts.md +++ b/architecture-concepts.md @@ -1,5 +1,6 @@ --- priority: 5 +category: "Getting Started" --- ## Front Matter diff --git a/console-commands.md b/console-commands.md index 763c6e4..5492889 100644 --- a/console-commands.md +++ b/console-commands.md @@ -1,5 +1,6 @@ --- priority: 5 +category: "Getting Started" --- # Console Commands diff --git a/creating-blog-posts.md b/creating-blog-posts.md index 0ef7ae8..299293c 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -1,5 +1,6 @@ --- priority: 10 +category: "Creating Content" --- # Creating Blog Posts diff --git a/creating-documentation-pages.md b/creating-documentation-pages.md index 93e5f34..4400360 100644 --- a/creating-documentation-pages.md +++ b/creating-documentation-pages.md @@ -1,6 +1,7 @@ --- label: Documentation Pages priority: 12 +category: "Creating Content" --- # Creating Documentation Pages diff --git a/creating-static-pages.md b/creating-static-pages.md index 28d6816..848abd4 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -1,5 +1,6 @@ --- priority: 11 +category: "Creating Content" --- # Creating Static Pages diff --git a/customization.md b/customization.md index 2e76536..d5af7e5 100644 --- a/customization.md +++ b/customization.md @@ -1,6 +1,7 @@ --- label: "Customizing your Site" priority: 25 +category: "Digging Deeper" --- ## CommonMark environment diff --git a/managing-assets.md b/managing-assets.md index 9c4fb49..ee68ef4 100644 --- a/managing-assets.md +++ b/managing-assets.md @@ -1,5 +1,6 @@ --- priority: 20 +category: "Creating Content" --- # Managing and Compiling Assets diff --git a/quickstart.md b/quickstart.md index 5f7eafe..ae3b8fc 100644 --- a/quickstart.md +++ b/quickstart.md @@ -1,6 +1,7 @@ --- label: Quickstart Guide priority: 1 +category: "Getting Started" --- # Quickstart Guide From 79ab910db7f9d530e02e1366f6cf66609be3a096 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:50:59 +0200 Subject: [PATCH 42/70] Add the old documentation I think the old docs are good enough here so merging them --- customization.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/customization.md b/customization.md index d5af7e5..0f1de78 100644 --- a/customization.md +++ b/customization.md @@ -4,6 +4,118 @@ priority: 25 category: "Digging Deeper" --- +# Customizing your Site + +## 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! + + +## 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. + +In this config file, you can customize the site name, what modules to enable, and programmatically customize the navigation menu and documentation sidebar. + +Here are a few examples of the config options. + +### Modules +With a concept directly inspired by [Laravel Jetstream](https://jetstream.laravel.com/), this setting allows you to toggle various modules. +```php +// torchlight! {"lineNumbers": false} +'features' => [ + Features::blogPosts(), + Features::bladePages(), + Features::markdownPages(), + // Features::documentationPages(), +], +``` + +### Footer +The footer can be customized using Markdown, and even disabled completely. + +```php +// torchlight! {"lineNumbers": false} +'footer' => [ + 'enabled' => true, + 'markdown' => 'Site built with [HydePHP](https://github.com/hydephp/hyde).' +], +``` + +### Navigation Menu & Sidebar +One of my (the author's) 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` or `readme.md` in the `_docs` directory. + +#### Reordering 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 hyde config, there is an array just for this. When the sidebar is generated it looks through this config array. If a slug is found here it will get priority according to its position in the list. If a page does not exist in the list they get priority 999, which puts them last. + +Let's see an example: +```php +// torchlight! {"lineNumbers": false} +// This is the default values in the config. It puts the readme.md first in order. +'documentationPageOrder' => [ + 'readme', // This is the first entry, so it gets the priority 0 + 'installation', // This gets priority 1 + 'getting-started', // And this gets priority 2 + // Any other pages not listed will get priority 999 +] +``` + +> Navigation menu items will be ordered in the same way in a coming update, but for now, they can be reordered by overriding them which you can learn in the next section. + +#### Adding Custom Navigation Menu Links +> Until the navigation link order is implemented, you can use this feature to reorder navigation menu items. + +The links are added in the config/hyde.php file, and the syntax for adding custom links is documented in the config. Here are some examples: + +```php +// torchlight! {"lineNumbers": false} +// External link +[ + 'title' => 'GitHub', + 'destination' => 'https://github.com/hydephp/hyde', + 'priority' => 1200, +], + +// Internal link (Hyde automatically resolves relative paths) +[ + 'title' => 'Featured Blog Post', + 'slug' => 'posts/hello-world', + // The 'priority' is not required. +] +``` + +#### Removing 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 slug to the blacklist. As you can see, the `404` page has already been filled in for you. + +```php +'navigationMenuBlacklist' => [ + '404' +], +``` + +> Tip: You can publish the included 404 page using `php hyde publish:404`! + +## Blade Views +Hyde uses the Laravel templating system called Blade. Most parts have been extracted into components to be customized easily. + +> Before editing Blade views you should familiarize yourself with how they work in the official documentation https://laravel.com/docs/9.x/blade. + +To edit the default component you need to publish them first using the `hyde publish:views` command. + +## 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. + +Please see the chapter in the [Getting Started](getting-started.html) page to learn more. + + ## CommonMark environment Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML. From de545ef74d509e24fc5fc28ac3029a651652bbc5 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:51:07 +0200 Subject: [PATCH 43/70] Add some key concepts in Hyde --- architecture-concepts.md | 45 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/architecture-concepts.md b/architecture-concepts.md index 1ba4187..60b390b 100644 --- a/architecture-concepts.md +++ b/architecture-concepts.md @@ -3,6 +3,51 @@ 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] +``` + +## 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. From 7f9326413ebaaf34136b5bb2c9ad1dedaa10d55b Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 17:53:47 +0200 Subject: [PATCH 44/70] Add Further reading to quickstart --- quickstart.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/quickstart.md b/quickstart.md index ae3b8fc..81e22c5 100644 --- a/quickstart.md +++ b/quickstart.md @@ -84,3 +84,10 @@ You can even use GitHub pages to host your site for free. That's what the Hyde w using a CI that automatically builds and deploys this site. +## Further reading + +Here's some ideas of what to read next: + +- [Architecture Concepts](architecture-concepts.html) +- [Console Commands](console-commands.html) +- [Creating Blog Posts](creating-blog-posts.html) \ No newline at end of file From 4eef3fb91219ae40e22b686829b2f2973a0d587f Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 18:06:18 +0200 Subject: [PATCH 45/70] Add Using images in posts section --- creating-blog-posts.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/creating-blog-posts.md b/creating-blog-posts.md index 299293c..b401419 100644 --- a/creating-blog-posts.md +++ b/creating-blog-posts.md @@ -207,3 +207,14 @@ 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 +![Image Alt](../media/image.png "Image Title") # 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 From 139206be9b3881897a2c1bdc0891c688e1b3c88b Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 18:09:13 +0200 Subject: [PATCH 46/70] Create updating-hyde.md --- updating-hyde.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 updating-hyde.md diff --git a/updating-hyde.md b/updating-hyde.md new file mode 100644 index 0000000..3d454a6 --- /dev/null +++ b/updating-hyde.md @@ -0,0 +1,84 @@ +--- +priority: 30 +category: "Digging Deeper" +--- + +# Updating Hyde + +## While Hyde is in beta, stuff can change rapidly. +This guide will help you update Hyde to the latest version. It is recommended to back up your source files before updating. + +## Updating Hyde/Framework + +Run the following command from your Hyde/Hyde installation: +```bash +composer update hyde/framework +``` + +Next, follow the post-update instructions for Hyde/Hyde. + +## Updating Hyde/Hyde +When updating an existing installation, first ensure you have a Git backup of your source files to revert the update. + +Depending on how you installed Hyde, there are a few different ways to update it. + +### Using Git +Make sure you have a remote set up for the repository. +```bash +git remote add upstream https://github.com/hydephp/hyde.git +``` + +Then pull the latest changes from the remote: +```bash +git pull upstream master +``` + +Next, follow the post-update instructions for Hyde/Hyde. + +### Manual Update +Since all resource files are in the content directories you can simply copy those files to the new location. + +If you have changed any other files, for example in the App directory, you will need to update those files manually as well. But if you have done that you probably know what you are doing. I hope. The same goes if you have created any custom blade components or have modified Hyde ones. + +Example CLI workflow, assuming the Hyde/Hyde project is stored as `my-project` in the home directory: +```bash +cd ~ +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 for Hyde/Hyde. 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 the files will be overwritten. However, since you should be using Git, you can take care of any merge conflicts that arise. + +```bash +php hyde update:configs +php hyde update:assets +``` + +If you have published any of the Hyde Blade components you will need to re-publish them. + +```bash +php hyde publish:views layouts +php hyde publish:views components +``` + +Next, re-build your site. + +```bash +php hyde build +``` + +And recompile your assets if applicable. + +```bash +npm install +npm run dev/prod +``` \ No newline at end of file From 9b749ca5488187364bbec18b6f0f05e1574d1b0e Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 18:09:20 +0200 Subject: [PATCH 47/70] Set and change page label --- creating-static-pages.md | 1 + 1 file changed, 1 insertion(+) diff --git a/creating-static-pages.md b/creating-static-pages.md index 848abd4..c01f10d 100644 --- a/creating-static-pages.md +++ b/creating-static-pages.md @@ -1,5 +1,6 @@ --- priority: 11 +label: "Markdown & Blade Pages" category: "Creating Content" --- From fc2e924ff2f3fc718a3c87b2c8ff8b819d10d369 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 18:11:54 +0200 Subject: [PATCH 48/70] Rename filenames --- creating-blog-posts.md => blog-posts.md | 0 creating-documentation-pages.md => documentation-pages.md | 0 creating-static-pages.md => static-pages.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename creating-blog-posts.md => blog-posts.md (100%) rename creating-documentation-pages.md => documentation-pages.md (100%) rename creating-static-pages.md => static-pages.md (100%) diff --git a/creating-blog-posts.md b/blog-posts.md similarity index 100% rename from creating-blog-posts.md rename to blog-posts.md diff --git a/creating-documentation-pages.md b/documentation-pages.md similarity index 100% rename from creating-documentation-pages.md rename to documentation-pages.md diff --git a/creating-static-pages.md b/static-pages.md similarity index 100% rename from creating-static-pages.md rename to static-pages.md From c34151a6991c20dd317a67f411f875bf60673aa3 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 18:12:34 +0200 Subject: [PATCH 49/70] Update internal links --- documentation-pages.md | 2 +- managing-assets.md | 2 +- quickstart.md | 2 +- static-pages.md | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation-pages.md b/documentation-pages.md index 4400360..154d4d9 100644 --- a/documentation-pages.md +++ b/documentation-pages.md @@ -56,7 +56,7 @@ This will create the following file saved as `_docs/page-title.md` ### Front Matter is optional -You don't need to use [front matter](creating-blog-posts.html#supported-front-matter-properties) to create a documentation page. +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. diff --git a/managing-assets.md b/managing-assets.md index ee68ef4..c0eaa07 100644 --- a/managing-assets.md +++ b/managing-assets.md @@ -98,5 +98,5 @@ To improve accessibility, you should always add an `alt` text. Here is a full ex 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](creating-blog-posts.html#image). +You can read more about this in the [creating blog posts page](blog-posts.html#image). diff --git a/quickstart.md b/quickstart.md index 81e22c5..45af30b 100644 --- a/quickstart.md +++ b/quickstart.md @@ -90,4 +90,4 @@ Here's some ideas of what to read next: - [Architecture Concepts](architecture-concepts.html) - [Console Commands](console-commands.html) -- [Creating Blog Posts](creating-blog-posts.html) \ No newline at end of file +- [Creating Blog Posts](blog-posts.html) \ No newline at end of file diff --git a/static-pages.md b/static-pages.md index c01f10d..eecc6ca 100644 --- a/static-pages.md +++ b/static-pages.md @@ -31,8 +31,8 @@ to keep in mind when creating blog posts so that you don't get unexpected result ## Creating Markdown Pages -Markdown pages are the easiest way to create static pages, and are similar to [blog posts](creating-blog-posts.html). -You may want to read that page first as it explains [how front matter works](creating-blog-posts.html#supported-front-matter-properties) +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`. From 6c977653ec5231293a1c2577a30f313c5c14dc94 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 19:25:52 +0200 Subject: [PATCH 50/70] Create (admittedly terrible) troubleshooting page --- troubleshooting.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 troubleshooting.md diff --git a/troubleshooting.md b/troubleshooting.md new file mode 100644 index 0000000..2aab04e --- /dev/null +++ b/troubleshooting.md @@ -0,0 +1,90 @@ +--- +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). + + +## 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. | From a1d02484bd84277ceddbb1db58f59b12d266bc51 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 19:27:27 +0200 Subject: [PATCH 51/70] Set label --- blog-posts.md | 1 + 1 file changed, 1 insertion(+) diff --git a/blog-posts.md b/blog-posts.md index b401419..6e5f78c 100644 --- a/blog-posts.md +++ b/blog-posts.md @@ -1,4 +1,5 @@ --- +label: "Creating Blog Posts" priority: 10 category: "Creating Content" --- From 54c1abea27a04d39efeb4d6f313ef78952fec00f Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 19:49:22 +0200 Subject: [PATCH 52/70] Expand link text --- documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation-pages.md b/documentation-pages.md index 154d4d9..550b0b6 100644 --- a/documentation-pages.md +++ b/documentation-pages.md @@ -22,7 +22,7 @@ What is "the rest", you may ask? Well, for starters: - 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](extensions.html) page. + See more about this in the [extensions page](extensions.html). ### Best Practices and Hyde Expectations From 40059f163ae3f11497d806cbededcf546369cd49 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:22:29 +0200 Subject: [PATCH 53/70] Create extensions.md --- extensions.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 extensions.md diff --git a/extensions.md b/extensions.md new file mode 100644 index 0000000..6418a97 --- /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 entierly [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 From b1a9f51b140618faacee1ee0f4c86925e47b3838 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:23:42 +0200 Subject: [PATCH 54/70] Link directly to the Torchlight section --- documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation-pages.md b/documentation-pages.md index 550b0b6..6e65aaa 100644 --- a/documentation-pages.md +++ b/documentation-pages.md @@ -22,7 +22,7 @@ What is "the rest", you may ask? Well, for starters: - 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). + See more about this in the [extensions page](extensions.html#torchlight). ### Best Practices and Hyde Expectations From 0d19e04b89735ccb710f13cfa32fb405500368b9 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:25:01 +0200 Subject: [PATCH 55/70] Add config to directory structure --- quickstart.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/quickstart.md b/quickstart.md index 45af30b..636cfe8 100644 --- a/quickstart.md +++ b/quickstart.md @@ -37,7 +37,8 @@ Creating content with Hyde is easy. Simply place Markdown files in one of the so // torchlight! {"lineNumbers": false} ├── _docs // For documentation pages ├── _posts // For blog posts -└── _pages // For static Markdown or Blade pages +├── _pages // For static Markdown and Blade pages +└── config // Configuration files for Hyde and integrations ``` ### Scaffolding files From 15d183724dda68b6d1a4d8ab1588262281944b4e Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:27:19 +0200 Subject: [PATCH 56/70] Specify and clarify vendor view directory --- console-commands.md | 4 ++-- customization.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/console-commands.md b/console-commands.md index 5492889..bbe9e36 100644 --- a/console-commands.md +++ b/console-commands.md @@ -184,14 +184,14 @@ php hyde publish:views [<category>] ``` 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 directory and the resources directory in the Framework package. +Laravel actually registers two locations for the Hyde views: your site's `resources/views/vendor/hyde` directory and the resources directory in the Framework package. <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> -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. +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. The available views you can publish are: diff --git a/customization.md b/customization.md index 0f1de78..8b36739 100644 --- a/customization.md +++ b/customization.md @@ -110,6 +110,8 @@ 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. From c759e708d81483f2302e7d382368e3c192e2035b Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:39:55 +0200 Subject: [PATCH 57/70] Add note about nested directories --- troubleshooting.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/troubleshooting.md b/troubleshooting.md index 2aab04e..23c3594 100644 --- a/troubleshooting.md +++ b/troubleshooting.md @@ -21,6 +21,9 @@ did you find a new one? Send a PR to [update the docs](https://github.com/hydeph 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 From 24cd9efcb4a0cc2cdf248f7d2ef2f862d375fa41 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:40:07 +0200 Subject: [PATCH 58/70] Add directory structure --- architecture-concepts.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/architecture-concepts.md b/architecture-concepts.md index 60b390b..6fbdabc 100644 --- a/architecture-concepts.md +++ b/architecture-concepts.md @@ -18,6 +18,26 @@ to learn more and see the available commands and their usage. 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 From c69947fbe207a513f2f9e112d4249f15b2cb6152 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:40:25 +0200 Subject: [PATCH 59/70] Link to directory structure section --- quickstart.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/quickstart.md b/quickstart.md index 636cfe8..26da5fe 100644 --- a/quickstart.md +++ b/quickstart.md @@ -35,12 +35,14 @@ php hyde serve 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 +├── _docs // For documentation pages ├── _posts // For blog posts -├── _pages // For static Markdown and Blade pages -└── config // Configuration files for Hyde and integrations +└── _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. @@ -89,6 +91,6 @@ using a CI that automatically builds and deploys this site. Here's some ideas of what to read next: -- [Architecture Concepts](architecture-concepts.html) -- [Console Commands](console-commands.html) +- [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 From 83cfad71e4e150026e19351a022247a2a5eae0a5 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 20:52:15 +0200 Subject: [PATCH 60/70] Add Requirements section --- quickstart.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/quickstart.md b/quickstart.md index 26da5fe..ff6ca88 100644 --- a/quickstart.md +++ b/quickstart.md @@ -13,6 +13,17 @@ The recommended method of installing Hyde is using Composer. 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. From b68110b4f857dbe686dc5970eefec28420d260bc Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:02:34 +0200 Subject: [PATCH 61/70] Fix broken links --- blog-posts.md | 2 +- documentation-pages.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/blog-posts.md b/blog-posts.md index 6e5f78c..3198a73 100644 --- a/blog-posts.md +++ b/blog-posts.md @@ -47,7 +47,7 @@ to keep in mind when creating blog posts so that you don't get unexpected result Front matter is optional, but highly recommended for blog posts. -You can read more about the Front Matter format in the [Markdown documentation](markdown.html#front-matter). +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. diff --git a/documentation-pages.md b/documentation-pages.md index 6e65aaa..27b1ada 100644 --- a/documentation-pages.md +++ b/documentation-pages.md @@ -98,8 +98,8 @@ of these items. You can do this in two ways, either in the config or with front 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#documentation-sidebar) for more details. +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 @@ -112,7 +112,7 @@ priority: 5 ``` You can also change the order in the Hyde configuration file. -See [the chapter in the customization page](customization.html#documentation-sidebar) for more details. <br> +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 @@ -174,7 +174,7 @@ Link items without an entry here will have fall back to the default priority of ] ``` -See [the chapter in the customization page](customization.html#documentation-sidebar) for more details. <br> +See [the chapter in the customization page](customization.html#navigation-menu--sidebar) for more details. <br> ### Table of contents settings From 80e521036eb6dcf8d18605bd4c7a85fdc51aaddc Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:02:45 +0200 Subject: [PATCH 62/70] Update frontend styles section --- customization.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/customization.md b/customization.md index 8b36739..abb92c1 100644 --- a/customization.md +++ b/customization.md @@ -113,9 +113,7 @@ To edit the default component you need to publish them first using the `hyde pub 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. - -Please see the chapter in the [Getting Started](getting-started.html) page to learn more. +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 From f80ad5cdce0799bcb73e71c7b5b83f012e5c11ce Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:03:21 +0200 Subject: [PATCH 63/70] Remove extra closing tag --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 32c90f7..07d0a46 100644 --- a/index.md +++ b/index.md @@ -6,7 +6,7 @@ <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 From 2afa15030b825542707ea0496aa5d8078d9d8a23 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:05:04 +0200 Subject: [PATCH 64/70] Fix grammar and formatting --- blog-posts.md | 2 +- console-commands.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/blog-posts.md b/blog-posts.md index 3198a73..6deeea9 100644 --- a/blog-posts.md +++ b/blog-posts.md @@ -9,7 +9,7 @@ category: "Creating Content" ## 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. +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. diff --git a/console-commands.md b/console-commands.md index bbe9e36..b9a3d10 100644 --- a/console-commands.md +++ b/console-commands.md @@ -97,7 +97,7 @@ php hyde serve 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 and proxy +realtime compiler to locate the source file, recompile it, and proxy the resulting HTML and any media files to your browser. If you are missing the extension, you can always reinstall it with Composer `composer require hyde/realtime-compiler`. @@ -166,7 +166,7 @@ Hyde comes with three homepage options to choose from. The homepage you select i `_pages/index.blade.php` and becomes the `index.html` file when compiling the site. On a fresh install the page 'welcome' is installed. -However, you can use the this command to publish another one. +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. The available homepages are: @@ -184,7 +184,7 @@ php hyde publish:views [<category>] ``` 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 in the Framework package. +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. <blockquote class="warning"> <p>Warning: This command will overwrite any existing files in the <code>resources/views/vendor</code> directory. <br> @@ -197,7 +197,7 @@ 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. +- **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. You can supply the category name directly to the command, otherwise you will be prompted to select one. From 35f4a2e25226d60e927715af812e4e01a07b441c Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:09:08 +0200 Subject: [PATCH 65/70] Fix grammar --- customization.md | 4 ++-- documentation-pages.md | 4 ++-- extensions.md | 2 +- quickstart.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/customization.md b/customization.md index abb92c1..975167f 100644 --- a/customization.md +++ b/customization.md @@ -13,7 +13,7 @@ and thus comes preconfigured with sensible defaults. However, Hyde also strives ## 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. @@ -120,7 +120,7 @@ Hyde is designed to not only serve as a framework but a whole starter kit and co Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML. -Hyde ships with the Github Flavored Markdown extension, and +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. diff --git a/documentation-pages.md b/documentation-pages.md index 27b1ada..c7876e7 100644 --- a/documentation-pages.md +++ b/documentation-pages.md @@ -17,7 +17,7 @@ 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 be used as the sidebar header + - 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". @@ -155,7 +155,7 @@ for example to specify a version like the Hyde docs does, you can specify the ou ### 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 you can change this in the Hyde configuration file. +You can change this in the Hyde configuration file. ```php 'docsSidebarHeaderTitle' => 'API Documentation', diff --git a/extensions.md b/extensions.md index 6418a97..8c76a2b 100644 --- a/extensions.md +++ b/extensions.md @@ -56,4 +56,4 @@ that use Torchlight. You can of course disable this in the `config/torchlight.ph 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 +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/quickstart.md b/quickstart.md index ff6ca88..ec426dd 100644 --- a/quickstart.md +++ b/quickstart.md @@ -92,7 +92,7 @@ Hyde comes bundled with a precompiled and minified `app.css` containing all the 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. +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. From 2caf8fd96fe5038ecdb80822d3c223341b3f6428 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:12:04 +0200 Subject: [PATCH 66/70] Fix typos --- blog-posts.md | 4 ++-- console-commands.md | 4 ++-- documentation-pages.md | 2 +- extensions.md | 2 +- managing-assets.md | 2 +- static-pages.md | 6 +++--- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/blog-posts.md b/blog-posts.md index 6deeea9..b4f91e3 100644 --- a/blog-posts.md +++ b/blog-posts.md @@ -54,7 +54,7 @@ Here is a quick primer: - 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 encouranged to look at the compiled HTML to learn and understand how your front matter is used. + You are encouraged to look at the compiled HTML to learn and understand how your front matter is used. **Example:** @@ -97,7 +97,7 @@ animi distinctio earum ducimus minus, magnam. The front matter is used to construct dynamic HTML markup for the post as well as meta tags and post feeds. -You are encouranged to look at the compiled HTML to learn and understand how your front matter is used. +You are encouraged to look at the compiled HTML to learn and understand how your front matter is used. ### Front matter syntax diff --git a/console-commands.md b/console-commands.md index b9a3d10..e1a1f6e 100644 --- a/console-commands.md +++ b/console-commands.md @@ -16,13 +16,13 @@ To use the HydeCLI, run `php hyde` from your project directory followed by a com ### Documentation syntax -Wondering what the diffrent formatting in examples means? Here's a quick guide: +Wondering what the different formatting in examples means? Here's a quick guide: ```bash <argument> # Comes after the command name. [<argument>] # Optional argument. ---option # Sometimes refered to as a flag. +--option # Sometimes referred to as a flag. --option=<value> # Option which takes an value. [--option] # Optional option. ``` diff --git a/documentation-pages.md b/documentation-pages.md index c7876e7..b6e2eb7 100644 --- a/documentation-pages.md +++ b/documentation-pages.md @@ -78,7 +78,7 @@ Hyde makes documentation pages easy to create by automatically generating dynami 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 overriden. +and where the data is from as well as where it can be overridden. | Property | Description | Source | Override in | diff --git a/extensions.md b/extensions.md index 8c76a2b..cd1c874 100644 --- a/extensions.md +++ b/extensions.md @@ -28,7 +28,7 @@ I cannot recommend it highly enough, especially for documentation sites and code #### Getting started To get started you need an API token which you can get through the [torchlight.dev website](https://torchlight.dev/). -It is entierly [free for personal and open source projects](https://torchlight.dev/#pricing). +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. diff --git a/managing-assets.md b/managing-assets.md index c0eaa07..74f0f49 100644 --- a/managing-assets.md +++ b/managing-assets.md @@ -74,7 +74,7 @@ making it the recommended place to store images. You can then easily reference t ### Referencing images -The reccomended way to reference images are with relative paths as this offers the most compatibility, +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 diff --git a/static-pages.md b/static-pages.md index eecc6ca..7822c83 100644 --- a/static-pages.md +++ b/static-pages.md @@ -9,8 +9,8 @@ category: "Creating Content" ## Introduction to Hyde Pages Hyde offers two ways to create static pages: -**Markdown pages** which are perfect for simple pagesthat focuses heavily on the content, -and **Blade pages** which are perfect for more complex pages where you want full control over the HMTL, +**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. @@ -62,7 +62,7 @@ You can of course also create the file yourself with your text editor. 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 searcing +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. From 60e70f674d06ebaf3086e36be1872efb26397a6d Mon Sep 17 00:00:00 2001 From: Caen De Silva <95144705+caendesilva@users.noreply.github.com> Date: Tue, 10 May 2022 21:13:58 +0200 Subject: [PATCH 67/70] Rename file as it had the case inverted --- readme.MARKDOWN | 1 - 1 file changed, 1 deletion(-) delete mode 100644 readme.MARKDOWN diff --git a/readme.MARKDOWN b/readme.MARKDOWN deleted file mode 100644 index 6142cdd..0000000 --- a/readme.MARKDOWN +++ /dev/null @@ -1 +0,0 @@ -# Hyde Documentation for versions series 0.20 and above (Work in progress) From ccb03ad696c111c1f6d03bc98e93e01edbc42f20 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:14:28 +0200 Subject: [PATCH 68/70] Merge Readme, readying for PR --- README.markdown | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 README.markdown diff --git a/README.markdown b/README.markdown new file mode 100644 index 0000000..4b95663 --- /dev/null +++ b/README.markdown @@ -0,0 +1,5 @@ +# Hyde Documentation +[![CI Deploy](https://github.com/hydephp/docs/actions/workflows/deploy.yml/badge.svg)](https://github.com/hydephp/docs/actions/workflows/deploy.yml) + +This is the source for the HydePHP Documentation. Updates to this repo are automatically propagated to the [DocsCI pipeline](https://github.com/hydephp/DocsCI) which uses Hyde to build the static site hosted at +https://hydephp.github.io/docs From 0a4b544fbcf7f15ea2325606d3c74a1b9d7eddec Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 21:35:17 +0200 Subject: [PATCH 69/70] Merge .github with master --- .github/workflows/deploy.yml | 41 ++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .github/workflows/deploy.yml diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..98a68b9 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,41 @@ +# This is a basic workflow to help you get started with Actions +name: CI Deploy + +# Controls when the workflow will run +on: + # Triggers the workflow on push or pull request events but only for the master branch + push: + branches: [ master ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +permissions: + contents: read + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "deploy" + deploy: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v3 + + # Copy over the root Markdown files into a new directory + - name: Copy Markdown files + run: mkdir files && cp *.md files + + - name: Push Markdown files + uses: cpina/github-action-push-to-another-repository@main + env: + API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }} + with: + source-directory: 'files' + target-directory: '_docs' + destination-github-username: 'hydephp' + destination-repository-name: 'DocsCI' + target-branch: master From 14ccdc958600deabd175666683851f3a3be24cb7 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Tue, 10 May 2022 22:27:10 +0200 Subject: [PATCH 70/70] Add redirect files --- directory-structure.md | 9 +++++++++ getting-started.md | 9 +++++++++ installation.md | 9 +++++++++ 3 files changed, 27 insertions(+) create mode 100644 directory-structure.md create mode 100644 getting-started.md create mode 100644 installation.md diff --git a/directory-structure.md b/directory-structure.md new file mode 100644 index 0000000..9870577 --- /dev/null +++ b/directory-structure.md @@ -0,0 +1,9 @@ +--- +hidden: true +--- + +<meta http-equiv="refresh" content="0;url=architecture-concepts.html#directory-structure" /> + +Redirecting you to [architecture-concepts#directory-structure](architecture-concepts.html#directory-structure) + +<!-- 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/getting-started.md b/getting-started.md new file mode 100644 index 0000000..507d8ca --- /dev/null +++ b/getting-started.md @@ -0,0 +1,9 @@ +--- +hidden: true +--- + +<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/installation.md b/installation.md new file mode 100644 index 0000000..507d8ca --- /dev/null +++ b/installation.md @@ -0,0 +1,9 @@ +--- +hidden: true +--- + +<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