DOCSEARCHbyAlgolia
Submit Docs

HydePHP Documentation

repository·2.x·Indexed 19 days ago

https://github.com/hydephp/hyde

A Laravel-powered static site generator for building blogs, documentation, and websites using Markdown or Blade templates. Features a built-in TailwindCSS frontend, Vite-based asset management, and a CLI for content scaffolding. Includes comprehensive migration guides for upgrading to v2.0, covering dependency updates, the transition from Laravel Mix to Vite, and API changes to the Routes, Asset, and Includes facades.

Tokens
2.5K
Snippets
8
Records
17
Agent score
17%

What's inside HydePHP

  1. Customize frontend layouts and components

    2.x
    All frontend components and page layouts in HydePHP are built using Laravel Blade. To customize them, you can publish the vendor views to your project, allowing you to override the default templates just as you would in a standard Laravel application.

  2. Customize TailwindCSS styles

    2.x

    HydePHP comes with precompiled and minified TailwindCSS styles in app.css and uses HydeFront to serve assets via CDN.

    If you need to customize the Tailwind configuration or add new Tailwind classes via Blade files, you must recompile the styles using the included Vite setup by running:

    npm run build

  3. Install HydePHP via Composer

    2.x

    To create a new HydePHP project, use the composer create-project command. This scaffolds a new directory with the HydePHP structure and dependencies.

    composer create-project hyde/hyde

  4. Create and manage content in HydePHP

    2.x

    HydePHP uses specific directories to organize different types of content. You can place files directly into these folders or use the hyde:make CLI commands to scaffold them with appropriate front matter or layouts.

    • _posts: For blog posts (typically Markdown with Front Matter).
    • _docs: For documentation pages (plain Markdown).
    • _pages: For simple Markdown pages or advanced Laravel Blade files.

  5. Migrate from Laravel Mix to Vite

    2.x

    HydePHP v2.0 uses Vite instead of Laravel Mix for asset management.

    1. Remove Mix: Delete webpack.mix.js from your project root.
    2. Create Vite Config: Create vite.config.js in your project root.
    3. Update CSS: Update resources/assets/app.css to use the new Tailwind v4 @import syntax.
    4. Upgrade Tailwind: Run the automated tool to convert your Tailwind configuration to v4.

    Vite Configuration Example:

    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(),
    ],
});

    New CSS Import Pattern:

    @import 'hydefront/components/torchlight.css' layer(base);
@import 'tailwindcss';
@config '../../tailwind.config.js';
    npx @tailwindcss/upgrade

  6. Upgrade to HydePHP v2.0

    2.x

    HydePHP v2.0 is a major evolution that replaces Laravel Mix with Vite, rewrites the navigation system, and upgrades to Tailwind CSS v4.

    Prerequisites

    • Ensure you are running HydePHP v1.6 or later (v1.8 is recommended).
    • Backup your project by committing all changes to Git or creating a directory backup.

    High-level Upgrade Steps

    1. Update Dependencies: Update composer.json and package.json.
    2. Migrate Frontend: Replace Laravel Mix with Vite and upgrade to Tailwind CSS v4.
    3. Update Configuration: Modify config/hyde.php, config/docs.php, and app/config.php to match new schemas.
    4. Update Code: Adjust usage of Routes, Asset, Includes, and DataCollection.
    5. Rebuild: Clear caches and run the new build commands.
    # Recommended pre-upgrade backup
git init
git add .
git commit -m "Pre-upgrade backup before HydePHP v2.0"

  7. Update Composer and Node Dependencies for v2.0

    2.x

    Update your dependency files to support the new framework version and Vite-based asset pipeline.

    Composer Update

    Update composer.json with the following requirements:

    • php: ^8.2
    • hyde/framework: ^2.0
    • laravel-zero/framework: ^11.0
    • hyde/realtime-compiler: ^4.0 (dev)

    Then run:

    composer update

    Node/NPM Update

    Replace the devDependencies in package.json with the Vite-compatible set and add "type": "module" to the top level of the file. Update your scripts to use Vite.

    New Scripts:

    "scripts": {
    "dev": "vite",
    "build": "vite build"
}

    Then run:

    npm install
    {
    "type": "module",
    "require": {
        "php": "^8.2",
        "hyde/framework": "^2.0",
        "laravel-zero/framework": "^11.0"
    },
    "require-dev": {
        "hyde/realtime-compiler": "^4.0"
    },
    "devDependencies": {
        "@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"
    }
}

  8. Build your static site

    2.x

    Once your content is ready, run the build command. HydePHP will compile your Markdown and Blade files into static HTML files, which are saved in the _site directory.

    php hyde build

  9. Update Documentation Configuration (config/docs.php)

    2.x

    The sidebar and table of contents configuration in config/docs.php has been reorganized into a single sidebar key.

    New Structure:

    'sidebar' => [
    'order' => [
        'readme',
        'installation',
    ],
    
    'labels' => [
        // ...
    ],

    'table_of_contents' => [
        'enabled' => true,
        'min_heading_level' => 2,
        'max_heading_level' => 4,
    ],
],

  10. Update HydePHP Configuration (config/hyde.php)

    2.x

    Several keys and formats in config/hyde.php have changed in v2.0.

    Features (Enums)

    Replace method calls with Enum values.

    • Old: Features::htmlPages()
    • New: Feature::HtmlPages

    Navigation

    Navigation items must now be an array of objects or use the Navigation facade.

    • Old: 'Custom Item' => '/custom-page'
    • New: ['label' => 'Custom Item', 'destination' => '/custom-page']
    • Facade: Navigation::item('url', 'label', status_code)

    Other Key Changes

    • Subdirectory Display: Rename subdirectories to subdirectory_display.
    • Cache Busting: Rename enable_cache_busting to cache_busting.
    • Authors: The format is now an associative array keyed by username.
    • HydeFront: Remove hydefront_version and hydefront_cdn_url (now automatic).

    New Author Format:

    'authors' => [
    'username' => Author::create(
        name: 'Display Name',
        website: 'https://example.com',
        bio: 'Author bio',
        avatar: 'avatar.png',
        socials: ['twitter' => '@username']
    ),
],

  11. Update Application Configuration (app/config.php)

    2.x

    In app/config.php, you must register the new Navigation service provider and update aliases.

    Providers: Add Hyde\Foundation\Providers\NavigationServiceProvider::class, to the 'providers' array.

    Aliases: Add the following to the 'aliases' array:

    • 'Vite' => \Hyde\Facades\Vite::class,
    • 'MediaFile' => \Hyde\Support\Filesystem\MediaFile::class,

  12. Troubleshoot asset compilation issues

    2.x

    If your assets are failing to compile after an upgrade, follow these steps to reset your environment:

    1. Delete node_modules and package-lock.json.
    2. Run npm install to reinstall dependencies.
    3. Clear the _media directory.
    4. Run npm run build to attempt a fresh compilation.
    rm -rf node_modules package-lock.json
npm install
rm -rf _media
npm run build