Weave Code
Laravel Markdown Response Laravel Package
spatie/laravel-markdown-response
Serve markdown versions of your Laravel HTML pages for AI agents and bots. Detect markdown requests via Accept: text/markdown, known user agents, or .md URLs. Driver-based conversion (local PHP or Cloudflare Workers AI), with caching and HTML preprocessing.
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, `Route::middleware(ProvideMarkdownResponse::class)->get('/docs', [DocsController::class, 'show']);`. This automatically converts responses to markdown when the `Accept: text/markdown` header is detected or for known AI user agents.
- Does this package support Laravel 10+ and PHP 8.1+ only?
- Yes, the package is officially tested and supported for Laravel 10+ and PHP 8.1+. While it may work on older versions, no guarantees are provided for Laravel 9 or PHP 8.0 due to dependency constraints. Check the [README](https://github.com/spatie/laravel-markdown-response) for potential workarounds.
- Can I customize how HTML elements are converted to markdown?
- Yes, the package allows customization via the `MarkdownResponse` facade. Use `Markdown::convert($html, $customProcessor)` to pass a custom processor or extend the default `HtmlToMarkdownConverter` class. This is useful for handling domain-specific elements like Mermaid diagrams or syntax-highlighted code blocks.
- What happens if the HTML structure is poorly formatted or contains unsupported elements?
- Unsupported HTML elements (e.g., `<canvas>`, `<video>`) default to `[unsupported]` tags in the markdown output. For complex or malformed HTML, consider pre-processing your content with tools like TidyHTML or implementing a fallback to return the original HTML when conversion fails.
- How does caching work for markdown responses, and can I optimize performance?
- Markdown responses are cached automatically via Laravel’s cache system. For dynamic content, use `Cache::tags('markdown')` to invalidate caches when content changes. Pre-generating markdown for static content (e.g., documentation) via `MarkdownResponse::generate()` can further reduce runtime overhead.
- Will this package slow down my Laravel application in production?
- The conversion adds minimal overhead (~1–2ms per request in development). In production, caching ensures repeated requests for the same content are served instantly. For high-traffic routes, consider pre-generating markdown or using a dedicated service like Cloudflare Workers for conversion.
- How do I test if markdown responses are working correctly for my AI agents?
- Use `curl -H 'Accept: text/markdown' https://your-app.com/docs` to simulate an AI agent request. Compare the output against golden samples or validate it with tools like `pandoc` or custom scripts. Test edge cases like nested tables, code blocks, and unsupported elements to ensure quality.
- Can I use this package to serve markdown responses for API endpoints?
- Yes, the package works seamlessly with API routes. Simply apply the middleware to your API group or routes. Clients can request markdown by setting the `Accept: text/markdown` header, making it ideal for APIs consumed by AI agents or documentation tools.
- Are there alternatives to this package for HTML-to-markdown conversion in Laravel?
- For standalone conversion, you could use `league/html-to-markdown` directly or tools like `pandoc`. However, this package offers Laravel-specific features like middleware integration, caching, and AI agent detection, making it the most convenient choice for Laravel applications.
- How do I handle failures or errors during markdown conversion?
- By default, the package logs errors and returns the original HTML response if conversion fails. You can customize this behavior by extending the `MarkdownResponse` class or using middleware to implement fallback logic, such as returning a 406 Not Acceptable status for unsupported content.
Weaver
How can I help you explore Laravel packages today?