diff --git a/docs/advanced-features/build-tasks.md b/docs/advanced-features/build-tasks.md index dc9a23cdf68..f178db9d8b9 100644 --- a/docs/advanced-features/build-tasks.md +++ b/docs/advanced-features/build-tasks.md @@ -32,7 +32,7 @@ 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 +## Creating Build Tasks ### Minimal example @@ -103,7 +103,7 @@ 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 +## Registering the Tasks There are a few ways to register these tasks so Hyde can find them. diff --git a/docs/advanced-features/in-memory-pages.md b/docs/advanced-features/in-memory-pages.md index e9377b91f22..689ddc41669 100644 --- a/docs/advanced-features/in-memory-pages.md +++ b/docs/advanced-features/in-memory-pages.md @@ -24,7 +24,7 @@ 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 +## Creating the Page To create an InMemoryPage, you need to instantiate it with the required parameters. diff --git a/docs/architecture-concepts/architecture-concepts.md b/docs/architecture-concepts/architecture-concepts.md index 077fc8e0fc0..fda816a79fe 100644 --- a/docs/architecture-concepts/architecture-concepts.md +++ b/docs/architecture-concepts/architecture-concepts.md @@ -20,7 +20,7 @@ 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 +## 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 8981975088b..74381b4ad02 100644 --- a/docs/architecture-concepts/autodiscovery.md +++ b/docs/architecture-concepts/autodiscovery.md @@ -19,7 +19,7 @@ Before reading this article, you should be familiar with the following concepts: - [The HydeKernel](the-hydekernel) -## Booting pipeline +## Booting Pipeline The autodiscovery is run when the HydeKernel boots. It does so in three distinct steps, which run in sequence as each step depends on the previous one. Each discovery step runs in a `FoundationCollection` which both runs the actual diff --git a/docs/architecture-concepts/extensions-api.md b/docs/architecture-concepts/extensions-api.md index f6abd2b4109..a9891b63255 100644 --- a/docs/architecture-concepts/extensions-api.md +++ b/docs/architecture-concepts/extensions-api.md @@ -37,7 +37,7 @@ can be added the same way as you would in Laravel, and are thus not part of our See the [Laravel package development guide](https://laravel.com/docs/10.x/packages) for more. -## Creating your Extension class +## Creating Your Extension Class The entry-point for your extension is your Extensions class. Within this, you can register the custom page classes. If needed, you can also register discovery handlers which can run custom logic at various parts of the boot process. @@ -114,7 +114,7 @@ Since the discovery steps are handled sequentially, the added pages will automat us having to implement that handler method. As we inject the page objects directly, we bypass the need for the `FileCollection`. -## Registering your extension +## 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 69d158237d0..aa247c83ae9 100644 --- a/docs/architecture-concepts/page-models.md +++ b/docs/architecture-concepts/page-models.md @@ -13,7 +13,7 @@ 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 +## The Short Version #### Page models are classes that have two primary concerns: diff --git a/docs/architecture-concepts/the-hydekernel.md b/docs/architecture-concepts/the-hydekernel.md index 55d2c494c2d..2f4e0d9b43f 100644 --- a/docs/architecture-concepts/the-hydekernel.md +++ b/docs/architecture-concepts/the-hydekernel.md @@ -19,7 +19,7 @@ The kernel is created very early on in the application lifecycle, in the `bootst as a singleton into the application service container. -## Accessing the kernel +## 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. @@ -44,7 +44,7 @@ hyde()->version(); The Kernel instance is constructed in `bootstrap.php`, and is available globally as `$hyde`. -## The kernel lifecycle +## The Kernel Lifecycle Whenever we talk about the kernel being "booted" we are talking about the kernel's role in the autodiscovery process. diff --git a/docs/creating-content/blog-posts.md b/docs/creating-content/blog-posts.md index 41f7f087ced..70f4b454e26 100644 --- a/docs/creating-content/blog-posts.md +++ b/docs/creating-content/blog-posts.md @@ -66,7 +66,7 @@ author: Mr. Hyde date: 2022-05-09 18:38 --- -## Write your Markdown here +## Write Your Markdown Here Lorem ipsum dolor sit amet, consectetur adipisicing elit. Autem aliquid alias explicabo consequatur similique, @@ -74,7 +74,7 @@ animi distinctio earum ducimus minus, magnam. ``` -## Supported Front Matter properties +## Supported Front Matter Properties ### Post Front Matter Schema @@ -202,7 +202,7 @@ image: { .info } -## Using images in posts +## 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 bfdb31f909d..732e524bf01 100644 --- a/docs/creating-content/compile-and-deploy.md +++ b/docs/creating-content/compile-and-deploy.md @@ -6,7 +6,7 @@ navigation: # Compile and Deploy your site -## Running the build command +## Running the Build Command Now that you have some amazing content, you'll want to compile your site into static HTML. @@ -41,7 +41,7 @@ php hyde serve --- -## Deploying your site +## Deploying Your Site One of the things that make static sites so enjoyable to work with is how easy it is to deploy them to the web. This list is not exhaustive, but gives you a general idea of the most common ways to deploy your site. diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 383828a5280..91126dd70a0 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -76,7 +76,7 @@ navigation: ``` -## Dynamic content generation +## 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. @@ -278,7 +278,7 @@ If you set this to false, Hyde will match the directory structure of the source ``` -## Search feature +## Search Feature ### Introduction diff --git a/docs/creating-content/managing-assets.md b/docs/creating-content/managing-assets.md index 86a66e1a38f..481bad7cc94 100644 --- a/docs/creating-content/managing-assets.md +++ b/docs/creating-content/managing-assets.md @@ -56,7 +56,7 @@ The `_site` directory is intended to be excluded from version control, while 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? +## 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`. @@ -111,7 +111,7 @@ 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 +## 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/docs/creating-content/static-pages.md b/docs/creating-content/static-pages.md index c5171d3d11d..e793f5960c5 100644 --- a/docs/creating-content/static-pages.md +++ b/docs/creating-content/static-pages.md @@ -124,7 +124,7 @@ if you don't want to use the scaffolding command. > however you still need to use the `blade.php` extension so Hyde can recognize it. -## 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. diff --git a/docs/digging-deeper/advanced-customization.md b/docs/digging-deeper/advanced-customization.md index 5270878d0f3..1b08fd88dcd 100644 --- a/docs/digging-deeper/advanced-customization.md +++ b/docs/digging-deeper/advanced-customization.md @@ -29,7 +29,7 @@ is registered, at which point the provider will search for any overrides in the trait to use the same registration logic as the `HydeServiceProvider`. -## Customizing source directories +## Customizing Source Directories The directories you place your content in are important. The directory will be used to determine the proper page type and the templates used. If you are not happy the with defaults, you can change them. Note that these are relative to the `source_root` setting, @@ -71,7 +71,7 @@ public function register(): void ``` -## Customizing output directories +## Customizing Output Directories Like source directories, the output directories are also important as they determine the output path for the compiled pages. >warning Note that changing output directories also affects the route keys, as those are based on the output directory.

