Learn
CoursesMarkdown Routes with Next.jsWhy your docs need markdown routes for AI and tools
Markdown Routes with Next.js

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.
Knut Melvær
Knut MelværHead of Developer Community and Education
Before starting this Course it may be beneficial to have completed:
Log in to mark your progress for each Lesson and Task

Often we publish documentation-type content to the web: docs, knowledge bases, support articles, you name it. Like the very page you are reading now! This content might look great in the browser, but AI agents who increasingly might come by to pick up the information to help their users don’t really need this presentation.

In fact, serving agents a bunch of HTML might just bloat their context window.

So this course teaches you how to return content conditionally to user agents who are asking for markdown content in their request. Without having to duplicate your content.

  • AI agents can favor from content as markdown over HTML because it is plain text with lightweight structure (headings, lists, code blocks) and minimal noise, making it easier and more efficient for LLMs to parse and uses less tokens.
  • The HTTP Accept header lets a client tell the server which content type it wants (e.g. text/html vs text/markdown), enabling content negotiation for the same URL. Agents has started to request this on the web.
  • Implementing both Accept header negotiation and explicit markdown URLs provides flexibility: standards-based negotiation for capable agents, simple explicit routes for tools and testing, and clearer analytics.
  • Using Vary: Accept allows CDNs to cache different representations per Accept header, but it can reduce cache hit rates and complicate caching behavior because the same URL now has multiple variants.
# HTML by default (browser-like request)
curl https://www.sanity.io/learn/course/markdown-routes-with-nextjs


# Markdown via Accept header (content negotiation)
curl -H "Accept: text/markdown" https://www.sanity.io/learn/course/markdown-routes-with-nextjs


# Direct markdown URL (explicit route)
curl https://www.sanity.io/learn/course/markdown-routes-with-nextjs.md
You must be logged in to answer questions
Why do AI agents and tools benefit from dedicated markdown routes in addition to HTML docs?
1
Because markdown is plain text with lightweight structure, making it easier for LLMs and tools to parse than HTML, and explicit routes simplify access, analytics, and caching.
2
Because browsers cannot render HTML and require markdown instead.
3
Because the Accept header only works for image formats, not for documentation content.
4
Because markdown routes completely replace the need for HTML documentation for human users.
You have 1 uncompleted question in this lesson
0 of 1