Weave Code
Laravel Markdown Response Laravel Package
spatie/laravel-markdown-response
Serve markdown versions of Laravel HTML pages to AI agents and bots. Detects text/markdown Accept headers, AI user agents, or .md URLs; converts via local PHP or Cloudflare Workers AI, caches results, and supports HTML preprocessing.
spatie/laravel-markdown-response lets your Laravel app serve clean markdown versions of HTML pages to AI agents and bots. Requests are detected automatically via the Accept: text/markdown header, known AI user agent patterns, or a .md URL suffix—so /about.md returns a readable markdown rendering while normal visitors still get HTML.
Conversion is driver-based (local PHP or Cloudflare Workers AI), with built-in caching and HTML preprocessing before conversion.
- Simple middleware: wrap routes with
ProvideMarkdownResponse - Convert HTML directly via the
Markdownfacade - Pluggable drivers: local PHP or Cloudflare Workers AI
- Cached results for performance
- Preprocess HTML before conversion
- Pest-friendly testing helpers
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?