Build sites that serve both HTML for humans and markdown for AI agents. Learn to implement content negotiation using Next.js Route Handlers and rewrites, convert Portable Text to markdown, and create a discoverable sitemap.md for agent navigation.
1. Why your docs need markdown routes for AI and tools
Learn why modern documentation should serve both HTML and markdown, how Accept header content negotiation compares to explicit markdown URLs, and why a dual-route strategy best supports AI agents, tools, and human readers.
2. Set up markdown-ready docs with Next.js and Sanity
Extend your existing Next.js + Sanity project with schemas, queries, and routing structure needed to export documentation content as markdown files alongside your HTML pages.
3. Portable Text to Markdown
Sanity stores content as Portable Text — now we need to turn it into markdown.
4. Building the Markdown Route Handler
Time to serve our first markdown — Route Handlers that return docs articles as markdown.
5. Content Negotiation with Rewrites
Configure Next.js rewrites to serve markdown via .md suffix URLs and Accept header negotiation, keeping the same base URL for HTML and markdown.
6. Section and sitemap routes for agent-friendly docs
Set up a dedicated /sitemap.md route and section listings so AI agents and users can quickly discover your documentation structure, access markdown versions of pages, and benefit from optimized queries and caching for navigation versus full article content.
7. The CopyMarkdown Component
AI agents fetch markdown automatically, but humans need a button.
8. Production-ready markdown routes
Configure caching, headers, analytics, performance, and error handling so your markdown routes run efficiently and reliably in production.
9. Serve markdown for AI agents with Next.js route handlers
Review the key concepts for building markdown-first routes in Next.js that serve both browsers and AI agents from a single source of truth, including rewrites, optional catch-all routes, content negotiation, stega markers, and markdown sitemaps.