From 0a5fe4c86bfa5611e11843f8a8a2922a7c7d0c07 Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Tue, 30 Sep 2025 21:45:48 +0200
Subject: [PATCH 01/11] Add upgrade guide

---
 UPGRADE.md                            | 461 +++++++++++++++++++++++++
 docs/getting-started/upgrade-guide.md | 467 ++++++++++++++++++++++++++
 2 files changed, 928 insertions(+)
 create mode 100644 UPGRADE.md
 create mode 100644 docs/getting-started/upgrade-guide.md

diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 00000000000..4f39938c6d8
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,461 @@
+# HydePHP v2.0 Upgrade Guide
+
+## Prerequisites
+
+Before upgrading to HydePHP v2.0, ensure your application is running **HydePHP v1.6 or later** (ideally v1.8). These versions include transition helpers that will make the migration process smoother.
+
+## Step 1: Update Dependencies
+
+### Update Composer Dependencies
+
+Open your `composer.json` file and update the following dependencies:
+
+```json
+{
+    "require": {
+        "php": "^8.2",
+        "hyde/framework": "^2.0",
+        "laravel-zero/framework": "^11.0"
+    },
+    "require-dev": {
+        "hyde/realtime-compiler": "^4.0"
+    }
+}
+```
+
+Then run:
+
+```bash
+composer update
+```
+
+### Update Node Dependencies
+
+Open your `package.json` file and replace the entire `devDependencies` section:
+
+**Before (v1.x with Laravel Mix):**
+```json
+{
+    "devDependencies": {
+        "@tailwindcss/typography": "^0.5.2",
+        "autoprefixer": "^10.4.5",
+        "hydefront": "^3.4.1",
+        "laravel-mix": "^6.0.49",
+        "postcss": "^8.4.31",
+        "tailwindcss": "^3.0.24"
+    }
+}
+```
+
+**After (v2.x with Vite):**
+```json
+{
+    "type": "module",
+    "devDependencies": {
+        "@tailwindcss/typography": "^0.5.19",
+        "@tailwindcss/vite": "^4.1.13",
+        "autoprefixer": "^10.4.21",
+        "hyde-vite-plugin": "^1.0.0-RC.5",
+        "hydefront": "^4.0.0-RC.1",
+        "postcss": "^8.5.6",
+        "tailwindcss": "^4.1.13",
+        "vite": "^7.1.7"
+    }
+}
+```
+
+Update the npm scripts in your `package.json`:
+
+```json
+{
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build"
+    }
+}
+```
+
+Then run:
+
+```bash
+npm install
+npm run build
+```
+
+## Step 2: Migrate from Laravel Mix to Vite
+
+### Delete the old Mix configuration
+
+Remove the `webpack.mix.js` file from your project root.
+
+### Create the new Vite configuration
+
+Create a new `vite.config.js` file in your project root:
+
+```javascript
+import { defineConfig } from 'vite';
+import tailwindcss from "@tailwindcss/vite";
+import hyde from 'hyde-vite-plugin';
+
+export default defineConfig({
+    plugins: [
+        hyde({
+            input: ['resources/assets/app.css', 'resources/assets/app.js'],
+            watch: ['_pages', '_posts', '_docs'],
+            refresh: true,
+        }),
+        tailwindcss(),
+    ],
+});
+```
+
+### Update your CSS imports
+
+Update `resources/assets/app.css`:
+
+**Before:**
+```css
+@import '~hydefront/dist/hyde.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+[x-cloak] { display: none !important; }
+```
+
+**After:**
+```css
+@import 'hydefront/components/torchlight.css' layer(base);
+
+@import 'tailwindcss';
+
+@config '../../tailwind.config.js';
+```
+
+## Step 3: Upgrade Tailwind CSS to v4
+
+Run the automated Tailwind upgrade tool:
+
+```bash
+npx @tailwindcss/upgrade
+```
+
+Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed information about breaking changes in custom configurations.
+
+## Step 4: Update Configuration Files
+
+### Update `config/hyde.php`
+
+#### Replace Features with Enum Values
+
+**Before:**
+```php
+'features' => [
+    Features::htmlPages(),
+    Features::markdownPosts(),
+],
+```
+
+**After:**
+```php
+'features' => [
+    Feature::HtmlPages,
+    Feature::MarkdownPosts,
+],
+```
+
+#### Update Navigation Configuration
+
+**Before:**
+```php
+'navigation' => [
+    'custom_items' => [
+        'Custom Item' => '/custom-page',
+    ],
+],
+```
+
+**After:**
+```php
+'navigation' => [
+    'custom' => [
+        ['label' => 'Custom Item', 'destination' => '/custom-page'],
+    ],
+],
+```
+
+Or use the Navigation facade:
+
+```php
+'navigation' => [
+    'custom' => [
+        Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200),
+    ],
+],
+```
+
+#### Rename Cache Busting Setting
+
+**Before:**
+```php
+'enable_cache_busting' => true,
+```
+
+**After:**
+```php
+'cache_busting' => true,
+```
+
+#### Remove Deprecated HydeFront Settings
+
+Remove these configuration options (they're now handled automatically):
+
+```php
+'hydefront_version' => ...,
+'hydefront_cdn_url' => ...,
+```
+
+#### Update Subdirectory Display Setting
+
+**Before:**
+```php
+'navigation' => [
+    'subdirectories' => 'hidden',
+],
+```
+
+**After:**
+```php
+'navigation' => [
+    'subdirectory_display' => 'hidden',
+],
+```
+
+### Update Author Configuration
+
+If you're using blog post authors, update the configuration format:
+
+**Before:**
+```php
+'authors' => [
+    Author::create('username', 'Display Name', 'https://example.com'),
+],
+```
+
+**After:**
+```php
+'authors' => [
+    'username' => Author::create(
+        name: 'Display Name',
+        website: 'https://example.com',
+        bio: 'Author bio',
+        avatar: 'avatar.png',
+        socials: ['twitter' => '@username']
+    ),
+],
+```
+
+### Update `config/docs.php`
+
+Reorganize the sidebar configuration:
+
+**Before:**
+```php
+'sidebar_order' => [
+    'readme',
+    'installation',
+],
+
+'table_of_contents' => [
+    'enabled' => true,
+],
+
+'sidebar_group_labels' => [
+    // ...
+],
+```
+
+**After:**
+```php
+'sidebar' => [
+    'order' => [
+        'readme',
+        'installation',
+    ],
+    
+    'table_of_contents' => [
+        'enabled' => true,
+    ],
+    
+    'labels' => [
+        // ...
+    ],
+],
+```
+
+## Step 5: Update Code References
+
+### Routes Facade API Changes
+
+**Before:**
+```php
+$route = Routes::get('route-name');        // Returns null if not found
+$route = Routes::getOrFail('route-name');  // Throws exception
+```
+
+**After:**
+```php
+$route = Routes::find('route-name');       // Returns null if not found
+$route = Routes::get('route-name');        // Throws exception
+```
+
+### Asset API Updates
+
+If you're using asset methods in custom code, note that they now return `MediaFile` instances:
+
+```php
+// Methods renamed for clarity
+Hyde::asset('image.png');        // Previously: Hyde::mediaLink()
+Asset::get('image.png');         // Previously: Asset::mediaLink()
+Asset::exists('image.png');      // Previously: Asset::hasMediaFile()
+HydeFront::cdnLink('app.css');   // Previously: Asset::cdnLink()
+```
+
+The `MediaFile` instances are Stringable and will automatically resolve to relative links, so in most cases (especially in Blade templates), no code changes are needed.
+
+### Includes Facade Return Types
+
+Methods now return `HtmlString` objects instead of raw strings:
+
+**Before:**
+```blade
+{!! Includes::html('partial') !!}
+```
+
+**After:**
+```blade
+{{ Includes::html('partial') }}
+```
+
+**Security Note:** Output is no longer escaped by default. If you're including user-generated content, use `{{ e(Includes::html('foo')) }}` for escaping.
+
+### DataCollections Renamed
+
+**Before:**
+```php
+use Hyde\Support\DataCollections;
+```
+
+**After:**
+```php
+use Hyde\Support\DataCollection;
+```
+
+## Step 6: Update Build Commands
+
+Update any CI/CD pipelines or build scripts:
+
+**Before:**
+```bash
+npm run prod
+php hyde build --run-prod
+```
+
+**After:**
+```bash
+npm run build
+php hyde build --vite
+```
+
+The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use `--vite` instead.
+
+## Step 7: Rebuild Your Site
+
+After completing all the configuration updates:
+
+```bash
+# Compile assets
+npm run build
+
+# Build your site
+php hyde build
+
+# Or use the realtime compiler for development
+php hyde serve
+```
+
+## Step 8: Test Your Site
+
+1. Test all navigation menus for correct ordering and appearance
+2. Verify media assets are loading correctly
+3. Check that all pages render properly
+4. Test the search functionality (if using documentation)
+5. Verify author information displays correctly on blog posts
+6. Test dark mode if you're using theme toggle buttons
+
+## Migration Checklist
+
+Use this checklist to track your upgrade progress:
+
+- [ ] Confirmed running HydePHP v1.6+ (preferably v1.8)
+- [ ] Updated `composer.json` dependencies
+- [ ] Ran `composer update`
+- [ ] Updated `package.json` dependencies and scripts
+- [ ] Added `"type": "module"` to `package.json`
+- [ ] Ran `npm install`
+- [ ] Deleted `webpack.mix.js`
+- [ ] Created `vite.config.js`
+- [ ] Updated `resources/assets/app.css` imports
+- [ ] Ran `npx @tailwindcss/upgrade` for Tailwind v4
+- [ ] Updated `config/hyde.php` features to use enum values
+- [ ] Updated navigation configuration to array format
+- [ ] Renamed `enable_cache_busting` to `cache_busting`
+- [ ] Removed deprecated HydeFront settings
+- [ ] Updated author configuration format (if using blog)
+- [ ] Reorganized sidebar configuration in `config/docs.php`
+- [ ] Updated Routes facade method calls (if used in custom code)
+- [ ] Updated Includes facade usage (if used in custom views)
+- [ ] Renamed DataCollections to DataCollection (if used)
+- [ ] Ran `npm run build`
+- [ ] Ran `php hyde build`
+- [ ] Tested site menus for correct ordering and appearance
+- [ ] Verified media assets load correctly
+- [ ] Checked all pages render properly
+- [ ] Tested documentation search (if applicable)
+- [ ] Verified blog author information (if applicable)
+
+## Troubleshooting
+
+### Assets Not Compiling
+
+If you encounter issues with asset compilation:
+
+1. Delete `node_modules` and `package-lock.json`
+2. Run `npm install` again
+3. Clear the `_media` directory
+4. Run `npm run build`
+
+### Missing Routes
+
+If you get `RouteNotFoundException` errors:
+
+- Check that you've updated `Routes::get()` to `Routes::find()` for cases where the route might not exist
+- Verify your page source files are in the correct directories
+
+### Validation Errors
+
+If you get syntax validation errors from DataCollection:
+
+- Ensure all your YAML/JSON data files have valid syntax
+- Empty data files are no longer allowed in v2.0
+
+## Getting Help
+
+If you encounter issues during the upgrade:
+
+- **Documentation**: [https://hydephp.com/docs/2.x](https://hydephp.com/docs/2.x)
+- **GitHub Issues**: [https://github.com/hydephp/hyde/issues](https://github.com/hydephp/hyde/issues)
+- **Community Discord**: [https://discord.hydephp.com](https://discord.hydephp.com)
+
+For the complete changelog with all pull request references, see the [full release notes](https://github.com/hydephp/hyde/releases/tag/v2.0.0).
diff --git a/docs/getting-started/upgrade-guide.md b/docs/getting-started/upgrade-guide.md
new file mode 100644
index 00000000000..d6346bede83
--- /dev/null
+++ b/docs/getting-started/upgrade-guide.md
@@ -0,0 +1,467 @@
+---
+navigation:
+    label: v2 Upgrade Guide
+    priority: 16
+---
+
+# HydePHP v2.0 Upgrade Guide
+
+## Prerequisites
+
+Before upgrading to HydePHP v2.0, ensure your application is running **HydePHP v1.6 or later** (ideally v1.8). These versions include transition helpers that will make the migration process smoother.
+
+## Step 1: Update Dependencies
+
+### Update Composer Dependencies
+
+Open your `composer.json` file and update the following dependencies:
+
+```json
+{
+    "require": {
+        "php": "^8.2",
+        "hyde/framework": "^2.0",
+        "laravel-zero/framework": "^11.0"
+    },
+    "require-dev": {
+        "hyde/realtime-compiler": "^4.0"
+    }
+}
+```
+
+Then run:
+
+```bash
+composer update
+```
+
+### Update Node Dependencies
+
+Open your `package.json` file and replace the entire `devDependencies` section:
+
+**Before (v1.x with Laravel Mix):**
+```json
+{
+    "devDependencies": {
+        "@tailwindcss/typography": "^0.5.2",
+        "autoprefixer": "^10.4.5",
+        "hydefront": "^3.4.1",
+        "laravel-mix": "^6.0.49",
+        "postcss": "^8.4.31",
+        "tailwindcss": "^3.0.24"
+    }
+}
+```
+
+**After (v2.x with Vite):**
+```json
+{
+    "type": "module",
+    "devDependencies": {
+        "@tailwindcss/typography": "^0.5.19",
+        "@tailwindcss/vite": "^4.1.13",
+        "autoprefixer": "^10.4.21",
+        "hyde-vite-plugin": "^1.0.0-RC.5",
+        "hydefront": "^4.0.0-RC.1",
+        "postcss": "^8.5.6",
+        "tailwindcss": "^4.1.13",
+        "vite": "^7.1.7"
+    }
+}
+```
+
+Update the npm scripts in your `package.json`:
+
+```json
+{
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build"
+    }
+}
+```
+
+Then run:
+
+```bash
+npm install
+npm run build
+```
+
+## Step 2: Migrate from Laravel Mix to Vite
+
+### Delete the old Mix configuration
+
+Remove the `webpack.mix.js` file from your project root.
+
+### Create the new Vite configuration
+
+Create a new `vite.config.js` file in your project root:
+
+```javascript
+import { defineConfig } from 'vite';
+import tailwindcss from "@tailwindcss/vite";
+import hyde from 'hyde-vite-plugin';
+
+export default defineConfig({
+    plugins: [
+        hyde({
+            input: ['resources/assets/app.css', 'resources/assets/app.js'],
+            watch: ['_pages', '_posts', '_docs'],
+            refresh: true,
+        }),
+        tailwindcss(),
+    ],
+});
+```
+
+### Update your CSS imports
+
+Update `resources/assets/app.css`:
+
+**Before:**
+```css
+@import '~hydefront/dist/hyde.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+[x-cloak] { display: none !important; }
+```
+
+**After:**
+```css
+@import 'hydefront/components/torchlight.css' layer(base);
+
+@import 'tailwindcss';
+
+@config '../../tailwind.config.js';
+```
+
+## Step 3: Upgrade Tailwind CSS to v4
+
+Run the automated Tailwind upgrade tool:
+
+```bash
+npx @tailwindcss/upgrade
+```
+
+Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed information about breaking changes in custom configurations.
+
+## Step 4: Update Configuration Files
+
+### Update `config/hyde.php`
+
+#### Replace Features with Enum Values
+
+**Before:**
+```php
+'features' => [
+    Features::htmlPages(),
+    Features::markdownPosts(),
+],
+```
+
+**After:**
+```php
+'features' => [
+    Feature::HtmlPages,
+    Feature::MarkdownPosts,
+],
+```
+
+#### Update Navigation Configuration
+
+**Before:**
+```php
+'navigation' => [
+    'custom_items' => [
+        'Custom Item' => '/custom-page',
+    ],
+],
+```
+
+**After:**
+```php
+'navigation' => [
+    'custom' => [
+        ['label' => 'Custom Item', 'destination' => '/custom-page'],
+    ],
+],
+```
+
+Or use the Navigation facade:
+
+```php
+'navigation' => [
+    'custom' => [
+        Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200),
+    ],
+],
+```
+
+#### Rename Cache Busting Setting
+
+**Before:**
+```php
+'enable_cache_busting' => true,
+```
+
+**After:**
+```php
+'cache_busting' => true,
+```
+
+#### Remove Deprecated HydeFront Settings
+
+Remove these configuration options (they're now handled automatically):
+
+```php
+'hydefront_version' => ...,
+'hydefront_cdn_url' => ...,
+```
+
+#### Update Subdirectory Display Setting
+
+**Before:**
+```php
+'navigation' => [
+    'subdirectories' => 'hidden',
+],
+```
+
+**After:**
+```php
+'navigation' => [
+    'subdirectory_display' => 'hidden',
+],
+```
+
+### Update Author Configuration
+
+If you're using blog post authors, update the configuration format:
+
+**Before:**
+```php
+'authors' => [
+    Author::create('username', 'Display Name', 'https://example.com'),
+],
+```
+
+**After:**
+```php
+'authors' => [
+    'username' => Author::create(
+        name: 'Display Name',
+        website: 'https://example.com',
+        bio: 'Author bio',
+        avatar: 'avatar.png',
+        socials: ['twitter' => '@username']
+    ),
+],
+```
+
+### Update `config/docs.php`
+
+Reorganize the sidebar configuration:
+
+**Before:**
+```php
+'sidebar_order' => [
+    'readme',
+    'installation',
+],
+
+'table_of_contents' => [
+    'enabled' => true,
+],
+
+'sidebar_group_labels' => [
+    // ...
+],
+```
+
+**After:**
+```php
+'sidebar' => [
+    'order' => [
+        'readme',
+        'installation',
+    ],
+    
+    'table_of_contents' => [
+        'enabled' => true,
+    ],
+    
+    'labels' => [
+        // ...
+    ],
+],
+```
+
+## Step 5: Update Code References
+
+### Routes Facade API Changes
+
+**Before:**
+```php
+$route = Routes::get('route-name');        // Returns null if not found
+$route = Routes::getOrFail('route-name');  // Throws exception
+```
+
+**After:**
+```php
+$route = Routes::find('route-name');       // Returns null if not found
+$route = Routes::get('route-name');        // Throws exception
+```
+
+### Asset API Updates
+
+If you're using asset methods in custom code, note that they now return `MediaFile` instances:
+
+```php
+// Methods renamed for clarity
+Hyde::asset('image.png');        // Previously: Hyde::mediaLink()
+Asset::get('image.png');         // Previously: Asset::mediaLink()
+Asset::exists('image.png');      // Previously: Asset::hasMediaFile()
+HydeFront::cdnLink('app.css');   // Previously: Asset::cdnLink()
+```
+
+The `MediaFile` instances are Stringable and will automatically resolve to relative links, so in most cases (especially in Blade templates), no code changes are needed.
+
+### Includes Facade Return Types
+
+Methods now return `HtmlString` objects instead of raw strings:
+
+**Before:**
+```blade
+{!! Includes::html('partial') !!}
+```
+
+**After:**
+```blade
+{{ Includes::html('partial') }}
+```
+
+**Security Note:** Output is no longer escaped by default. If you're including user-generated content, use `{{ e(Includes::html('foo')) }}` for escaping.
+
+### DataCollections Renamed
+
+**Before:**
+```php
+use Hyde\Support\DataCollections;
+```
+
+**After:**
+```php
+use Hyde\Support\DataCollection;
+```
+
+## Step 6: Update Build Commands
+
+Update any CI/CD pipelines or build scripts:
+
+**Before:**
+```bash
+npm run prod
+php hyde build --run-prod
+```
+
+**After:**
+```bash
+npm run build
+php hyde build --vite
+```
+
+The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use `--vite` instead.
+
+## Step 7: Rebuild Your Site
+
+After completing all the configuration updates:
+
+```bash
+# Compile assets
+npm run build
+
+# Build your site
+php hyde build
+
+# Or use the realtime compiler for development
+php hyde serve
+```
+
+## Step 8: Test Your Site
+
+1. Test all navigation menus for correct ordering and appearance
+2. Verify media assets are loading correctly
+3. Check that all pages render properly
+4. Test the search functionality (if using documentation)
+5. Verify author information displays correctly on blog posts
+6. Test dark mode if you're using theme toggle buttons
+
+## Migration Checklist
+
+Use this checklist to track your upgrade progress:
+
+- [ ] Confirmed running HydePHP v1.6+ (preferably v1.8)
+- [ ] Updated `composer.json` dependencies
+- [ ] Ran `composer update`
+- [ ] Updated `package.json` dependencies and scripts
+- [ ] Added `"type": "module"` to `package.json`
+- [ ] Ran `npm install`
+- [ ] Deleted `webpack.mix.js`
+- [ ] Created `vite.config.js`
+- [ ] Updated `resources/assets/app.css` imports
+- [ ] Ran `npx @tailwindcss/upgrade` for Tailwind v4
+- [ ] Updated `config/hyde.php` features to use enum values
+- [ ] Updated navigation configuration to array format
+- [ ] Renamed `enable_cache_busting` to `cache_busting`
+- [ ] Removed deprecated HydeFront settings
+- [ ] Updated author configuration format (if using blog)
+- [ ] Reorganized sidebar configuration in `config/docs.php`
+- [ ] Updated Routes facade method calls (if used in custom code)
+- [ ] Updated Includes facade usage (if used in custom views)
+- [ ] Renamed DataCollections to DataCollection (if used)
+- [ ] Ran `npm run build`
+- [ ] Ran `php hyde build`
+- [ ] Tested site menus for correct ordering and appearance
+- [ ] Verified media assets load correctly
+- [ ] Checked all pages render properly
+- [ ] Tested documentation search (if applicable)
+- [ ] Verified blog author information (if applicable)
+
+## Troubleshooting
+
+### Assets Not Compiling
+
+If you encounter issues with asset compilation:
+
+1. Delete `node_modules` and `package-lock.json`
+2. Run `npm install` again
+3. Clear the `_media` directory
+4. Run `npm run build`
+
+### Missing Routes
+
+If you get `RouteNotFoundException` errors:
+
+- Check that you've updated `Routes::get()` to `Routes::find()` for cases where the route might not exist
+- Verify your page source files are in the correct directories
+
+### Validation Errors
+
+If you get syntax validation errors from DataCollection:
+
+- Ensure all your YAML/JSON data files have valid syntax
+- Empty data files are no longer allowed in v2.0
+
+## Getting Help
+
+If you encounter issues during the upgrade:
+
+- **Documentation**: [https://hydephp.com/docs/2.x](https://hydephp.com/docs/2.x)
+- **GitHub Issues**: [https://github.com/hydephp/hyde/issues](https://github.com/hydephp/hyde/issues)
+- **Community Discord**: [https://discord.hydephp.com](https://discord.hydephp.com)
+
+For the complete changelog with all pull request references, see the [full release notes](https://github.com/hydephp/hyde/releases/tag/v2.0.0).

From 52685490587c79bf6a58a6f837d15ac8e07437f0 Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 11:54:35 +0200
Subject: [PATCH 02/11] Document moved config key

---
 config/docs.php                    | 14 ++++++++++++++
 packages/framework/config/docs.php | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/config/docs.php b/config/docs.php
index 9650b1f057c..24eb146f088 100644
--- a/config/docs.php
+++ b/config/docs.php
@@ -56,6 +56,20 @@
             'getting-started',
         ],
 
+        /*
+        |--------------------------------------------------------------------------
+        | Sidebar Labels
+        |--------------------------------------------------------------------------
+        |
+        | Define custom labels for sidebar items. The array key should be the
+        | page identifier, and the value should be the display label.
+        |
+        */
+
+        'labels' => [
+            // 'page-identifier' => 'Display Label',
+        ],
+
         /*
         |--------------------------------------------------------------------------
         | Table of Contents Settings
diff --git a/packages/framework/config/docs.php b/packages/framework/config/docs.php
index 9650b1f057c..24eb146f088 100644
--- a/packages/framework/config/docs.php
+++ b/packages/framework/config/docs.php
@@ -56,6 +56,20 @@
             'getting-started',
         ],
 
+        /*
+        |--------------------------------------------------------------------------
+        | Sidebar Labels
+        |--------------------------------------------------------------------------
+        |
+        | Define custom labels for sidebar items. The array key should be the
+        | page identifier, and the value should be the display label.
+        |
+        */
+
+        'labels' => [
+            // 'page-identifier' => 'Display Label',
+        ],
+
         /*
         |--------------------------------------------------------------------------
         | Table of Contents Settings

From 0b72aae2017f69e8a94f39878dc6420d39658dd0 Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 11:54:47 +0200
Subject: [PATCH 03/11] Go through upgrade guide one more time

---
 UPGRADE.md                            | 159 +++++++++++++++++++-------
 docs/getting-started/upgrade-guide.md | 159 +++++++++++++++++++-------
 2 files changed, 230 insertions(+), 88 deletions(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index 4f39938c6d8..6497ca24547 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -29,6 +29,8 @@ Then run:
 composer update
 ```
 
+The dump-autoload script will likely fail, but that is okay for now as we will fix it shortly.
+
 ### Update Node Dependencies
 
 Open your `package.json` file and replace the entire `devDependencies` section:
@@ -52,19 +54,19 @@ Open your `package.json` file and replace the entire `devDependencies` section:
 {
     "type": "module",
     "devDependencies": {
-        "@tailwindcss/typography": "^0.5.19",
-        "@tailwindcss/vite": "^4.1.13",
-        "autoprefixer": "^10.4.21",
-        "hyde-vite-plugin": "^1.0.0-RC.5",
-        "hydefront": "^4.0.0-RC.1",
-        "postcss": "^8.5.6",
-        "tailwindcss": "^4.1.13",
-        "vite": "^7.1.7"
+        "@tailwindcss/typography": "^0.5.0",
+        "@tailwindcss/vite": "^4.1.0",
+        "autoprefixer": "^10.4.0",
+        "hyde-vite-plugin": "^1.1.0",
+        "hydefront": "^4.0.0",
+        "postcss": "^8.5.0",
+        "tailwindcss": "^4.1.0",
+        "vite": "^7.1.0"
     }
 }
 ```
 
-Update the npm scripts in your `package.json`:
+Update the NPM scripts in your `package.json`:
 
 ```json
 {
@@ -79,7 +81,6 @@ Then run:
 
 ```bash
 npm install
-npm run build
 ```
 
 ## Step 2: Migrate from Laravel Mix to Vite
@@ -143,6 +144,14 @@ npx @tailwindcss/upgrade
 
 Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed information about breaking changes in custom configurations.
 
+## Step 5: Veriy Vite Works
+
+Now you can run Vite build:
+
+```bash
+npm run build
+```
+
 ## Step 4: Update Configuration Files
 
 ### Update `config/hyde.php`
@@ -188,6 +197,8 @@ Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guid
 Or use the Navigation facade:
 
 ```php
+use Hyde\Facades\Navigation;
+
 'navigation' => [
     'custom' => [
         Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200),
@@ -195,27 +206,6 @@ Or use the Navigation facade:
 ],
 ```
 
-#### Rename Cache Busting Setting
-
-**Before:**
-```php
-'enable_cache_busting' => true,
-```
-
-**After:**
-```php
-'cache_busting' => true,
-```
-
-#### Remove Deprecated HydeFront Settings
-
-Remove these configuration options (they're now handled automatically):
-
-```php
-'hydefront_version' => ...,
-'hydefront_cdn_url' => ...,
-```
-
 #### Update Subdirectory Display Setting
 
 **Before:**
@@ -232,6 +222,7 @@ Remove these configuration options (they're now handled automatically):
 ],
 ```
 
+
 ### Update Author Configuration
 
 If you're using blog post authors, update the configuration format:
@@ -256,6 +247,27 @@ If you're using blog post authors, update the configuration format:
 ],
 ```
 
+#### Rename Cache Busting Setting
+
+**Before:**
+```php
+'enable_cache_busting' => true,
+```
+
+**After:**
+```php
+'cache_busting' => true,
+```
+
+#### Remove Deprecated HydeFront Settings
+
+Remove these configuration options (they're now handled automatically):
+
+```php
+'hydefront_version' => ...,
+'hydefront_cdn_url' => ...,
+```
+
 ### Update `config/docs.php`
 
 Reorganize the sidebar configuration:
@@ -284,17 +296,34 @@ Reorganize the sidebar configuration:
         'installation',
     ],
     
-    'table_of_contents' => [
-        'enabled' => true,
-    ],
-    
     'labels' => [
         // ...
     ],
+
+    'table_of_contents' => [
+        'enabled' => true,
+        'min_heading_level' => 2,
+        'max_heading_level' => 4,
+    ],
 ],
 ```
 
-## Step 5: Update Code References
+### Update `app/config.php`
+
+Add the new navigation service provider under the `'providers'` array:
+
+```php
+Hyde\Foundation\Providers\NavigationServiceProvider::class,
+```
+
+And add the following classes to the `'aliases'` array:
+
+```php
+'Vite' => \Hyde\Facades\Vite::class,
+'MediaFile' => \Hyde\Support\Filesystem\MediaFile::class,
+```
+
+## Step 6: Update Code References
 
 ### Routes Facade API Changes
 
@@ -316,10 +345,11 @@ If you're using asset methods in custom code, note that they now return `MediaFi
 
 ```php
 // Methods renamed for clarity
-Hyde::asset('image.png');        // Previously: Hyde::mediaLink()
-Asset::get('image.png');         // Previously: Asset::mediaLink()
-Asset::exists('image.png');      // Previously: Asset::hasMediaFile()
-HydeFront::cdnLink('app.css');   // Previously: Asset::cdnLink()
+Hyde::asset('image.png');          // Previously: Hyde::mediaLink()
+Asset::get('image.png');           // Previously: Asset::mediaLink()
+Asset::exists('image.png');        // Previously: Asset::hasMediaFile()
+HydeFront::cdnLink('app.css');     // Previously: Asset::cdnLink()
+MediaFile::sourcePath('image.png') // Previously: Hyde::mediaPath()
 ```
 
 The `MediaFile` instances are Stringable and will automatically resolve to relative links, so in most cases (especially in Blade templates), no code changes are needed.
@@ -352,7 +382,37 @@ use Hyde\Support\DataCollections;
 use Hyde\Support\DataCollection;
 ```
 
-## Step 6: Update Build Commands
+### Features now use enums
+
+If you in custom code call `hasFeature` with a string, that must now be changed to an enum:
+
+**Before:**
+```php
+Hyde::hasFeature('darkmode)
+```
+
+**After:**
+```php
+Hyde::hasFeature(Feature::Darkmode)
+```
+
+### Update navigation menu creation
+
+If you in custom code call `NavigationMenu` code, do the following replacements:
+
+**before:**
+```php
+$navigation = NavigationMenu::create();
+$navigation->items`
+```
+
+**After:**
+```php
+$navigation = app('navigation.main');
+$navigation->getItems()
+```
+
+## Step 7: Update Build Commands
 
 Update any CI/CD pipelines or build scripts:
 
@@ -370,12 +430,23 @@ php hyde build --vite
 
 The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use `--vite` instead.
 
-## Step 7: Rebuild Your Site
+## Step 8: Clear caches
+
+Next to ensure we have a clean slate, run the following commands:
+
+```bash
+composer dump-autoload
+php hyde cache:clear
+rm app/storage/framework/views/*.php
+```
+
+You may also want to republish any views you have published.
+
+## Step 9: Rebuild Your Site
 
 After completing all the configuration updates:
 
 ```bash
-# Compile assets
 npm run build
 
 # Build your site
@@ -385,7 +456,7 @@ php hyde build
 php hyde serve
 ```
 
-## Step 8: Test Your Site
+## Step 10: Test Your Site
 
 1. Test all navigation menus for correct ordering and appearance
 2. Verify media assets are loading correctly
diff --git a/docs/getting-started/upgrade-guide.md b/docs/getting-started/upgrade-guide.md
index d6346bede83..e2c1e057073 100644
--- a/docs/getting-started/upgrade-guide.md
+++ b/docs/getting-started/upgrade-guide.md
@@ -35,6 +35,8 @@ Then run:
 composer update
 ```
 
+The dump-autoload script will likely fail, but that is okay for now as we will fix it shortly.
+
 ### Update Node Dependencies
 
 Open your `package.json` file and replace the entire `devDependencies` section:
@@ -58,19 +60,19 @@ Open your `package.json` file and replace the entire `devDependencies` section:
 {
     "type": "module",
     "devDependencies": {
-        "@tailwindcss/typography": "^0.5.19",
-        "@tailwindcss/vite": "^4.1.13",
-        "autoprefixer": "^10.4.21",
-        "hyde-vite-plugin": "^1.0.0-RC.5",
-        "hydefront": "^4.0.0-RC.1",
-        "postcss": "^8.5.6",
-        "tailwindcss": "^4.1.13",
-        "vite": "^7.1.7"
+        "@tailwindcss/typography": "^0.5.0",
+        "@tailwindcss/vite": "^4.1.0",
+        "autoprefixer": "^10.4.0",
+        "hyde-vite-plugin": "^1.1.0",
+        "hydefront": "^4.0.0",
+        "postcss": "^8.5.0",
+        "tailwindcss": "^4.1.0",
+        "vite": "^7.1.0"
     }
 }
 ```
 
-Update the npm scripts in your `package.json`:
+Update the NPM scripts in your `package.json`:
 
 ```json
 {
@@ -85,7 +87,6 @@ Then run:
 
 ```bash
 npm install
-npm run build
 ```
 
 ## Step 2: Migrate from Laravel Mix to Vite
@@ -149,6 +150,14 @@ npx @tailwindcss/upgrade
 
 Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed information about breaking changes in custom configurations.
 
+## Step 5: Veriy Vite Works
+
+Now you can run Vite build:
+
+```bash
+npm run build
+```
+
 ## Step 4: Update Configuration Files
 
 ### Update `config/hyde.php`
@@ -194,6 +203,8 @@ Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guid
 Or use the Navigation facade:
 
 ```php
+use Hyde\Facades\Navigation;
+
 'navigation' => [
     'custom' => [
         Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200),
@@ -201,27 +212,6 @@ Or use the Navigation facade:
 ],
 ```
 
-#### Rename Cache Busting Setting
-
-**Before:**
-```php
-'enable_cache_busting' => true,
-```
-
-**After:**
-```php
-'cache_busting' => true,
-```
-
-#### Remove Deprecated HydeFront Settings
-
-Remove these configuration options (they're now handled automatically):
-
-```php
-'hydefront_version' => ...,
-'hydefront_cdn_url' => ...,
-```
-
 #### Update Subdirectory Display Setting
 
 **Before:**
@@ -238,6 +228,7 @@ Remove these configuration options (they're now handled automatically):
 ],
 ```
 
+
 ### Update Author Configuration
 
 If you're using blog post authors, update the configuration format:
@@ -262,6 +253,27 @@ If you're using blog post authors, update the configuration format:
 ],
 ```
 
+#### Rename Cache Busting Setting
+
+**Before:**
+```php
+'enable_cache_busting' => true,
+```
+
+**After:**
+```php
+'cache_busting' => true,
+```
+
+#### Remove Deprecated HydeFront Settings
+
+Remove these configuration options (they're now handled automatically):
+
+```php
+'hydefront_version' => ...,
+'hydefront_cdn_url' => ...,
+```
+
 ### Update `config/docs.php`
 
 Reorganize the sidebar configuration:
@@ -290,17 +302,34 @@ Reorganize the sidebar configuration:
         'installation',
     ],
     
-    'table_of_contents' => [
-        'enabled' => true,
-    ],
-    
     'labels' => [
         // ...
     ],
+
+    'table_of_contents' => [
+        'enabled' => true,
+        'min_heading_level' => 2,
+        'max_heading_level' => 4,
+    ],
 ],
 ```
 
-## Step 5: Update Code References
+### Update `app/config.php`
+
+Add the new navigation service provider under the `'providers'` array:
+
+```php
+Hyde\Foundation\Providers\NavigationServiceProvider::class,
+```
+
+And add the following classes to the `'aliases'` array:
+
+```php
+'Vite' => \Hyde\Facades\Vite::class,
+'MediaFile' => \Hyde\Support\Filesystem\MediaFile::class,
+```
+
+## Step 6: Update Code References
 
 ### Routes Facade API Changes
 
@@ -322,10 +351,11 @@ If you're using asset methods in custom code, note that they now return `MediaFi
 
 ```php
 // Methods renamed for clarity
-Hyde::asset('image.png');        // Previously: Hyde::mediaLink()
-Asset::get('image.png');         // Previously: Asset::mediaLink()
-Asset::exists('image.png');      // Previously: Asset::hasMediaFile()
-HydeFront::cdnLink('app.css');   // Previously: Asset::cdnLink()
+Hyde::asset('image.png');          // Previously: Hyde::mediaLink()
+Asset::get('image.png');           // Previously: Asset::mediaLink()
+Asset::exists('image.png');        // Previously: Asset::hasMediaFile()
+HydeFront::cdnLink('app.css');     // Previously: Asset::cdnLink()
+MediaFile::sourcePath('image.png') // Previously: Hyde::mediaPath()
 ```
 
 The `MediaFile` instances are Stringable and will automatically resolve to relative links, so in most cases (especially in Blade templates), no code changes are needed.
@@ -358,7 +388,37 @@ use Hyde\Support\DataCollections;
 use Hyde\Support\DataCollection;
 ```
 
-## Step 6: Update Build Commands
+### Features now use enums
+
+If you in custom code call `hasFeature` with a string, that must now be changed to an enum:
+
+**Before:**
+```php
+Hyde::hasFeature('darkmode)
+```
+
+**After:**
+```php
+Hyde::hasFeature(Feature::Darkmode)
+```
+
+### Update navigation menu creation
+
+If you in custom code call `NavigationMenu` code, do the following replacements:
+
+**before:**
+```php
+$navigation = NavigationMenu::create();
+$navigation->items`
+```
+
+**After:**
+```php
+$navigation = app('navigation.main');
+$navigation->getItems()
+```
+
+## Step 7: Update Build Commands
 
 Update any CI/CD pipelines or build scripts:
 
@@ -376,12 +436,23 @@ php hyde build --vite
 
 The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use `--vite` instead.
 
-## Step 7: Rebuild Your Site
+## Step 8: Clear caches
+
+Next to ensure we have a clean slate, run the following commands:
+
+```bash
+composer dump-autoload
+php hyde cache:clear
+rm app/storage/framework/views/*.php
+```
+
+You may also want to republish any views you have published.
+
+## Step 9: Rebuild Your Site
 
 After completing all the configuration updates:
 
 ```bash
-# Compile assets
 npm run build
 
 # Build your site
@@ -391,7 +462,7 @@ php hyde build
 php hyde serve
 ```
 
-## Step 8: Test Your Site
+## Step 10: Test Your Site
 
 1. Test all navigation menus for correct ordering and appearance
 2. Verify media assets are loading correctly

From 4c835099bbe1cf72ed0d98736246b9eaa7abdf7e Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 12:08:27 +0200
Subject: [PATCH 04/11] Proofreading

---
 docs/getting-started/upgrade-guide.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/getting-started/upgrade-guide.md b/docs/getting-started/upgrade-guide.md
index e2c1e057073..47b9809596c 100644
--- a/docs/getting-started/upgrade-guide.md
+++ b/docs/getting-started/upgrade-guide.md
@@ -150,7 +150,7 @@ npx @tailwindcss/upgrade
 
 Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed information about breaking changes in custom configurations.
 
-## Step 5: Veriy Vite Works
+## Step 4: Verify Vite Works
 
 Now you can run Vite build:
 
@@ -158,7 +158,7 @@ Now you can run Vite build:
 npm run build
 ```
 
-## Step 4: Update Configuration Files
+## Step 5: Update Configuration Files
 
 ### Update `config/hyde.php`
 

From d078a35e7cd8452a933c467e773438b24e0dc83a Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 12:08:33 +0200
Subject: [PATCH 05/11] Remove overkill information

---
 docs/getting-started/upgrade-guide.md | 30 ---------------------------
 1 file changed, 30 deletions(-)

diff --git a/docs/getting-started/upgrade-guide.md b/docs/getting-started/upgrade-guide.md
index 47b9809596c..4af3d5f770d 100644
--- a/docs/getting-started/upgrade-guide.md
+++ b/docs/getting-started/upgrade-guide.md
@@ -388,36 +388,6 @@ use Hyde\Support\DataCollections;
 use Hyde\Support\DataCollection;
 ```
 
-### Features now use enums
-
-If you in custom code call `hasFeature` with a string, that must now be changed to an enum:
-
-**Before:**
-```php
-Hyde::hasFeature('darkmode)
-```
-
-**After:**
-```php
-Hyde::hasFeature(Feature::Darkmode)
-```
-
-### Update navigation menu creation
-
-If you in custom code call `NavigationMenu` code, do the following replacements:
-
-**before:**
-```php
-$navigation = NavigationMenu::create();
-$navigation->items`
-```
-
-**After:**
-```php
-$navigation = app('navigation.main');
-$navigation->getItems()
-```
-
 ## Step 7: Update Build Commands
 
 Update any CI/CD pipelines or build scripts:

From 8f6efa7c934d00b4b9ebcfc8490e0abbe94f6abf Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 12:09:13 +0200
Subject: [PATCH 06/11] Final proofreading

---
 docs/getting-started/upgrade-guide.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/getting-started/upgrade-guide.md b/docs/getting-started/upgrade-guide.md
index 4af3d5f770d..68298003e0c 100644
--- a/docs/getting-started/upgrade-guide.md
+++ b/docs/getting-started/upgrade-guide.md
@@ -162,7 +162,7 @@ npm run build
 
 ### Update `config/hyde.php`
 
-#### Replace Features with Enum Values
+#### Replace Features With Enum Values
 
 **Before:**
 ```php
@@ -408,7 +408,7 @@ The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use
 
 ## Step 8: Clear caches
 
-Next to ensure we have a clean slate, run the following commands:
+Next, to ensure we have a clean slate, run the following commands:
 
 ```bash
 composer dump-autoload

From ad99b002113dc3cd26f159316944829e9e0ce491 Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 12:09:32 +0200
Subject: [PATCH 07/11] Sync upgrade guide

---
 UPGRADE.md | 38 ++++----------------------------------
 1 file changed, 4 insertions(+), 34 deletions(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index 6497ca24547..8becb802ba0 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -144,7 +144,7 @@ npx @tailwindcss/upgrade
 
 Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed information about breaking changes in custom configurations.
 
-## Step 5: Veriy Vite Works
+## Step 4: Verify Vite Works
 
 Now you can run Vite build:
 
@@ -152,11 +152,11 @@ Now you can run Vite build:
 npm run build
 ```
 
-## Step 4: Update Configuration Files
+## Step 5: Update Configuration Files
 
 ### Update `config/hyde.php`
 
-#### Replace Features with Enum Values
+#### Replace Features With Enum Values
 
 **Before:**
 ```php
@@ -382,36 +382,6 @@ use Hyde\Support\DataCollections;
 use Hyde\Support\DataCollection;
 ```
 
-### Features now use enums
-
-If you in custom code call `hasFeature` with a string, that must now be changed to an enum:
-
-**Before:**
-```php
-Hyde::hasFeature('darkmode)
-```
-
-**After:**
-```php
-Hyde::hasFeature(Feature::Darkmode)
-```
-
-### Update navigation menu creation
-
-If you in custom code call `NavigationMenu` code, do the following replacements:
-
-**before:**
-```php
-$navigation = NavigationMenu::create();
-$navigation->items`
-```
-
-**After:**
-```php
-$navigation = app('navigation.main');
-$navigation->getItems()
-```
-
 ## Step 7: Update Build Commands
 
 Update any CI/CD pipelines or build scripts:
@@ -432,7 +402,7 @@ The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use
 
 ## Step 8: Clear caches
 
-Next to ensure we have a clean slate, run the following commands:
+Next, to ensure we have a clean slate, run the following commands:
 
 ```bash
 composer dump-autoload

From 6cf6240699bf1e28b7fa4b036ae7a0219db342d5 Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 12:11:47 +0200
Subject: [PATCH 08/11] Clarify section

---
 RELEASE_NOTES.md                      | 2 +-
 docs/getting-started/release-notes.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 7a0a0f2cc2a..927eabd2ea5 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -294,7 +294,7 @@ Documentation sidebar configuration has been reorganized:
 
 ## Removed Features
 
-### Deprecated Methods
+### Deprecated Method Removals
 - `PostAuthor::getName()` - use `$author->name` property
 - `FeaturedImage::isRemote()` - use `Hyperlinks::isRemote()`
 - `DocumentationPage::getTableOfContents()` - use Blade component
diff --git a/docs/getting-started/release-notes.md b/docs/getting-started/release-notes.md
index e72ac4632de..96a19eeb573 100644
--- a/docs/getting-started/release-notes.md
+++ b/docs/getting-started/release-notes.md
@@ -300,7 +300,7 @@ Documentation sidebar configuration has been reorganized:
 
 ## Removed Features
 
-### Deprecated Methods
+### Deprecated Method Removals
 - `PostAuthor::getName()` - use `$author->name` property
 - `FeaturedImage::isRemote()` - use `Hyperlinks::isRemote()`
 - `DocumentationPage::getTableOfContents()` - use Blade component

From 9c9a468c92a0d73303f701da313482552b79683c Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 14:07:54 +0200
Subject: [PATCH 09/11] Update to document default value

---
 config/docs.php                    | 2 +-
 packages/framework/config/docs.php | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/config/docs.php b/config/docs.php
index 24eb146f088..eedd77e8d1c 100644
--- a/config/docs.php
+++ b/config/docs.php
@@ -67,7 +67,7 @@
         */
 
         'labels' => [
-            // 'page-identifier' => 'Display Label',
+            \Hyde\Pages\DocumentationPage::homeRouteName() => 'Docs',
         ],
 
         /*
diff --git a/packages/framework/config/docs.php b/packages/framework/config/docs.php
index 24eb146f088..eedd77e8d1c 100644
--- a/packages/framework/config/docs.php
+++ b/packages/framework/config/docs.php
@@ -67,7 +67,7 @@
         */
 
         'labels' => [
-            // 'page-identifier' => 'Display Label',
+            \Hyde\Pages\DocumentationPage::homeRouteName() => 'Docs',
         ],
 
         /*

From 7b5faacb7b11ac8958484936ccc7c41bfe5412ce Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 14:26:56 +0200
Subject: [PATCH 10/11] Final upgrade guide proofreading

---
 UPGRADE.md                            | 48 +++++++++++++++++++++++----
 docs/getting-started/upgrade-guide.md | 48 +++++++++++++++++++++++----
 2 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index 8becb802ba0..05d6332ea52 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -1,9 +1,41 @@
 # HydePHP v2.0 Upgrade Guide
 
-## Prerequisites
+## Overview
+
+HydePHP v2.0 represents a major evolution of the framework, introducing significant improvements to the asset system, navigation API, and overall developer experience. This release modernizes the frontend tooling by replacing Laravel Mix with Vite, completely rewrites the navigation system for better flexibility, and introduces numerous performance optimizations throughout the framework.
+
+This document will guide you through the upgrade process. If you want to learn more about the new features, take a look at the [Release Notes](https://hydephp.com/docs/2.x/release-notes).
+
+## Before You Begin
+
+### Prerequisites
 
 Before upgrading to HydePHP v2.0, ensure your application is running **HydePHP v1.6 or later** (ideally v1.8). These versions include transition helpers that will make the migration process smoother.
 
+### Backup Your Project
+
+Before starting the upgrade process, it's **strongly recommended** to:
+
+- **Commit all changes to Git** - This allows you to easily revert if needed
+- **Create a backup** of your entire project directory
+- **Have a previous site build** so you can compare output
+
+If you're not already using Git for version control, now is an excellent time to initialize a repository:
+
+```bash
+git init
+git add .
+git commit -m "Pre-upgrade backup before HydePHP v2.0"
+```
+
+### Estimated Time
+
+The upgrade process typically takes **30-60 minutes** for most projects. Complex sites with extensive customizations may take up to 90 minutes. The majority of this time involves:
+
+- Updating and installing dependencies (~15 minutes)
+- Migrating configuration files (~20 minutes)
+- Testing and verifying the site (~15-30 minutes)
+
 ## Step 1: Update Dependencies
 
 ### Update Composer Dependencies
@@ -29,7 +61,7 @@ Then run:
 composer update
 ```
 
-The dump-autoload script will likely fail, but that is okay for now as we will fix it shortly.
+The dump-autoload script will likely fail, but this is expected and will be resolved in subsequent steps.
 
 ### Update Node Dependencies
 
@@ -85,11 +117,11 @@ npm install
 
 ## Step 2: Migrate from Laravel Mix to Vite
 
-### Delete the old Mix configuration
+### Delete the Old Mix Configuration
 
 Remove the `webpack.mix.js` file from your project root.
 
-### Create the new Vite configuration
+### Create the New Vite Configuration
 
 Create a new `vite.config.js` file in your project root:
 
@@ -110,7 +142,7 @@ export default defineConfig({
 });
 ```
 
-### Update your CSS imports
+### Update Your CSS imports
 
 Update `resources/assets/app.css`:
 
@@ -400,7 +432,7 @@ php hyde build --vite
 
 The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use `--vite` instead.
 
-## Step 8: Clear caches
+## Step 8: Clear Caches
 
 Next, to ensure we have a clean slate, run the following commands:
 
@@ -491,6 +523,10 @@ If you get syntax validation errors from DataCollection:
 - Ensure all your YAML/JSON data files have valid syntax
 - Empty data files are no longer allowed in v2.0
 
+### Errors During build
+
+If you have published Blade views, those may need to be republished if they use old syntax. If you use custom code you may need to look closer at the full release diff.
+
 ## Getting Help
 
 If you encounter issues during the upgrade:
diff --git a/docs/getting-started/upgrade-guide.md b/docs/getting-started/upgrade-guide.md
index 68298003e0c..70896bc5978 100644
--- a/docs/getting-started/upgrade-guide.md
+++ b/docs/getting-started/upgrade-guide.md
@@ -6,10 +6,42 @@ navigation:
 
 # HydePHP v2.0 Upgrade Guide
 
-## Prerequisites
+## Overview
+
+HydePHP v2.0 represents a major evolution of the framework, introducing significant improvements to the asset system, navigation API, and overall developer experience. This release modernizes the frontend tooling by replacing Laravel Mix with Vite, completely rewrites the navigation system for better flexibility, and introduces numerous performance optimizations throughout the framework.
+
+This document will guide you through the upgrade process. If you want to learn more about the new features, take a look at the [Release Notes](https://hydephp.com/docs/2.x/release-notes).
+
+## Before You Begin
+
+### Prerequisites
 
 Before upgrading to HydePHP v2.0, ensure your application is running **HydePHP v1.6 or later** (ideally v1.8). These versions include transition helpers that will make the migration process smoother.
 
+### Backup Your Project
+
+Before starting the upgrade process, it's **strongly recommended** to:
+
+- **Commit all changes to Git** - This allows you to easily revert if needed
+- **Create a backup** of your entire project directory
+- **Have a previous site build** so you can compare output
+
+If you're not already using Git for version control, now is an excellent time to initialize a repository:
+
+```bash
+git init
+git add .
+git commit -m "Pre-upgrade backup before HydePHP v2.0"
+```
+
+### Estimated Time
+
+The upgrade process typically takes **30-60 minutes** for most projects. Complex sites with extensive customizations may take up to 90 minutes. The majority of this time involves:
+
+- Updating and installing dependencies (~15 minutes)
+- Migrating configuration files (~20 minutes)
+- Testing and verifying the site (~15-30 minutes)
+
 ## Step 1: Update Dependencies
 
 ### Update Composer Dependencies
@@ -35,7 +67,7 @@ Then run:
 composer update
 ```
 
-The dump-autoload script will likely fail, but that is okay for now as we will fix it shortly.
+The dump-autoload script will likely fail, but this is expected and will be resolved in subsequent steps.
 
 ### Update Node Dependencies
 
@@ -91,11 +123,11 @@ npm install
 
 ## Step 2: Migrate from Laravel Mix to Vite
 
-### Delete the old Mix configuration
+### Delete the Old Mix Configuration
 
 Remove the `webpack.mix.js` file from your project root.
 
-### Create the new Vite configuration
+### Create the New Vite Configuration
 
 Create a new `vite.config.js` file in your project root:
 
@@ -116,7 +148,7 @@ export default defineConfig({
 });
 ```
 
-### Update your CSS imports
+### Update Your CSS imports
 
 Update `resources/assets/app.css`:
 
@@ -406,7 +438,7 @@ php hyde build --vite
 
 The `--run-dev`, `--run-prod`, and `--run-prettier` flags have been removed. Use `--vite` instead.
 
-## Step 8: Clear caches
+## Step 8: Clear Caches
 
 Next, to ensure we have a clean slate, run the following commands:
 
@@ -497,6 +529,10 @@ If you get syntax validation errors from DataCollection:
 - Ensure all your YAML/JSON data files have valid syntax
 - Empty data files are no longer allowed in v2.0
 
+### Errors During build
+
+If you have published Blade views, those may need to be republished if they use old syntax. If you use custom code you may need to look closer at the full release diff.
+
 ## Getting Help
 
 If you encounter issues during the upgrade:

From 61c2926d3e7b1ef15815d76a49c17d2c28331077 Mon Sep 17 00:00:00 2001
From: Emma De Silva <emma@desilva.se>
Date: Wed, 1 Oct 2025 14:27:08 +0200
Subject: [PATCH 11/11] Final release notes proofreading

---
 RELEASE_NOTES.md                      | 6 ++++--
 docs/getting-started/release-notes.md | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 927eabd2ea5..c9fbcdca9f8 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -4,6 +4,8 @@
 
 HydePHP v2.0 represents a major evolution of the framework, introducing significant improvements to the asset system, navigation API, and overall developer experience. This release modernizes the frontend tooling by replacing Laravel Mix with Vite, completely rewrites the navigation system for better flexibility, and introduces numerous performance optimizations throughout the framework.
 
+This document will give you an overview of the changes. When you're ready to upgrade your site, take a look at the [Upgrade Guide](https://hydephp.com/docs/2.x/upgrade-guide).
+
 ## Major Features
 
 ### 🚀 Modern Frontend Tooling with Vite
@@ -11,7 +13,7 @@ HydePHP v2.0 represents a major evolution of the framework, introducing signific
 We've replaced Laravel Mix with Vite for a faster, more modern development experience:
 - **Instant Hot Module Replacement (HMR)** for real-time updates during development
 - **Direct asset compilation** into the `_media` folder for cleaner builds
-- **Updated build command**: Use `npm run build` instead of `npm run prod` (or `--vite` during the sit build)
+- **Updated build command**: Use `npm run build` instead of `npm run prod` (or `--vite` during the site build)
 - **Vite facade** for seamless Blade template integration
 - **Optimized asset serving** through the realtime compiler
 - **Hyde Vite plugin** for enhanced integration
@@ -170,7 +172,7 @@ Key changes:
 - A new `Hyde::authors()` method provides access to all site authors
 - Authors can be configured via YAML
 
-The way this system now works is that you first define authors in the config, Hyde the loads this during the booting process, and you can then access them using the get method.
+The way this system now works is that you first define authors in the config, Hyde then loads this during the booting process, and you can then access them using the get method.
 
 ### Medium Impact Changes
 
diff --git a/docs/getting-started/release-notes.md b/docs/getting-started/release-notes.md
index 96a19eeb573..ec572ee9b92 100644
--- a/docs/getting-started/release-notes.md
+++ b/docs/getting-started/release-notes.md
@@ -10,6 +10,8 @@ navigation:
 
 HydePHP v2.0 represents a major evolution of the framework, introducing significant improvements to the asset system, navigation API, and overall developer experience. This release modernizes the frontend tooling by replacing Laravel Mix with Vite, completely rewrites the navigation system for better flexibility, and introduces numerous performance optimizations throughout the framework.
 
+This document will give you an overview of the changes. When you're ready to upgrade your site, take a look at the [Upgrade Guide](https://hydephp.com/docs/2.x/upgrade-guide).
+
 ## Major Features
 
 ### 🚀 Modern Frontend Tooling with Vite
@@ -17,7 +19,7 @@ HydePHP v2.0 represents a major evolution of the framework, introducing signific
 We've replaced Laravel Mix with Vite for a faster, more modern development experience:
 - **Instant Hot Module Replacement (HMR)** for real-time updates during development
 - **Direct asset compilation** into the `_media` folder for cleaner builds
-- **Updated build command**: Use `npm run build` instead of `npm run prod` (or `--vite` during the sit build)
+- **Updated build command**: Use `npm run build` instead of `npm run prod` (or `--vite` during the site build)
 - **Vite facade** for seamless Blade template integration
 - **Optimized asset serving** through the realtime compiler
 - **Hyde Vite plugin** for enhanced integration
@@ -176,7 +178,7 @@ Key changes:
 - A new `Hyde::authors()` method provides access to all site authors
 - Authors can be configured via YAML
 
-The way this system now works is that you first define authors in the config, Hyde the loads this during the booting process, and you can then access them using the get method.
+The way this system now works is that you first define authors in the config, Hyde then loads this during the booting process, and you can then access them using the get method.
 
 ### Medium Impact Changes