Markdown Routes with Next.js
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.
Log in to mark your progress for each Lesson and Task
Let's verify what stuck.
You must be logged in to answer questions
Why use `next.config.ts` rewrites instead of checking headers in the page component?
1
Rewrites are processed before the page component runs, avoiding unnecessary rendering
2
Rewrites are faster than reading headers
3
Page components can't access request headers
4
Rewrites work better with TypeScript
You must be logged in to answer questions
What does the `[[...slug]]` pattern do in Next.js Route Handlers?
1
Creates a required single parameter
2
Creates an optional catch-all that matches zero or more segments
3
Creates a required catch-all that must have at least one segment
4
Escapes special characters in the URL
You must be logged in to answer questions
Why disable Stega markers for markdown output?
1
They slow down the response
2
They add invisible Unicode characters that break markdown rendering
3
They're only needed for HTML
4
They increase the response size significantly
You must be logged in to answer questions
What Content-Type header should markdown routes return?
1
text/plain
2
text/html
3
text/markdown; charset=utf-8
4
application/markdown
You must be logged in to answer questions
Why normalize internal links to absolute URLs in markdown?
1
Relative URLs don't work in markdown syntax
2
AI agents consuming markdown outside a browser can't resolve relative paths
3
Absolute URLs are better for SEO
4
It's required by the Portable Text specification
You must be logged in to answer questions
What's the purpose of the sitemap.md route?
1
SEO optimization for search engines
2
Providing a structured index for AI agents to discover all available content
3
Generating an XML sitemap
4
Tracking which articles have markdown versions
You must be logged in to answer questions
How does `Vary: Accept` affect CDN caching?
1
It disables caching entirely
2
It tells the CDN to cache multiple versions based on the Accept header
3
It improves cache hit rates
4
It only affects HTML responses
Count your correct answers:
- 7/7 — Excellent! You've mastered markdown routes.
- 5-6 — Good understanding. Review the topics you missed.
- 3-4 — Solid start. Re-read the lessons for missed questions.
- 0-2 — Take another pass through the course material.
Congratulations! You now have a documentation site that serves:
- HTML articles for human users in browsers
- Markdown responses for AI agents via content negotiation
- Explicit .md suffix URLs for direct access
- A /sitemap.md for content discovery
- A CopyMarkdown button for humans who want markdown
This pattern makes your content accessible to both audiences from a single source of truth.
Ideas for extending what you've built:
- Add search — Include a search endpoint that returns markdown results
- Version tracking — Serve different content versions based on API version
- PDF export — Add a Route Handler that generates PDFs
- Agent analytics — Track which AI tools are using your docs most
Course complete! You're ready to make your content accessible to AI agents.
You have 7 uncompleted questions in this lesson
0 of 7