Scroll down to see the [Route key impact](#route-key-impact) section for more information.

@@ -117,7 +117,7 @@ this may break your site's configuration and links, so you should always verify You can learn more about this in the [route key documentation](core-concepts#paths-identifiers-and-route-keys). -## Custom source root +## Custom Source Root HydePHP will by default look for the source directories shown above in the root of your project. If you're not happy with this, it's easy to change! For example, you might want everything in a `'src'` subdirectory. @@ -142,7 +142,7 @@ When run, Hyde will update the source directory setting in the config file, then and move all source directories and their content into it. -## Custom media directory +## Custom Media Directory The media directory houses assets like images and stylesheets. The default directory is `_media`, and upon building the site, Hyde will copy all files in this directory to `_site/media` (or whatever your configured output and media directories are). @@ -166,7 +166,7 @@ all files from `assets` will be copied to `_site/assets`. If the setting starts from the output directory, so files in `_assets` will be copied to `_site/assets`. -## Custom output directory +## 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 149b7f53b06..b36f577e639 100644 --- a/docs/digging-deeper/advanced-markdown.md +++ b/docs/digging-deeper/advanced-markdown.md @@ -107,7 +107,7 @@ The coloured blockquotes also support inline Markdown, just like normal blockquo Note that these currently do not support multi-line blockquotes. -## Code block filepaths +## Code Block Filepaths When browsing these documentation pages you may have noticed a label in the top right corner of code blocks specifying the file path. These are also created by using a custom Hyde feature that turns code comments into automatic code blocks. diff --git a/docs/digging-deeper/collections.md b/docs/digging-deeper/collections.md index efe68e3d633..f0ebb7b79fb 100644 --- a/docs/digging-deeper/collections.md +++ b/docs/digging-deeper/collections.md @@ -103,7 +103,7 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit... ``` -## Yaml Collections +## YAML Collections ### Usage diff --git a/docs/digging-deeper/helpers.md b/docs/digging-deeper/helpers.md index b60c7fb16f2..cb63815abce 100644 --- a/docs/digging-deeper/helpers.md +++ b/docs/digging-deeper/helpers.md @@ -91,7 +91,7 @@ HydePHP also supports some drop-in includes that you can use as an alternative t - 'scripts' 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 +## Reading Time Helper The `ReadingTime` helper provides a simple way to calculate the reading time of a given string, for example a blog post. @@ -180,7 +180,7 @@ $time->formatUsingClosure(function (int $minutes, int $seconds): string { ``` -## Pagination utility +## Pagination Utility The `Pagination` class provides utilities to help you create custom pagination components. diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 051ca1661e7..a9d865d45df 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -61,7 +61,7 @@ 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 +## Front Matter Configuration The front matter options allow you to customize the navigation menus on a per-page basis. Here is a quick reference of the available options. The full documentation of each option is below. @@ -115,7 +115,7 @@ navigation: ``` -## Config file configuration +## Config File Configuration Next up, let's look at how to customize the navigation menus using the config files. @@ -291,7 +291,7 @@ 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 +## Digging Deeper into the internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. The best way to learn about this is to look at the source code, so here is a high-level overview with details on where to look in the source code. diff --git a/docs/digging-deeper/troubleshooting.md b/docs/digging-deeper/troubleshooting.md index 96380c23c08..a94ffe2c37e 100644 --- a/docs/digging-deeper/troubleshooting.md +++ b/docs/digging-deeper/troubleshooting.md @@ -23,7 +23,7 @@ did you find a new one? Send a PR to [update the docs](https://github.com/hydeph For example, Hyde makes attempts to guess the title for a page depending on the content. (Headings, filenames, etc). -## Conventions to follow +## Conventions to Follow ### File naming @@ -68,7 +68,7 @@ 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 +## 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 f12d23790a4..bc3c0948459 100644 --- a/docs/digging-deeper/updating-hyde.md +++ b/docs/digging-deeper/updating-hyde.md @@ -8,13 +8,13 @@ navigation: This guide will help you update your HydePHP project to the latest version. -## Before you start +## 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 +## Version Compatibility HydePHP follows [semantic versioning](https://semver.org/), so you can expect that minor and patch releases will be backwards compatible. Only major releases may introduce breaking changes, all of which are thoroughly documented in the accompanying release notes. diff --git a/docs/getting-started/console-commands.md b/docs/getting-started/console-commands.md index 0d9d79b202f..66b6f945123 100644 --- a/docs/getting-started/console-commands.md +++ b/docs/getting-started/console-commands.md @@ -67,7 +67,7 @@ Here is a quick reference of all the available commands. You can also run `php h | [`list`](#available-commands) | List all available commands | -## Build the static site +## Build the Static Site @@ -107,7 +107,7 @@ 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 +## Start the Realtime Compiler Server @@ -138,7 +138,7 @@ php hyde validate Run a series of tests to validate your setup and help you optimize your site. -## Generate the RSS feed +## Generate the RSS Feed @@ -215,7 +215,7 @@ Scaffold a new Markdown blog post file | `--force` | Should the generated file overwrite existing posts with the same filename? | -## Publish the default configuration files +## Publish the Default Configuration Files @@ -264,7 +264,7 @@ Publish the hyde components for customization. Note that existing files will be | `category` | The category to publish | -## Display all registered routes. +## Display all Registered Routes. diff --git a/docs/getting-started/core-concepts.md b/docs/getting-started/core-concepts.md index aff17c20e5a..9d7fe4d6eff 100644 --- a/docs/getting-started/core-concepts.md +++ b/docs/getting-started/core-concepts.md @@ -30,7 +30,7 @@ php hyde [--help] ``` -## Directory structure +## Directory Structure To take full advantage of the framework, it may first be good to familiarize ourselves with the directory structure. diff --git a/docs/getting-started/front-matter.md b/docs/getting-started/front-matter.md index a14503cfbd8..aa09a764fb3 100644 --- a/docs/getting-started/front-matter.md +++ b/docs/getting-started/front-matter.md @@ -14,7 +14,7 @@ Using front matter is optional, as Hyde will dynamically generate data based on 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 +## 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 e5864d40af2..87e0ecf752b 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -6,7 +6,7 @@ navigation: # Quickstart Guide -## Installing HydePHP using Composer +## Installing HydePHP Using Composer The recommended method of installing Hyde is using Composer, which installs the required dependencies on a per-project basis. @@ -30,7 +30,7 @@ you also need NodeJS and NPM. 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 +## Starting a Development Server To make previewing your site a breeze you can use the realtime compiler, which builds your pages on the fly. @@ -40,7 +40,7 @@ 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 +## Creating Content ### Directory structure @@ -81,7 +81,7 @@ 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 +## Further Reading Here's some ideas of what to read next: diff --git a/monorepo/scripts/docs/MarkdownFormatter.php b/monorepo/scripts/docs/MarkdownFormatter.php index 5f7e37082cc..0d3dd756386 100644 --- a/monorepo/scripts/docs/MarkdownFormatter.php +++ b/monorepo/scripts/docs/MarkdownFormatter.php @@ -20,6 +20,7 @@ // Buffer headings so we can check for style $headings = []; // [filename => [line => heading]] $checksHeadings = false; +$fixesHeadings = false; class MarkdownFormatter { @@ -444,6 +445,9 @@ function getSignatures(): array $headings['foo.md'][1] = '## Bar'; if ($checksHeadings && count($headings)) { + // Needed to use the make_title function + \Hyde\Foundation\HydeKernel::setInstance(new \Hyde\Foundation\HydeKernel()); + foreach ($headings as $filename => $fileHeadings) { $headingLevels = []; foreach ($fileHeadings as $heading) { @@ -453,14 +457,22 @@ function getSignatures(): array // Check for style: 1-2 headings should be title case, 3+ should be sentence case $headingText = trim(str_replace('#', '', $heading)); $titleCase = Hyde\make_title($headingText); - $alwaysUppercase = ['PHP', 'HTML', 'CLI']; - $alwaysLowercase = ['to']; + $alwaysUppercase = ['PHP', 'HTML', 'CLI', 'API', 'YAML', 'XML', 'RSS', 'HydeKernel', 'GitHub']; + $alwaysLowercase = ['to', 'it']; $titleCase = str_ireplace($alwaysUppercase, $alwaysUppercase, $titleCase); $titleCase = str_ireplace($alwaysLowercase, $alwaysLowercase, $titleCase); $isTitleCase = $headingText === $titleCase; $sentenceCase = Str::ucfirst($headingText); $isSentenceCase = $headingText === $sentenceCase; + + // If it's just one word, or if it's more than 5 words, we can ignore it + $canIgnore = str_word_count($headingText) === 1 || str_word_count($headingText) > 5; + + if ($canIgnore) { + continue; + } + $something = false; if ($headingLevel < 3) { if (! $isTitleCase) { @@ -471,6 +483,20 @@ function getSignatures(): array $warnings['Headings'][] = "Heading '$headingText' should be sentence case in $filename (expected '$sentenceCase')"; } } + + if ($fixesHeadings) { + // Replace the heading with the expected case + + $headingHashes = str_repeat('#', $headingLevel); + $useCase = $headingLevel < 3 ? $titleCase : $sentenceCase; + $newHeading = "$headingHashes $useCase"; + + $newContent = file_get_contents($filename); + $newContent = str_replace($heading, $newHeading, $newContent); + file_put_contents($filename, $newContent); + + echo "Fixed heading '$headingText' to '$newHeading' in $filename\n"; + } } } }