diff --git a/docs/advanced-features/advanced-features.md b/docs/advanced-features/advanced-features.md index 6e02ab9646d..e88283832a8 100644 --- a/docs/advanced-features/advanced-features.md +++ b/docs/advanced-features/advanced-features.md @@ -12,7 +12,6 @@ HydePHP is a simple, yet powerful, static site generator. It is designed to be e This section of the documentation will cover some of the more advanced (but optional) features of the framework. - ## Prerequisites To fully understand the features described in these chapters, it may be beneficial to first skim through the @@ -22,7 +21,6 @@ You are also expected to have a basic understanding of PHP, and object-oriented Having some familiarity with Laravel will also be beneficial, as HydePHP is built on top of the Laravel framework. - ## Table of Contents [Blade]: diff --git a/docs/advanced-features/build-tasks.md b/docs/advanced-features/build-tasks.md index dd25bb74afe..cb052ce8b6f 100644 --- a/docs/advanced-features/build-tasks.md +++ b/docs/advanced-features/build-tasks.md @@ -9,7 +9,6 @@ The built-in Hyde features like sitemap generation and RSS feeds are created usi Maybe you want to create your own, to for example upload the site to FTP or copy the files to a public directory? You can also overload the built-in tasks to customize them to your needs. - ## Good to know before you start ### Types of tasks @@ -31,7 +30,6 @@ In a way, build tasks are like micro-commands, as they can interact directly wit In addition, there are some extra helpers available in the base BuildTask class that allow you to fluently format output to the console, which you will see in the examples below. - ## Creating Build Tasks ### Minimal example @@ -102,7 +100,6 @@ Running this task will produce the following output: As you can see, there is no execution time tracking here, since we overrode the `printFinishMessage()` method that normally prints this. You can of course call the `withExecutionTime()` method to add this back in. See more in the API reference below. - ## Registering the Tasks There are a few ways to register these tasks so Hyde can find them. diff --git a/docs/advanced-features/hyde-pages.md b/docs/advanced-features/hyde-pages.md index eff92d33cc6..7cf2249d73b 100644 --- a/docs/advanced-features/hyde-pages.md +++ b/docs/advanced-features/hyde-pages.md @@ -7,7 +7,6 @@ navigation: >warning This article covers advanced information, and you are expected to already be familiar with [Page Models](page-models) and OOP - ## Abstract This page contains the full API references for the built-in HydePage classes. Most users will not need to know about @@ -38,7 +37,6 @@ under the `HydePage` class documentation which is conveniently located just belo | [DocumentationPage](#documentationpage) | Class for documentation pages. | | [HtmlPage](#htmlpage) | Class for HTML pages. | - ## HydePage The base class for all Hyde pages. All other page classes extend this class. @@ -120,7 +118,6 @@ abstract class HydePage [Blade]: {{ Hyde\Markdown\Models\Markdown::fromFile(DocumentationPage::sourcePath('_data/partials/hyde-pages-api/interacts-with-front-matter-methods'))->toHtml($page::class) }} - ## BaseMarkdownPage The base class for all Markdown-based page models, with additional helpers tailored for Markdown pages. @@ -149,7 +146,6 @@ abstract class BaseMarkdownPage extends HydePage [Blade]: {{ Hyde\Markdown\Models\Markdown::fromFile(DocumentationPage::sourcePath('_data/partials/hyde-pages-api/base-markdown-page-methods'))->toHtml($page::class) }} - ## InMemoryPage Before we take a look at the common page classes, you'll usually use, let's first take a look at one that's quite interesting. @@ -193,7 +189,6 @@ class InMemoryPage extends HydePage [Blade]: {{ Hyde\Markdown\Models\Markdown::fromFile(DocumentationPage::sourcePath('_data/partials/hyde-pages-api/in-memory-page-methods'))->toHtml($page::class) }} - ## BladePage Page class for Blade pages. @@ -222,7 +217,6 @@ class BladePage extends HydePage [Blade]: {{ Hyde\Markdown\Models\Markdown::fromFile(DocumentationPage::sourcePath('_data/partials/hyde-pages-api/blade-page-methods'))->toHtml($page::class) }} - ## MarkdownPage Page class for Markdown pages. @@ -251,7 +245,6 @@ class MarkdownPage extends BaseMarkdownPage This class does not define any additional methods. - ## MarkdownPost Page class for Markdown blog posts. @@ -286,7 +279,6 @@ class MarkdownPost extends BaseMarkdownPage [Blade]: {{ Hyde\Markdown\Models\Markdown::fromFile(DocumentationPage::sourcePath('_data/partials/hyde-pages-api/markdown-post-methods'))->toHtml($page::class) }} - ## DocumentationPage Page class for documentation pages. @@ -315,7 +307,6 @@ class DocumentationPage extends BaseMarkdownPage [Blade]: {{ Hyde\Markdown\Models\Markdown::fromFile(DocumentationPage::sourcePath('_data/partials/hyde-pages-api/documentation-page-methods'))->toHtml($page::class) }} - ## HtmlPage Page class for HTML pages. diff --git a/docs/advanced-features/in-memory-pages.md b/docs/advanced-features/in-memory-pages.md index 689ddc41669..e02b4b1d033 100644 --- a/docs/advanced-features/in-memory-pages.md +++ b/docs/advanced-features/in-memory-pages.md @@ -23,7 +23,6 @@ make sure you register it before the full application is booted so that routes c _To see how to register the page, see the examples below. But first we must look at how to actually create the page._ - ## Creating the Page To create an InMemoryPage, you need to instantiate it with the required parameters. @@ -43,7 +42,6 @@ contents with the supplied front matter during the static site build process. You can also register a macro with the name `compile` to overload the default compile method. - ## API Reference To see all the methods available, please see the [InMemoryPage API reference](hyde-pages#inmemorypage). diff --git a/docs/architecture-concepts/architecture-concepts.md b/docs/architecture-concepts/architecture-concepts.md index fda816a79fe..5a991705b43 100644 --- a/docs/architecture-concepts/architecture-concepts.md +++ b/docs/architecture-concepts/architecture-concepts.md @@ -19,7 +19,6 @@ then by all means, please read on! This is also a great place to start if you wa >info For a high-level overview of these concepts, see the [Basic Architecture Concepts](core-concepts) page. - ## Behind the Magic Want to learn more about a particular feature? Click on the links below to visit the article. diff --git a/docs/architecture-concepts/autodiscovery.md b/docs/architecture-concepts/autodiscovery.md index 74381b4ad02..fde9d6e6ddb 100644 --- a/docs/architecture-concepts/autodiscovery.md +++ b/docs/architecture-concepts/autodiscovery.md @@ -18,7 +18,6 @@ Before reading this article, you should be familiar with the following concepts: - [Page Models](page-models) - [The HydeKernel](the-hydekernel) - ## Booting Pipeline The autodiscovery is run when the HydeKernel boots. It does so in three distinct steps, which run in sequence as each @@ -37,7 +36,6 @@ Usually, you will interact with the collection data through intermediaries. * For example, if you call `MarkdownPost::get('my-post')`, Hyde will retrieve that page from the page collection. * If you call `Routes::get('index')`, Hyde will retrieve that route from the route collection. - ## The HydeKernel If you have not yet read the [HydeKernel Documentation](the-hydekernel), here's a quick recap: diff --git a/docs/architecture-concepts/dynamic-data-discovery.md b/docs/architecture-concepts/dynamic-data-discovery.md index b89f0316690..bb8d3e51015 100644 --- a/docs/architecture-concepts/dynamic-data-discovery.md +++ b/docs/architecture-concepts/dynamic-data-discovery.md @@ -3,7 +3,6 @@ [//]: # (Adds a pseudo-subtitle)

