django-markdown-middleware 0.1.0

A Django middleware for rendering Markdown responses.

A Django middleware that converts HTML responses to Markdown when the client sends an Accept: text/markdown request header.

Requirements

django-markdown-middleware supports Python 3.11+ and requires Django 5.2 or later.

Installation

$ pip install django-markdown-middleware

Add the middleware to your Django settings:

MIDDLEWARE = [
    ...
    "markdown_middleware.middleware.MarkdownMiddleware",
    ...
]

The middleware must be placed after any middleware that sets the response content type (e.g. after CommonMiddleware).

Usage

Any client that sends Accept: text/markdown in the request headers will receive the HTML response body converted to Markdown, with the response Content-Type changed to text/markdown; charset=utf-8.

The response also includes an X-Markdown-Tokens header containing an approximate token count of the converted Markdown content (estimated as len(markdown) // 4).

Only HTTP 200 responses with a text/html content type are converted. All other responses are passed through unchanged.

Caching

To enable caching of converted Markdown responses, set MARKDOWN_MIDDLEWARE_CACHE_TIMEOUT in your Django settings to the desired cache duration in seconds:

# Cache converted Markdown responses for 5 minutes
MARKDOWN_MIDDLEWARE_CACHE_TIMEOUT = 300

When this setting is absent or None, no caching is performed.

Cache keys have the form markdown_middleware:<path>, for example markdown_middleware:/api/products/, making them easy to inspect or manage directly in your cache backend.

Cache Invalidation

To invalidate cached Markdown responses for a specific path, use invalidate_cache. It removes all cached variants of that path, including responses with different query strings:

from markdown_middleware import invalidate_cache

# Invalidates /blog/my-post/, /blog/my-post/?page=2, etc.
invalidate_cache("/blog/my-post/")

This is useful in post-save signals or management commands when content changes and the cached Markdown must be refreshed.

Prepare for development

Install uv, then:

$ uv sync --group dev

Run the tests:

$ make tests