Weave Code
Laravel Markdown Response Laravel Package
spatie/laravel-markdown-response
Serve clean markdown versions of your Laravel HTML pages for AI agents and bots. Detects requests via Accept: text/markdown, known user agents, or .md URLs. Driver-based conversion (local PHP or Cloudflare Workers AI), caching, and HTML preprocessing included.
Serve markdown versions of your HTML pages to AI agents and bots
Frequently asked questions about Laravel Markdown Response
- How do I enable markdown responses for specific routes in Laravel?
- Wrap your routes in the `ProvideMarkdownResponse` middleware. For example, use `Route::middleware(ProvideMarkdownResponse::class)->group(...)` to apply it to a group of routes. This detects markdown requests via `Accept: text/markdown`, AI user agents, or `.md` URL suffixes.
- Does this package work with Laravel 10/11, and what PHP version is required?
- Yes, it’s fully compatible with Laravel 10 and 11. The package requires PHP 8.1+, aligning with Laravel’s current support. No external framework dependencies beyond optional Cloudflare API integration.
- Can I use the Cloudflare Workers AI driver instead of the local PHP converter?
- Absolutely. Set the `MARKDOWN_RESPONSE_DRIVER` environment variable to `cloudflare` in your `.env` file. This trades local processing for potentially higher accuracy with complex HTML, but introduces an external API dependency.
- How do I exclude certain routes from markdown conversion (e.g., API or admin pages)?
- Use the `DoNotProvideMarkdownResponse` middleware on routes you want to exclude. For example, `Route::middleware(['auth', 'DoNotProvideMarkdownResponse'])->group(...)` prevents markdown responses for those endpoints.
- Will this break existing routes that use `.md` file extensions (e.g., static markdown files)?
- No, but you may need to explicitly exclude them. The middleware strips `.md` suffixes, so `/about.md` maps to `/about`. If you have legacy routes serving `.md` files, add `DoNotProvideMarkdownResponse` to those routes to avoid conflicts.
- How does caching work, and should I use a dedicated cache store for markdown responses?
- Markdown responses are cached by default using Laravel’s cache system. For production, use a dedicated cache store (e.g., Redis) to avoid cache stampedes. Configure the TTL in `config/markdown-response.php` based on your content’s dynamism.
- Can I convert HTML to markdown programmatically outside of HTTP requests (e.g., in CLI tools)?
- Yes! Use the `Markdown` facade: `$markdown = Markdown::convert($html)`. This is useful for background jobs, scheduled tasks, or generating markdown from HTML snippets in non-HTTP contexts.
- How do I test markdown responses in Laravel’s testing environment?
- Use the `Markdown::fake()` method to mock conversions in tests. Assert responses with `Markdown::assertConvertedTo($expectedMarkdown)`. The package integrates with PEST/PHPUnit and Laravel’s testing helpers for seamless test coverage.
- What happens if the HTML-to-markdown conversion fails (e.g., malformed HTML)?
- Failures fall back to the original HTML response. Log conversion errors by extending the `MarkdownResponseExceptionHandler` or listening for `markdown-response.conversion.failed` events. Monitor these for debugging complex HTML structures.
- Are there alternatives to this package for serving markdown to AI agents?
- Alternatives include custom middleware using libraries like `league/html-to-markdown` or server-side solutions like Cloudflare Workers. However, this package offers a Laravel-native, driver-based approach with built-in caching, middleware, and facade support for easier integration.
Weaver
How can I help you explore Laravel packages today?