Markdown for Agents

Cloudflare Markdown for Agents on the Free Plan

Cloudflare offers managed HTML-to-Markdown conversion through its Markdown for Agents feature. Cloudflare documents that feature for Pro, Business, and Enterprise plans. Astro projects on the Free plan can implement the same delivery pattern at the application or build layer.

@puralex/astro-markdown-for-agents provides two options.

Option 1: Cloudflare Workers runtime

Use Astro server output with the Cloudflare adapter. Middleware inspects the request and converts HTML responses when Markdown is requested.

pnpm add @astrojs/cloudflare @puralex/astro-markdown-for-agents
// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
import markdownForAgents from '@puralex/astro-markdown-for-agents';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
  integrations: [markdownForAgents()],
});

Verify locally and after deployment:

curl -i \
  -H "Accept: text/markdown" \
  https://example.com/docs

The middleware uses Web APIs and has no runtime package dependencies. The converter does not require a browser DOM.

Option 2: Static Pages output

For a fully static Astro site, keep normal static output:

import { defineConfig } from 'astro/config';
import markdownForAgents from '@puralex/astro-markdown-for-agents';

export default defineConfig({
  integrations: [markdownForAgents()],
});

The build produces HTML and Markdown variants:

/docs/index.html
/docs/index.md
/llms.txt

Agents can consume explicit Markdown URLs. Header-based content negotiation needs a Cloudflare rule or Worker that rewrites Markdown requests to the matching .md file.

Cache behavior

Negotiated HTML and Markdown share a URL, so caches must distinguish them. Runtime responses include a Vary header. When adding custom Cloudflare caching or transformations, verify that a Markdown response cannot be cached and served to browsers.

Test both directions after every cache change:

# Must remain HTML
curl -sI https://example.com/docs

# Must be Markdown
curl -sI -H "Accept: text/markdown" https://example.com/docs

Which option should you use?

Choose runtime middleware when:

Choose generated Markdown when:

Both approaches avoid requiring Cloudflare’s managed paid-plan conversion.