Framework Laravel Package

Getting Started

HydePHP is "Laravel for static sites": a Laravel application that compiles Markdown and Blade into a static HTML site in _site. The hyde/framework package is the engine — in practice you almost never composer require it into an existing app. Start from the starter skeleton so you get the directory layout, configs, and the hyde binary wired up:

composer create-project hyde/hyde my-site
cd my-site
php hyde serve          # local preview
php hyde build          # compile to _site/

First places to look:

1. config/hyde.php — site behavior, navigation, features (search, sitemap, RSS).
2. config/site.php — site name, URL, author, language, metadata used in <head>, feeds, and sitemap.
3. _pages/, _posts/, _docs/ — all source content (Markdown .md or Blade .blade.php).
4. resources/views/ — layouts and your own Blade components.

First use case — a one-file page:

php hyde make:page "About"

This drops _pages/about.md with front matter. Edit it, run php hyde serve, and the route is discovered automatically (file name → /about). Then php hyde build and deploy _site/ anywhere static files are served.

If you must add Hyde to an existing Laravel app, expect to do the skeleton's work yourself: publish configs, create the _pages/_posts/_docs/_media directories, register the service provider and the hyde console entry point, and confirm the version's expected Laravel/PHP constraints before committing to it. Those constraints are documented per version (the v2.0.3 patch refreshed the supported-versions docs and the version-scoped documentation links), so read the version-specific docs rather than the root README.

Implementation Patterns

Markdown-first with front matter. Pages, posts, and docs are plain files with YAML front matter (title, description, author, date, image, navigation, slug). The daily loop is: create file → set front matter → preview → build.

Blade when Markdown isn't enough. A _pages/foo.blade.php is rendered as a Blade view, so you can use layouts, components, loops over collections, and @foreach over Hyde::posts(). Use Blade pages for landing pages and index-style pages; keep prose in Markdown.

Query the content graph from Blade. Hyde exposes typed collections — Hyde::pages(), Hyde::posts(), Hyde::docs() — with the usual Laravel collection API:

@foreach (Hyde::posts()->sortByDesc('date')->take(5) as $post)
    <a href="{{ $post->url }}">{{ $post->title }}</a>
@endforeach

Page classes (Hyde\Pages\MarkdownPage, MarkdownPost, DocumentationPage, BladePage) are the extension points when you need custom behavior.

Blog and docs are mostly configuration. Posts are discovered from _posts and sorted by date; RSS and sitemap are generated at build time. Docs get a sidebar configured in config/docs.php (ordering, grouping, header); use front matter for per-page overrides rather than hardcoding links.

Navigation is declared, not hand-written. Define items in config/hyde.php (or opt pages in via navigation front matter) so the menu, sitemap, and route table stay consistent. Custom links in a layout will not appear in the generated sitemap or search index.

Deployment pattern. Commit source, build in CI, publish _site:

- run: composer install --no-dev --optimize-autoloader
- run: php hyde build
- uses: actions/upload-pages-artifact@v3
  with: { path: _site }

The starter ships a GitHub Pages workflow; adapt the same build-and-upload shape for Netlify, Cloudflare Pages, or S3. Cache vendor/ and the Composer cache keyed on composer.lock.

Integration with the Laravel side. Because Hyde is a Laravel app, ordinary Laravel patterns apply: service providers for bootstrapping, custom Artisan commands, config files read through config(), Blade components in resources/views/components. That's the seam for anything non-static — content transforms, custom collections, build-time validation.

Gotchas and Tips

• You're looking at the engine, not the product. The framework repo has low stars and zero dependents because users install hyde/hyde; the starter's docs and issues are where the real usage signal lives. Don't judge adoption by this repo alone, and don't expect its README to be a getting-started guide.
• _site is generated output. Never edit it by hand. Decide deliberately whether to commit it (branch-based Pages deploy) or gitignore it (artifact-based deploy); mixing both causes confusing stale-site bug reports.
• File path equals URL. Renaming or moving a file silently changes its route and breaks inbound links. Use the slug front matter when you want to decouple URL from filename, and add redirects yourself — Hyde won't infer them.
• Front matter is YAML and fails quietly-ish. An unquoted colon in title, a malformed date, or wrong indentation can drop a post from sorting, feeds, or the search index. If a post "disappears," check front matter before anything else.
• Blade pages don't get Markdown. _pages/x.blade.php is compiled as a view; Markdown syntax there renders literally. Conversely, don't put PHP in .md.
• Stale caches after config or view changes. Hyde leans on Laravel's config and view caches. When behavior doesn't match config/, clear storage/framework/views (and run php artisan config:clear) before debugging logic.
• CSS is prebuilt, and Vite is a trap. Hyde ships a compiled stylesheet; utility classes you invent at author time may not exist in it. If you need custom Tailwind classes, use the project's CSS build step (or Vite) or safelist them — otherwise styles silently no-op in _site while looking fine if you're testing against an old build. Since v2.0.3 the build command no longer inherits the Vite dev server asset path when a dev server happens to be running, so production builds stopped pointing at localhost:5173; if you were relying on that quirk (or are on ≤ v2.0.2 and see unstyled deploys), upgrade and rebuild rather than chasing the CSS.
• Build errors now surface loudly (v2.0.3). The build pipeline previously absorbed exceptions from build tasks; it now propagates them. If php hyde build starts failing immediately after upgrading from v2.0.2, that's a pre-existing broken task being exposed, not a regression — read the trace and fix the task (or your custom BuildTask).
• Preview server vs. build. php hyde serve is a dev server; only php hyde build exercises the full static pipeline (asset copying, sitemap, feeds, search index). Bugs that appear only after deploy usually mean "works in serve, never built." In containers, bind explicitly: php hyde serve --host 0.0.0.0.
• Search and feeds are build artifacts. Changing content requires a rebuild for search.json/RSS to update; a running preview won't reflect them the way it reflects pages.
• Upgrades are structural. Hyde majors have moved directories and config keys. Pin hyde/framework in composer.json, read the upgrade guide, and rebuild from a clean _site — a half-upgraded skeleton produces missing-view and missing-config errors that look like framework bugs. Patch releases (2.0.x) are generally safe, but still composer update hyde/framework deliberately and rebuild; 2.0.3 also bumps the supported illuminate/console range, so let Composer resolve the pair together rather than pinning console by hand.
• Cosmetic config is still config. UI affordances — e.g. the footer "scroll to top" button, smooth-scroll behavior added in v2.0.3 — are toggled in config/hyde.php / the appearance config, not by editing published Blade views. Check config before overriding a view you'll have to maintain across upgrades.
• Debugging order: (1) front matter, (2) config cache, (3) route collision between a discovered page and a manually registered Laravel route, (4) storage/logs/laravel.log. Route collisions are the sneaky one — auto-discovery means adding a file can shadow a custom route.
• Extension points worth knowing: custom page classes, Hyde:: collections in Blade, Laravel service providers and Artisan commands for build-time work, and overriding framework views/components from your app. Reach for a custom page class before forking the framework.