AKA: Front Matter & Filling in the Gaps

- ## Introduction Hyde wants to allow developers to write less, and do more. This is also a major difference between HydePHP and JekyllRB. @@ -18,7 +17,6 @@ your content, and not your markup, front matter is optional and Hyde will try to If you're not happy with Hyde's generated data you can always override it by adding front matter to your files. - ## How it Works Now, to the fun part: getting into the nitty-gritty details of how Hyde does this! @@ -37,7 +35,6 @@ There are a few factory classes. The one we will be looking at here is the `Hyde responsible for data applicable to all page models. Complex structures and data only relevant to some page types have their own factories, making the code more modular and maintainable. - ## In-depth Overview of a Page Factory Let's take a look at how Hyde will discover the title of a page as an example. Since this is something used by all pages, diff --git a/docs/architecture-concepts/extensions-api.md b/docs/architecture-concepts/extensions-api.md index a9891b63255..d71e6a258b5 100644 --- a/docs/architecture-concepts/extensions-api.md +++ b/docs/architecture-concepts/extensions-api.md @@ -36,7 +36,6 @@ Any other functionality you want to add to HydePHP, such as new commands or conf can be added the same way as you would in Laravel, and are thus not part of our API. See the [Laravel package development guide](https://laravel.com/docs/10.x/packages) for more. - ## Creating Your Extension Class The entry-point for your extension is your Extensions class. Within this, you can register the custom page classes. @@ -113,7 +112,6 @@ class JsonPageExtension extends HydeExtension { Since the discovery steps are handled sequentially, the added pages will automatically be discovered as routes without us having to implement that handler method. As we inject the page objects directly, we bypass the need for the `FileCollection`. - ## Registering Your Extension Now that we have our extension class, we need to register it with HydePHP. diff --git a/docs/architecture-concepts/page-models.md b/docs/architecture-concepts/page-models.md index aa247c83ae9..ce9e2376734 100644 --- a/docs/architecture-concepts/page-models.md +++ b/docs/architecture-concepts/page-models.md @@ -12,7 +12,6 @@ for your pages, also house instructions to Hyde on how to parse, process, and re In this article, you'll get a high-level overview of the page models, and some code examples to give you a look inside. - ## The Short Version #### Page models are classes that have two primary concerns: @@ -26,7 +25,6 @@ In this article, you'll get a high-level overview of the page models, and some c - You don't construct page models yourself. HydePHP does it for you by the [autodiscovery process](autodiscovery). - Page models are just PHP classes. You can extend them, and you can implement your own. - ## The Page Model To give you an idea of what a page model class looks like, here's a simplified version of the base `MarkdownPost` class, @@ -52,7 +50,6 @@ class MarkdownPost extends BaseMarkdownPage _Note that since Hyde pages are modular through class inheritance and traits, this example has been simplified and edited to show all the relevant parts inlined into one class._ - ## Page Models as Blueprints All page models have some static properties (that is, they belong to the class, not the instance) that are used as @@ -78,7 +75,6 @@ and how the paths relate to each other. So for the class above, Hyde will thanks * Compile the page using the `post` Blade template * Output the compiled page to the `_site/posts` directory - ## Page Models as Data Containers As mentioned above, each page model instance also holds the page source contents, as well as the computed data. diff --git a/docs/architecture-concepts/the-hydekernel.md b/docs/architecture-concepts/the-hydekernel.md index 19e45ab13fa..c9c9bf2577a 100644 --- a/docs/architecture-concepts/the-hydekernel.md +++ b/docs/architecture-concepts/the-hydekernel.md @@ -18,7 +18,6 @@ Hyde::version(); // calls $HydeKernel->version() The kernel is created very early on in the application lifecycle, in the `bootstrap.php` file, where it is also bound as a singleton into the application service container. - ## Accessing the Kernel The HydeKernel is stored as a singleton in a static property in its own class and can be accessed in a few ways. @@ -43,14 +42,12 @@ hyde()->version(); The Kernel instance is constructed and bound in the `app/bootstrap.php` file. - ## The Kernel Lifecycle Whenever we talk about the kernel being "booted" we are talking about the kernel's role in the autodiscovery process. You can read all about it in the [Autodiscovery Documentation](autodiscovery). - ## API Reference Since the most common way to interact with the kernel is through the Hyde facade, we will use that for the examples. diff --git a/docs/creating-content/blog-posts.md b/docs/creating-content/blog-posts.md index cb3fa83b3cf..8f3dd87a4bf 100644 --- a/docs/creating-content/blog-posts.md +++ b/docs/creating-content/blog-posts.md @@ -19,12 +19,10 @@ php hyde make:post ``` Learn more about scaffolding posts, and other files, in the [console commands](console-commands) documentation. - ## Short Video Tutorial - ## Best Practices and Hyde Expectations Since Hyde does a lot of things automatically, there are some things you may need @@ -73,7 +71,6 @@ Autem aliquid alias explicabo consequatur similique, animi distinctio earum ducimus minus, magnam. ``` - ## Supported Front Matter Properties ### Post Front Matter Schema @@ -201,7 +198,6 @@ image: > 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: diff --git a/docs/creating-content/compile-and-deploy.md b/docs/creating-content/compile-and-deploy.md index 732e524bf01..e3699c1dd2e 100644 --- a/docs/creating-content/compile-and-deploy.md +++ b/docs/creating-content/compile-and-deploy.md @@ -40,7 +40,6 @@ php hyde serve --- - ## Deploying Your Site One of the things that make static sites so enjoyable to work with is how easy it is to deploy them to the web. diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index c1f0cdfdbd0..b0b08f35354 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -40,7 +40,6 @@ to keep in mind when creating blog posts so that you don't get unexpected result Like most of HydePHP, the Hyde Documentation module is highly customizable. Much of the frontend is composed using Blade templates and components, which you can customize to your heart's content. Since there are so many components, it's hard to list them all here in the documentation, so I encourage you to check out the [source code](https://github.com/hydephp/framework/tree/master/resources/views/components/docs) to see how it's all put together and find the customizations you are looking for. - ## Creating Documentation Pages You can create a Documentation page by adding a file to the `_docs` directory where the filename ends in `.md`. @@ -55,6 +54,7 @@ This will create the following file saved as `_docs/page-title.md` ```markdown # Page Title + ``` ### Front Matter is optional @@ -75,7 +75,6 @@ navigation: --- ``` - ## Dynamic Content Generation Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. @@ -94,7 +93,6 @@ and where the data is from as well as where it can be overridden. | `navigation.hidden` (boolean) | Hides the page from the sidebar | _none_ | Front matter, config | | `navigation.group` (string) | The group the page belongs to in the sidebar | Subdirectory, if nested | Front matter | - ## Sidebar The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order @@ -182,7 +180,6 @@ This can be useful to create redirects or other items that should not be shown i >info The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header.
- ## Customization Please see the [customization page](customization) for in-depth information on how to customize Hyde, @@ -276,7 +273,6 @@ If you set this to false, Hyde will match the directory structure of the source 'flattened_output_paths' => true, ``` - ## Search Feature ### Introduction @@ -323,7 +319,6 @@ navigation menu items are hidden. The page will still be accessible as normal bu The Realtime Compiler that powers the `php hyde serve` command will automatically generate a fresh search index each time the browser requests it. - ## Automatic "Edit Page" Button ### Introduction diff --git a/docs/creating-content/managing-assets.md b/docs/creating-content/managing-assets.md index 481bad7cc94..fbb97c067ea 100644 --- a/docs/creating-content/managing-assets.md +++ b/docs/creating-content/managing-assets.md @@ -18,7 +18,6 @@ Some extra custom styles are made in the HydeFront package, which is pre-install To get you started quickly, all the styles are already compiled and minified into `_media/app.css`, which will be copied to the `_site/media/app.css` directory when you run `php hyde build`. - ## Additional Information and Answers to Common Questions ### Is NodeJS/NPM Required for Using Hyde? @@ -33,7 +32,6 @@ If you want to customize the Tailwind settings or add custom styles, you will ne For example, if you customize the Blade views and add new classes or add new classes in Blade-based pages, you may need to compile the assets yourself to get the new styles. If you use Markdown-based pages, you do not need to compile anything as those styles are already included in the compiled CSS file. - ## How are assets stored and managed? The frontend assets are separated into three places. @@ -55,7 +53,6 @@ It may seem weird to have two folders for storing the compiled assets, but it is The `_site` directory is intended to be excluded from version control, while the `_media` folder is included in the version control. You are of course free to modify this behaviour by editing the `webpack.mix.js` file to change the output directory. - ## How Do I Compile assets? First, make sure that you have installed all the NodeJS dependencies using `npm install`. @@ -71,7 +68,6 @@ 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`. - ## Telling Hyde where to find assets ### Customizing the Blade templates @@ -110,7 +106,6 @@ so the Play CDN styles match the ones created by Laravel Mix. All in all, this allows you to tinker around with Tailwind without having to compile anything. - ## Managing Images As mentioned above, assets stored in the _media folder are automatically copied to the _site/media folder, diff --git a/docs/creating-content/static-pages.md b/docs/creating-content/static-pages.md index e793f5960c5..ea130f3df7a 100644 --- a/docs/creating-content/static-pages.md +++ b/docs/creating-content/static-pages.md @@ -29,7 +29,6 @@ to keep in mind when creating blog posts so that you don't get unexpected result - Your page will be stored in `_site/.html` - Blade pages will override any Markdown pages with the same filename when compiled - ## Creating Markdown Pages Markdown pages are the easiest way to create static pages. You can create a Markdown page by adding a file to the @@ -82,7 +81,6 @@ navigation: - `hidden` will hide the page from the navigation menu (`visible`) is also supported, but obviously invert the value) - `group` will put the page in a dropdown menu with the specified group name (`category`) is also supported) - ## Creating Blade Pages Since Hyde is based on Laravel and uses the powerful Blade templating engine, you can use Blade pages to create more @@ -123,7 +121,6 @@ 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. - ## 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. @@ -149,7 +146,6 @@ The Hyde website ([hydephp.com](https://hydephp.com/)) uses both Markdown and Bl A great example of a Markdown page can be found at [hydephp.github.io/portfolio-demo](https://hydephp.github.io/portfolio-demo), you can see the [page source here on GitHub](https://github.com/hydephp/portfolio-demo/blob/master/_pages/index.md). - ## Bonus: Creating HTML Pages If you have an already created `HTML` page, simply drop it into the `_pages` directory and Hyde will copy it over as it is diff --git a/docs/digging-deeper/advanced-customization.md b/docs/digging-deeper/advanced-customization.md index 1b08fd88dcd..0488dabf7e0 100644 --- a/docs/digging-deeper/advanced-customization.md +++ b/docs/digging-deeper/advanced-customization.md @@ -28,7 +28,6 @@ is registered, at which point the provider will search for any overrides in the - You can use the [`RegistersFileLocations`](https://github.com/hydephp/framework/blob/master/src/Framework/Concerns/RegistersFileLocations.php) trait to use the same registration logic as the `HydeServiceProvider`. - ## Customizing Source Directories The directories you place your content in are important. The directory will be used to determine the proper page type and the templates used. @@ -70,7 +69,6 @@ public function register(): void } ``` - ## Customizing Output Directories Like source directories, the output directories are also important as they determine the output path for the compiled pages. @@ -116,7 +114,6 @@ This means that a file stored as `_posts/hello-world.md` will have the route key this may break your site's configuration and links, so you should always verify your site works properly after such a change. You can learn more about this in the [route key documentation](core-concepts#paths-identifiers-and-route-keys). - ## Custom Source Root HydePHP will by default look for the source directories shown above in the root of your project. @@ -141,7 +138,6 @@ php hyde change:sourceDirectory When run, Hyde will update the source directory setting in the config file, then create the directory if it doesn't exist, and move all source directories and their content into it. - ## Custom Media Directory The media directory houses assets like images and stylesheets. The default directory is `_media`, and upon building the site, @@ -165,7 +161,6 @@ Note that this change will affect both the source and output directories. For ex all files from `assets` will be copied to `_site/assets`. If the setting starts with an underscore, that will be removed from the output directory, so files in `_assets` will be copied to `_site/assets`. - ## Custom Output Directory >danger

