- Can Laravel Docit replace my existing Laravel-based documentation system (e.g., custom routes + Blade templates)?
- Yes, if your docs are static or semi-static. Laravel Docit leverages HydePHP to pre-generate pages, reducing server load and improving performance. However, if your docs require real-time user interactions (e.g., comments, user-specific content), you’ll need to proxy requests through Laravel or host the static site separately.
- What Laravel versions does Laravel Docit support, and is it compatible with PHP 8.1+?
- Laravel Docit officially supports Laravel 8+ and assumes PHP 8.0+ for modern Laravel compatibility. While no explicit PHP 8.1+ constraints are listed, the package aligns with Laravel’s latest practices, so it should work without issues. Always check the package’s `composer.json` for precise version requirements.
- How do I integrate Laravel Docit with Laravel’s asset pipeline (e.g., Vite or Laravel Mix)?
- Laravel Docit generates static assets during builds, so you’ll need to configure HydePHP’s asset paths to match Laravel’s public/ directory or your Vite/Mix output. For Vite, ensure HydePHP’s CSS/JS paths align with Vite’s build directory (e.g., `resources/js` → `public/build`). Use Laravel’s `mix()` or Vite’s `@vite()` directives in Blade templates for dynamic asset references.
- Can I use Laravel Docit to serve documentation under a subdomain (e.g., docs.myapp.com) while keeping the main app on myapp.com?
- Yes, but you’ll need to configure HydePHP’s routes to avoid conflicts with Laravel’s dynamic routes. Use a route prefix (e.g., `/docs/*`) in Laravel’s `routes/web.php` to delegate static doc requests to the generated HydePHP files. Alternatively, host the static docs separately (e.g., Netlify, S3) and proxy requests through Laravel if authentication is needed.
- Does Laravel Docit support Markdown tables of contents (TOC) or custom metadata (e.g., last updated, authors)?
- Laravel Docit relies on HydePHP’s Markdown parsing, which supports basic front-matter metadata (e.g., YAML headers in Markdown files). For tables of contents, HydePHP auto-generates navigation from file structure, but custom metadata like authorship requires manual front-matter definitions or post-processing with Laravel’s Blade templates during builds.
- How do I trigger builds in CI/CD (e.g., GitHub Actions) without manual intervention?
- Add a `docit:build` Artisan command to your CI pipeline (e.g., `php artisan docit:build`). For GitHub Actions, use a step like `run: php artisan docit:build` after your `composer install`. Cache HydePHP’s dependencies to speed up builds, and deploy the generated `public/docs/` directory to your static host or Laravel’s storage.
- Will Laravel Docit work if I store Markdown files in a database (e.g., a `markdown_content` column) instead of the filesystem?
- Indirectly, yes—but you’ll need to pre-process the content. Fetch Markdown from the DB during a build step (e.g., using Laravel’s Storage facade or a custom Artisan command), save it to temporary filesystem files, then run `php artisan docit:build`. This approach adds complexity but enables dynamic content sources while keeping the static generation benefits.
- Are there alternatives to Laravel Docit for static docs in Laravel, and when should I choose them?
- Alternatives include **Laravel + HydePHP directly** (more control but less integration), **Laravel + Hugo** (faster builds, less Blade support), or **Laravel + Spatie’s Markdown** (dynamic rendering). Choose Laravel Docit if you want tight Blade integration, minimal setup, and a balance between static performance and Laravel’s ecosystem. Use Hugo if speed is critical, or Spatie’s package if you need dynamic Markdown rendering.
- How do I handle authentication for private documentation (e.g., internal wikis) if the docs are static?
- Static sites can’t natively handle auth, but you can proxy requests through Laravel. Configure a route like `Route::get('/docs/{path}', [DocitController::class])` to serve static files only if the user is authenticated. Alternatively, host the static docs separately and use Laravel’s session/auth middleware to gate access to the proxy endpoint.
- What happens if HydePHP (the underlying static site generator) stops receiving updates or introduces breaking changes?
- Since Laravel Docit is a thin wrapper around HydePHP, breaking changes in HydePHP could affect compatibility. Monitor HydePHP’s GitHub repo for updates and consider forking or contributing to its maintenance if critical. For production use, test builds regularly and have a fallback plan (e.g., switching to Hugo or a custom solution) if HydePHP becomes unstable.