Middleware that converts HTML responses to Markdown for AI agents — Flask, Django, and FastAPI.
Project description
python-markdown-agents
Python middleware that implements Markdown for Agents — when an AI agent requests Accept: text/markdown, the middleware converts HTML responses to Markdown on the fly, reducing token consumption by ~80%.
Supports Flask, Django, and FastAPI from a single package.
Inspired by Cloudflare's Markdown for Agents and caddy-markdown-agents.
Why?
Feeding raw HTML to an AI agent is wasteful. A simple ## About Us heading costs ~3 tokens in Markdown versus 12-15 tokens wrapped in HTML <div> tags, navigation bars, and scripts. For a typical web page, Markdown delivers the same content at ~80% fewer tokens.
AI agents like Claude Code, OpenCode, and Gemini CLI already send Accept: text/markdown headers when fetching web pages. This middleware lets your Python web app respond in kind — minimal code changes required.
How It Works
Request → Accept: text/markdown?
├─ No → Pass through unchanged
└─ Yes → Get response → Is it text/html? → Convert to Markdown → Respond
The middleware:
- Checks the
Acceptheader fortext/markdown - Only converts responses with
Content-Type: text/html - Strips non-content elements:
<script>,<style>,<nav>,<footer>,<iframe>,<noscript> - Returns Markdown with proper response headers
Regular browser requests are completely unaffected.
Error handling: If the HTML-to-Markdown conversion fails, the middleware falls back to serving the original HTML response and logs a warning. Your site never breaks because of a conversion issue.
Installation
# Pick your framework
pip install markdown-agents[flask]
pip install markdown-agents[django]
pip install markdown-agents[fastapi]
# Or install all frameworks
pip install markdown-agents[flask,django,fastapi]
Usage
Flask
from flask import Flask
from markdown_agents.flask import MarkdownAgents
app = Flask(__name__)
app.wsgi_app = MarkdownAgents(app.wsgi_app)
Django
# settings.py
MIDDLEWARE = [
"markdown_agents.django.MarkdownAgentsMiddleware",
# ... other middleware
]
FastAPI
from fastapi import FastAPI
from markdown_agents.fastapi import MarkdownAgentsMiddleware
app = FastAPI()
app.add_middleware(MarkdownAgentsMiddleware)
Response Headers
| Header | Value | Purpose |
|---|---|---|
Content-Type |
text/markdown; charset=utf-8 |
Declares response format |
Vary |
Accept |
Prevents cache poisoning — tells caches the same URL has multiple representations |
X-Markdown-Tokens |
<integer> |
Estimated token count (content_length / 4) for agent context window management |
Quick Demo
pip install markdown-agents[flask]
# demo.py
from flask import Flask
from markdown_agents.flask import MarkdownAgents
app = Flask(__name__)
app.wsgi_app = MarkdownAgents(app.wsgi_app)
@app.route("/")
def index():
return "<html><body><h1>Hello</h1><p>This is a <strong>test</strong>.</p></body></html>"
if __name__ == "__main__":
app.run(port=8780)
# Regular request — returns HTML
curl http://localhost:8780/
# Agent request — returns Markdown
curl -H "Accept: text/markdown" http://localhost:8780/
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Lint
ruff check .
# Format
ruff format .
Requirements
- Python 3.10+
- One of: Flask >= 2.0, Django >= 4.0, FastAPI >= 0.100
License
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file markdown_agents-0.1.0.tar.gz.
File metadata
- Download URL: markdown_agents-0.1.0.tar.gz
- Upload date:
- Size: 8.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5cf1e636499c9e29e102e8078fbf493e2cb14b0b3f516b19c82e30852a611fe2
|
|
| MD5 |
875dc04f3ae975b32963f47a3fb43f55
|
|
| BLAKE2b-256 |
605ea2724752cbff288f2950a11e77f3dedaa470f2213947f7e9427be597a1df
|
File details
Details for the file markdown_agents-0.1.0-py3-none-any.whl.
File metadata
- Download URL: markdown_agents-0.1.0-py3-none-any.whl
- Upload date:
- Size: 8.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0691877bf9f204c410a8ed155d93147800701bc22e8c3a2a2f550c04ac92df95
|
|
| MD5 |
cfe0d73ace7804ba5042a30ece7b28b1
|
|
| BLAKE2b-256 |
c74a35de5f9829223a6f45e92047f15e40d283ee367dcb10a3efae0a027a98f3
|