Warning: Hyde deletes all files in the output directory before compiling the site.

Don't set this path to a directory that contains important files!

diff --git a/docs/digging-deeper/advanced-markdown.md b/docs/digging-deeper/advanced-markdown.md index b36f577e639..bf58e739fd1 100644 --- a/docs/digging-deeper/advanced-markdown.md +++ b/docs/digging-deeper/advanced-markdown.md @@ -10,7 +10,6 @@ navigation: Since HydePHP makes heavy use of Markdown, there are some extra features and helpers created just for Hyde to make using Markdown even easier and more powerful! - ## Using Blade in Markdown A special feature in Hyde, is that you can use [Laravel Blade](https://laravel.com/docs/10.x/blade) in Markdown files! @@ -47,7 +46,6 @@ However, if your Markdown is trusted, and you know it's safe, you can enable it All shortcodes must be the first word on a new line, and only single-line shortcodes are supported. - ## Coloured Blockquotes The HydePHP Markdown converter also supports some extra directives and features. One of them being four different @@ -106,7 +104,6 @@ The coloured blockquotes also support inline Markdown, just like normal blockquo Note that these currently do not support multi-line blockquotes. - ## Code Block Filepaths When browsing these documentation pages you may have noticed a label in the top right corner of code blocks specifying the file path. @@ -163,7 +160,6 @@ anything within the path label will be rendered as HTML. This means you can add The filepaths are hidden on mobile devices using CSS to prevent them from overlapping with the code block. - ## Configuration ### Full configuration reference diff --git a/docs/digging-deeper/collections.md b/docs/digging-deeper/collections.md index 89745bd0c57..4cfc75ba1af 100644 --- a/docs/digging-deeper/collections.md +++ b/docs/digging-deeper/collections.md @@ -16,7 +16,6 @@ As you have access to all standard Laravel Collection methods, you are encourage This article covers advanced usage intended for those who are writing their own Blade views, and is not required as Hyde comes pre-packaged with many templates for you to use. - ## High-Level Concept Overview In short, HydePHP finds files in the specified directory, turns each file into an object, and returns a Laravel Collection of these objects. @@ -34,7 +33,6 @@ Follow these conventions and creating dynamic static sites will be a breeze. 8. You can customize the source directory for collections through a service provider. 9. If the base source directory does not exist, it will be created for you. - ## Available Collection Types ### Quick Reference Overview @@ -55,7 +53,6 @@ The following facade methods for creating data collections are available: | **[Yaml](#yaml-collections)** | `::yaml()` | [`FrontMatter`](https://github.com/hydephp/framework/blob/master/src/Markdown/Models/FrontMatter.php) | `.yaml`,  `.yml` | | **[Json](#json-collections)** | `::json()` | [`stdClass`](https://www.php.net/manual/en/class.stdclass.php) OR  [`array`](https://www.php.net/manual/en/language.types.array.php) | `.json` | - ## Markdown Collections ### Usage @@ -102,7 +99,6 @@ author: "John Doe" Lorem ipsum dolor sit amet, consectetur adipiscing elit... ``` - ## YAML Collections ### Usage @@ -149,7 +145,6 @@ $collection = \Hyde\Support\DataCollections::json('name', true); Since both return values use native PHP types, there are no example returns added here, as I'm sure you can imagine what they look like. - ## Markdown Collections - Hands-on Guide I think the best way to explain DataCollections is through examples, so let's create a Blade page with customer testimonials! diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 27e4ab49553..d835266bdf0 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -15,7 +15,6 @@ if you need it. This page guides you through the many options available! All the configuration files are stored in the config directory, and allow you to customize almost all aspects of your site. Each option is documented, so feel free to look through the files and get familiar with the options available to you. - ## Accessing Configuration Values ### Configuration API Recap @@ -58,7 +57,6 @@ In some cases, the same options can be set in the front matter of a page or in a When Hyde references files, especially when passing filenames between components, the file path is almost always relative to the root of the project. Specifying absolute paths yourself could lead to unforeseen problems. - ## Configuration Files Overview There are a few configuration files available in the `config` directory. All options are documented, so feel free to look through the files and get familiar with the options available to you. @@ -96,7 +94,6 @@ base HydePHP installation. However, you can publish them to your project by runn If any of these files are missing, you can run `php hyde publish:configs` to copy the default files to your project. - ## Configuration Options While all options are already documented within the files, here are some further explanations of some of the options. @@ -216,6 +213,7 @@ Note that the HTML is added to all pages. If you need to add HTML to a specific ```yaml # filepath: hyde.yml + hyde: head: "" scripts: "" @@ -261,7 +259,6 @@ Learn more in the [Navigation Menu](navigation) documentation. Learn more in the [Documentation Pages](documentation-pages) documentation. - ## Additional Advanced Options The following configuration options in the `config/hyde.php` file are intended for advanced users and @@ -350,14 +347,12 @@ php hyde publish:views The files will then be available in the `resources/views/vendor/hyde` directory. - ## Frontend Styles Hyde is designed to not only serve as a framework but a whole starter kit and comes with a Tailwind starter template for you to get up and running quickly. If you want to customize these, you are free to do so. Please see the [Managing Assets](managing-assets) page to learn more. - ## Markdown Configuration Hyde uses [League CommonMark](https://commonmark.thephpleague.com/) for converting Markdown into HTML, and @@ -420,7 +415,6 @@ arbitrary PHP code specified in Markdown to be executed. It's easy to enable how See the [Blade in Markdown](advanced-markdown#blade-support) documentation for more information on how to use this feature. - ## YAML Configuration The settings in the `config/hyde.php` file can also be set by using a `hyde.yml` file in the root of your project directory. @@ -433,6 +427,7 @@ Here is an example showing some of the `config/hyde.php` file settings, and how ```yaml # filepath hyde.yml + name: HydePHP url: "http://localhost" pretty_urls: false @@ -455,6 +450,7 @@ This feature is automatically enabled when you have a `hyde:` entry **first** in ```yaml # filepath hyde.yml + hyde: name: HydePHP diff --git a/docs/digging-deeper/helpers.md b/docs/digging-deeper/helpers.md index 515714b8d1e..b75147651e0 100644 --- a/docs/digging-deeper/helpers.md +++ b/docs/digging-deeper/helpers.md @@ -11,7 +11,6 @@ navigation: HydePHP comes with a few helper classes and utilities to make your life easier. This page will cover some of the most important ones. Note that these helpers targets those who write custom code and Blade templates, and that you are expected to have a basic understanding of programming and PHP. - ## File-based Collections Hyde provides `DataCollections`, a subset of [Laravel Collections](https://laravel.com/docs/10.x/collections) giving you a similar developer experience to working with Eloquent Collections. However, instead of accessing a database, @@ -32,7 +31,6 @@ DataCollections::json(string $name, bool $asArray = false); See the [File-based Collections](collections) documentation for the full details. - ## File Includes The Includes facade provides a simple way to access partials in the includes directory. @@ -98,7 +96,6 @@ If a `head.html` file exists in the includes directory, Hyde include that within If a `scripts.html` file exists in the includes directory, Hyde include that at the end of the `` tag of the generated HTML, in addition to the one set in the `hyde.scripts` config option. - ## Reading-Time Helper The `ReadingTime` helper provides a simple way to calculate the reading time of a given string, for example a blog post. diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index bf826c329b9..8368204054f 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -60,7 +60,6 @@ General options for the entire navigation menus are also available in the `hyde` Now that you know the basics, let's dive into the details of how to customize the navigation menus! - ## Front Matter Configuration The front matter options allow you to customize the navigation menus on a per-page basis. @@ -114,7 +113,6 @@ navigation: group: "My Group" ``` - ## Config File Configuration Next up, let's look at how to customize the navigation menus using the config files. @@ -290,7 +288,6 @@ For example: `_docs/getting-started/installation.md` will be placed in a group c >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. - ## Digging Deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. diff --git a/docs/digging-deeper/troubleshooting.md b/docs/digging-deeper/troubleshooting.md index a94ffe2c37e..dbea18f6201 100644 --- a/docs/digging-deeper/troubleshooting.md +++ b/docs/digging-deeper/troubleshooting.md @@ -11,7 +11,6 @@ did you find a new one? Send a PR to [update the docs](https://github.com/hydeph >info Tip: You can run `php hyde validate` to run a series of tests to help you catch common issues. - ## General Tips (In no particular order of importance) @@ -22,7 +21,6 @@ did you find a new one? Send a PR to [update the docs](https://github.com/hydeph 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 @@ -44,7 +42,6 @@ Remember, files retain their base filenames when compiled to HTML. - ✔ **Do** use the proper file extensions - ❌ **Don't** use conflicting source file names - ## Extra Information ### Definitions @@ -67,7 +64,6 @@ We will use the following definitions to describe the behaviour of Hyde. You can read more about some of these in the [Core Concepts](core-concepts#paths-identifiers-and-route-keys) article. - ## Common Issues, Causes, and Solutions | Issue | Possible Cause / Issue Context | Possible Solution | diff --git a/docs/digging-deeper/updating-hyde.md b/docs/digging-deeper/updating-hyde.md index 225d1018201..612f20f3fde 100644 --- a/docs/digging-deeper/updating-hyde.md +++ b/docs/digging-deeper/updating-hyde.md @@ -7,13 +7,11 @@ navigation: This guide will help you update your HydePHP project to the latest version. - ## Before You Start When updating an existing installation, first ensure that you have a backup of your project in case anything goes wrong. The recommended way to do this is to use Git as that allows you to smoothly roll back any changes. - ## Version Compatibility HydePHP follows [semantic versioning](https://semver.org/), so you can expect that minor and patch releases will be backwards compatible. @@ -77,7 +75,6 @@ An alternate way to update your project is to essentially do a hard reset. This Essentially: Download the [latest release](https://github.com/hydephp/hyde/releases/latest) from GitHub, extract it to a new project directory, then copy over your source files and install the dependencies. - ## Post-update instructions After updating Hyde you should update your config and resource files. This is where things can get a tiny bit dangerous diff --git a/docs/extensions/extensions.md b/docs/extensions/extensions.md index a94ffbe47b4..5bb8d4653f9 100644 --- a/docs/extensions/extensions.md +++ b/docs/extensions/extensions.md @@ -11,7 +11,6 @@ navigation: HydePHP is designed to be extensible, and comes with a number of built-in extensions and integrations, as well as support for third-party extensions and integrations. - ## First-Party Extensions & Integrations ### Realtime Compiler @@ -29,7 +28,6 @@ The [HydePHP UI Kit](https://github.com/hydephp/ui-kit) is a set of minimalistic The [GitHub Action for HydePHP](https://github.com/hydephp/action) is hands-down the easiest way to build and deploy your Hyde site to GitHub Pages. - Learn more at https://github.com/hydephp/action and see the documentation at https://hydephp.github.io/action - ## Integration with Third-Party Services All third-party integrations are listed on the [Third-Party Integrations](third-party-integrations) page. Below is a summary. @@ -39,7 +37,6 @@ All third-party integrations are listed on the [Third-Party Integrations](third- Torchlight is an amazing API for syntax highlighting, and is supported natively by HydePHP. - Learn more about [Torchlight](third-party-integrations#torchlight) in the documentation. - ## Contribute Have an idea for an extension or integration? Let me know! I'd love to hear from you. Get in touch on diff --git a/docs/extensions/ui-kit.md b/docs/extensions/ui-kit.md index 84ebe97d178..b632c0719cc 100644 --- a/docs/extensions/ui-kit.md +++ b/docs/extensions/ui-kit.md @@ -4,14 +4,12 @@ The HydePHP UI Kit is a collection of minimalistic and un-opinionated TailwindCS indented to be used with HydePHP. Note that these components may require CSS classes not present in the bundled app.css file and that you may need to recompile the CSS file using the included Laravel Mix configuration. - ## Screenshot Here are some of the components you can use to build your next project! As you can see, all components support both light and dark mode out of the box, just like the rest of HydePHP. ![Components Screenshot](https://raw.githubusercontent.com/hydephp/ui-kit/art/header-large-min.png) - ## Components Please make sure you're familiar with [Laravel Blade](https://laravel.com/docs/blade) before using the HydePHP UI Kit. @@ -161,7 +159,6 @@ You can get surprisingly far when you combine the components. Take this newslett ![Newsletter Screenshot](https://raw.githubusercontent.com/hydephp/ui-kit/art/newsletter-signup-example-min.png) - ## GitHub Repository You can find the source code for the UI Kit on GitHub at [hydephp/ui-kit](https://github.com/hydephp/ui-kit). diff --git a/docs/getting-started/console-commands.md b/docs/getting-started/console-commands.md index 0b0a61138fc..bcdc5552f40 100644 --- a/docs/getting-started/console-commands.md +++ b/docs/getting-started/console-commands.md @@ -10,7 +10,6 @@ The primary way of interacting with Hyde is through the command line using the H If you have ever used the Artisan Console in Laravel you will feel right at home, the HydeCLI is based on Artisan after all! - ## Introduction To use the HydeCLI, run `php hyde` from your project directory followed by a command. @@ -40,7 +39,6 @@ You can also always add `--help` to a command to show detailed usage information php hyde --help ``` - ## Available Commands Here is a quick reference of all the available commands. You can also run `php hyde list` to see this list. @@ -63,7 +61,6 @@ Here is a quick reference of all the available commands. You can also run `php h | [`validate`](#validate) | Run a series of tests to validate your setup and help you optimize your site | | [`list`](#available-commands) | List all available commands | - ## Build the Static Site @@ -84,7 +81,6 @@ Build the static site | `--pretty-urls` | Should links in output use pretty URLs? | | `--no-api` | Disable API calls, for example, Torchlight | - ## Run the static site builder for a single file @@ -101,7 +97,6 @@ Run the static site builder for a single file |--------|--------------------------------------------------------------------------------| | `path` | The relative file path (example: \_posts/hello-world.md) \n - Is required: yes | - ## Start the Realtime Compiler Server @@ -119,7 +114,6 @@ Start the realtime compiler server. | `--host=` | [default: "localhost"] | | `--port=` | [default: 8080] | - ## Test and validate your project to optimize your site @@ -130,7 +124,6 @@ php hyde validate Run a series of tests to validate your setup and help you optimize your site. - ## Generate the RSS Feed @@ -141,7 +134,6 @@ php hyde build:rss Generate the RSS feed - ## Generate the `docs/search.json` file @@ -152,7 +144,6 @@ php hyde build:search Generate the `docs/search.json` file - ## Generate the `sitemap.xml` file @@ -163,7 +154,6 @@ php hyde build:sitemap Generate the `sitemap.xml` file - ## Scaffold a new Markdown, Blade, or documentation page file @@ -184,7 +174,6 @@ Scaffold a new Markdown, Blade, or documentation page file | `--docs` | Create a Documentation page | | `--force` | Overwrite any existing files | - ## Scaffold a new Markdown blog post file @@ -202,7 +191,6 @@ Scaffold a new Markdown blog post file | `title` | The title for the Post. Will also be used to generate the filename | | `--force` | Should the generated file overwrite existing posts with the same filename? | - ## Publish the Default Configuration Files @@ -213,7 +201,6 @@ php hyde publish:configs Publish the default configuration files - ## Publish one of the default homepages as `index.blade.php`. @@ -231,7 +218,6 @@ Publish one of the default homepages as `index.blade.php`. | `homepage` | The name of the page to publish | | `--force` | Overwrite any existing files | - ## Publish the hyde components for customization @@ -248,7 +234,6 @@ Publish the hyde components for customization. Note that existing files will be |------------|-------------------------| | `category` | The category to publish | - ## Display all Registered Routes. @@ -259,7 +244,6 @@ php hyde route:list Display all registered routes. - ## Publish any publishable assets from vendor packages diff --git a/docs/getting-started/core-concepts.md b/docs/getting-started/core-concepts.md index 9d7fe4d6eff..9ebb4d9fd41 100644 --- a/docs/getting-started/core-concepts.md +++ b/docs/getting-started/core-concepts.md @@ -14,7 +14,6 @@ All designed so that you can focus on your content, while the framework does the This page provides a high-level overview of the framework's capabilities, so you can quickly grasp its benefits. As you delve deeper into the documentation, you'll discover the details of each feature and learn how to leverage them effectively. - ## The HydeCLI When you are not writing Markdown and Blade, most of your interactions with Hyde will be through the command line @@ -29,7 +28,6 @@ php hyde help php hyde [--help] ``` - ## Directory Structure To take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure. @@ -46,7 +44,6 @@ To take full advantage of the framework, it may first be good to familiarize our | `resources/views` | Location for Blade components (optional) | | `app` | Location for custom PHP classes (optional) | - ## Page Models The Hyde page models are an integral part of how HydePHP creates your static site. Each page in your site is represented @@ -60,7 +57,6 @@ The page classes are very important and fill two roles: To learn more, you can visit the [Page Models](page-models) page. - ## File Autodiscovery Content files, meaning source Markdown and Blade files, are automatically discovered by Hyde and compiled to HTML when @@ -77,7 +73,6 @@ All source and output directories are configurable, but the defaults are as foll | Documentation | `_docs/` | `_site/docs/` | `.md` | | Media Assets | `_media/` | `_site/media/` | Common asset types | - ## Paths, Identifiers, and Route Keys Since HydePHP automatically discovers and compiles content files, it is important to understand how HydePHP handles paths, @@ -105,14 +100,12 @@ This can be visualized as follows, assuming a blog post is stored as `_posts/hel As you can see, the route key is simply put the relative page URL, without the .html extension. - ## Convention over Configuration Hyde favours the "Convention over Configuration" paradigm and thus comes preconfigured with sensible defaults. However, Hyde also strives to be modular and endlessly customizable hackable if you need it. Take a look at the [customization and configuration guide](customization) to see the endless options available! - ## Front Matter >info **In a nutshell:** Front Matter is a block of YAML containing metadata, stored at the top of a Markdown file. @@ -148,7 +141,6 @@ where code in `@php` directives are statically parsed into page object's front m @php($title = 'BladeMatter Demo') // Equivalent to `title: 'BladeMatter Demo'` in Yaml ``` - ## Automatic Routing >info **In a nutshell:** Hyde will automatically create routes for your source files. @@ -173,7 +165,6 @@ Routes::get('posts/my-post') To learn more about the routing system, please visit the [routing documentation](automatic-routing). - ## Global Page Data During the build of each page, Hyde will inject some data available to all Blade views. If you are not planning to write @@ -188,7 +179,6 @@ Depending on the page type, you will have different helpers available. But `$pag You can see all the helpers in the [Page API](hyde-pages) reference page. - ## Terminology In this quick reference, we'll briefly go over some terminology and concepts used in HydePHP. diff --git a/docs/getting-started/front-matter.md b/docs/getting-started/front-matter.md index aa09a764fb3..31e335dfcc0 100644 --- a/docs/getting-started/front-matter.md +++ b/docs/getting-started/front-matter.md @@ -13,7 +13,6 @@ For example, in a blog post you may define a category, author website, or featur Using front matter is optional, as Hyde will dynamically generate data based on the content itself. (Though any matter you provide will take precedence over the automatically generated data.) While Hyde offers some support for front matter within Blade files, most of the time you use front matter, it will be in Markdown. - ## Front Matter Syntax Here's a refresher on Yaml, and a quick reference of the syntax Hyde uses and expects: diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index b2083000d63..6f962d031cf 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -23,12 +23,10 @@ You should also have [Composer](https://getcomposer.org/) installed. To use some features like [compiling your own assets](managing-assets) you also need NodeJS and NPM. - ## Using the Hyde CLI The main way to interact with Hyde is through the [HydeCLI](console-commands), a Laravel Artisan-based command-line interface. Learn more about the HydeCLI in the [console commands](console-commands) documentation. - ## Starting a Development Server To make previewing your site a breeze you can use the realtime compiler, which builds your pages on the fly. @@ -38,7 +36,6 @@ php hyde serve ``` Simply run the serve command, and you will be able to preview your site at [http://localhost:8080](http://localhost:8080). - ## Creating Content ### Directory structure @@ -79,7 +76,6 @@ You are now ready to show your site to the world! Simply copy the `_site` direct You can even use GitHub Pages to host your site for free. That's what the Hyde website does, using an Actions CI workflow that automatically builds and deploys this site. - ## Further Reading Here's some ideas of what to read next: diff --git a/docs/index.md b/docs/index.md index 7e4252fd6ac..86636842179 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,6 @@ ![License MIT](https://img.shields.io/github/license/hydephp/hyde) {.images-inline .not-prose} - ## About HydePHP HydePHP is a Static Site Generator focused on writing content, not markup. With Hyde, it is easy to create static @@ -31,7 +30,6 @@ endless configuration. Instead, when you create a new Hyde project, everything y Hyde was inspired by JekyllRB and is designed for developers who are comfortable writing posts in Markdown, and it requires virtually no configuration out of the box as it favours convention over configuration and is preconfigured with sensible defaults. - ## Installation HydePHP is a command-line interface (CLI) application that is installed on a per-project basis. @@ -50,7 +48,6 @@ Once installed, you can access the HydeCLI from the project root using the `hyde php hyde info ``` - ## Usage Creating static websites with HydePHP is incredibly easy. First you need some content. You can just drop Markdown files diff --git a/monorepo/scripts/docs/MarkdownFormatter.php b/monorepo/scripts/docs/MarkdownFormatter.php index 0d3dd756386..a4200fae602 100644 --- a/monorepo/scripts/docs/MarkdownFormatter.php +++ b/monorepo/scripts/docs/MarkdownFormatter.php @@ -77,8 +77,8 @@ protected function run(): void $new_lines[] = ''; } - // Make sure there are two empty lines before level 2 headings (but not if it's the first l2 heading) - if ($is_inside_fenced_code_block !== true && str_starts_with($line, '## ') && $index > $firstHeadingLevel + 3) { + // Make sure there is exactly one empty line before any heading + if (! $is_inside_fenced_code_block && preg_match('/^#{1,6} /', $line) && trim($last_line) != '') { $new_lines[] = ''; } @@ -87,7 +87,7 @@ protected function run(): void } // Check if line is a heading - if (str_starts_with($line, '##')) { + if (preg_match('/^#{1,6} /', $line)) { $was_last_line_heading = true; global $headings; $headings[$filename][$index + 1] = $line;