Serving Markdown to AI Agents via Accept Headers

Bun announced they started serving their documentation as raw Markdown to Claude Code instead of rendered HTML. The results were a 10x reduction in token usage.

It’s a great idea. I immediately went to implement it on our roots.io docs, which uses Laravel routes within our WordPress site thanks to Acorn.

I’ll show an implementation in Laravel, but the concept applies to any web framework.

Getting started

Create a Laravel app and install the CommonMark package for converting markdown to HTML:

composer require league/commonmark

Creating the files

You’ll need to create a few files to get this working:

Create the controller at app/Http/Controllers/DocsController.php:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use League\CommonMark\CommonMarkConverter;

class DocsController extends Controller
{
    public function show(Request $request, $slug)
    {
        $slug = basename($slug);
        $filePath = resource_path("content/docs/{$slug}.md");

        if (!file_exists($filePath)) {
            abort(404);
        }

        $markdown = file_get_contents($filePath);

        if ($this->shouldServeMarkdown($request)) {
            return response($markdown, 200)
                ->header('Content-Type', 'text/markdown; charset=UTF-8');
        }

        // Convert to HTML for regular users
        $converter = new CommonMarkConverter();
        $html = $converter->convert($markdown);

        return view('docs', ['content' => $html]);
    }

    protected function shouldServeMarkdown(Request $request): bool
    {
        $acceptHeader = $request->header('Accept', '');
        return str_contains($acceptHeader, 'text/markdown');
    }
}

Create a sample Markdown file at resources/content/docs/example.md:

# Example Markdown File

Howdy!

## Markdown example

This content is written in **Markdown**.

Create the view at resources/views/docs.blade.php:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Documentation</title>
</head>
<body>
    <div class="docs-content">
        {!! $content !!}
    </div>
</body>
</html>

Add the route in routes/web.php:

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\DocsController;

Route::get('/', function () {
    return view('welcome');
});

Route::get('/docs/{slug}', [DocsController::class, 'show']);

Now if you visit /docs/example in your browser, you’ll see the rendered HTML. But if you make a request with an Accept header requesting Markdown, you’ll get the raw Markdown instead.

Testing it out

To test your implementation, use cURL with an Accept header:

# Request Markdown via Accept header
curl -H "Accept: text/markdown" http://localhost:8000/docs/example

You should see the raw Markdown returned instead of HTML. Without this header, you’ll get the full HTML page.

About content negotiation

The implementation uses the HTTP Accept header for content negotiation. Clients that want Markdown can request it using Accept: text/markdown.

The HTTP Content-Type header for Markdown content is text/markdown. This media type is defined in RFC 7763. While browsers don’t have native support for rendering Markdown, using the proper media type ensures clients can correctly identify the content format.

Why this matters

This approach provides benefits for different types of clients:

For LLMs: They’re typically charged based on token usage, and HTML is very verbose compared to Markdown. By serving Markdown directly, you can significantly reduce the number of tokens processed, leading to cost savings and improved performance.

For other clients: Tools that work better with Markdown (like documentation scrapers, content management systems, etc.) can explicitly request it via the Accept header.