Markdown to agents, HTML to humans

Markdown to agents, HTML to humans is a Next.js demo project that shows how to serve the same documentation URL as raw markdown to AI agents and as rendered HTML to humans using the HTTP Accept header for content negotiation.

What is Markdown to agents, HTML to humans?

It is a minimal open-source demo that implements content negotiation in a Next.js app. The project takes a single URL such as /docs/getting-started and selects a markdown response when the incoming request's Accept header contains text/markdown; otherwise it returns HTML. The project is built with Next.js and TypeScript, uses a rewrite inside next.config.ts, and is deployed at markdown-to-agents.vercel.app. The repository has 26 stars.

What makes it stand out?

• Header-based routing: The rewrite uses the has condition to inspect the accept header and match text/markdown.
• beforeFiles rewrites: The beforeFiles array lets the markdown route take precedence over normal rendering.
• Single source URL: Humans and agents share the same /docs/:slug path, with no separate endpoint.
• Live demo: Curl commands show the difference between Accept: text/markdown and Accept: text/html responses.
• TypeScript configuration: The logic is written in next.config.ts, so it benefits from type checking.

Who should use it?

• Next.js developers building documentation sites that need to serve both humans and AI agents.
• Agent and tool builders who need markdown input for LLMs and can use this pattern to fetch clean source.
• Technical writers who want to maintain one document and have it automatically deliver markdown to agents.

What can you do with it?

• AI agents: Send a request with Accept: text/markdown to get the documentation as markdown for context.
• Website visitors: Access the same URL in a browser and receive the HTML version.
• Developers: Use the project as a reference implementation for content negotiation in Next.js.

How does it work?

• The rewrite in next.config.ts matches requests to /docs/:slug when the accept header contains text/markdown and rewrites them to /markdown/:slug.
• The markdown route returns the original markdown file, while normal requests proceed to the standard HTML page.