Caddy-markdown-agents — HTML-to-Markdown conversion for AI agents

Plugins
1

I created a Caddy plugin that converts HTML responses to Markdown on the fly when the request includes Accept: text/markdown. This is the same idea behind Cloudflare’s Markdown for Agents, but implemented as a Caddy middleware so you can use it on any Caddy-powered site without a CDN.

What it does:

  • Detects Accept: text/markdown in the request header (sent by AI agents like Claude Code, OpenCode, Gemini CLI, etc.)
  • Buffers the upstream HTML response and converts it to CommonMark-compliant Markdown
  • Strips non-content elements (<script>, <style>, <nav>, <footer>, <iframe>, <noscript>)
  • Falls back to the original HTML if conversion fails — your site never breaks
  • Regular browser requests pass through completely unaffected

Quick demo — no backend needed:

{
	admin off
	order markdown_for_agents before respond
}

:8080 {
	header /hello Content-Type text/html
	respond /hello `<html><body><h1>Hello</h1><p>This is a <strong>test</strong>.</p></body></html>` 200
	markdown_for_agents
}

# Regular request — returns HTML
curl http://localhost:8080/hello

# Agent request — returns Markdown
curl -H "Accept: text/markdown" http://localhost:8080/hello

Response headers include:

  • Content-Type: text/markdown; charset=utf-8
  • Vary: Accept (prevents cache poisoning)
  • X-Markdown-Tokens (estimated token count for agent context window management)

GitHub: github.com/shengwubin/caddy-markdown-agents

Install:

xcaddy build --with github.com/shengwubin/caddy-markdown-agents

Feedback and contributions welcome.

3 Likes