Skip to main content
Our docs redesign is live!

Markdown Routes

The site exposes markdown versions of blog posts, guides, kickstarts, and live streams.

Routes

  • Blogs: /blog/[slug].md
  • Guides: /guides/[...slug].md
  • Full guide (all chapters): /guides/[slug]/full.md
  • Kickstarts: /kickstarts/[...slug].md
  • Live streams: /livestreams/[...slug].md
  • Homepage: /index.md (also via Accept: text/markdown on /; responses include Vary: Accept)
  • Sitemap: /sitemap.md

Markdown handlers are centralized in lib/markdown/routeUtils.ts to keep markdown routes consistent. Missing markdown resources return HTTP 404 with Content-Type: text/markdown and recovery links (home, search, sitemaps, llms.txt, agents.md, OpenAPI). Do not invent a replacement URL.

Full Guide (/guides/[slug]/full.md)

For multipart guides with chapters, appending /full.md to the parent guide URL returns all chapters concatenated into a single markdown document. The output includes:

  • Parent guide title, metadata, and intro content
  • A table of contents with links to each chapter heading
  • Each chapter's content separated by horizontal rules

This is designed for AI agents that need to consume an entire guide in one request. The regular .md route for parent guides includes a link to the full.md variant so agents can discover it.

Conversion Layer

The content-specific converters (blogMarkdown.ts, guideMarkdown.ts, kickstartMarkdown.ts, and liveStreamMarkdown.ts) share common markdown primitives from lib/markdown/shared.ts:

  • heading/title formatting
  • metadata list composition
  • shared additional-items rendering (notices, FAQs, related cards)
  • canonical source footer formatting

Guide chapter pagination, full-guide concatenation, and live-stream component rendering remain content-specific and are still handled in their dedicated converter modules.

Routing note

Bare HTML paths (/blog/[slug], /guides/..., etc.) always serve HTML. Markdown is only served for explicit .md URLs (and special cases like /guides/[slug]/full.md). Next.js rewrites for *.md are configured as beforeFiles so they run before prerendered pages and cannot be shadowed by the App Router HTML routes.

The homepage is the exception: when Accept prefers markdown over HTML, / is rewritten to /index.md (Launch Edge Function, before CDN cache) or /md/home (Next.js middleware, for local/origin). HTML / stays CDN-cached and primed. Markdown is a separate cache object at /index.md. Responses also set Vary: Accept.

Sitemap Format

/sitemap.md is a human-readable markdown file grouped by content type (Guides, Blog Posts, Live Streams, Pages, People), with markdown links for blog posts, guides, and live streams.

Runtime Compatibility

Markdown route handlers return native Response objects from lib/markdown/routeUtils.ts (not NextResponse) to ensure compatibility with production/serverless app-route validation.

Legacy Routes

The previous /md/blog/..., /md/guides/..., /md/kickstarts/..., and /md/livestreams/... paths now redirect to the new .md URLs.