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
  • Sitemap: /sitemap.md

Markdown handlers are centralized in lib/markdown/routeUtils.ts to keep markdown routes consistent.

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.

Content Negotiation

If a request includes the Accept: text/markdown header, the HTML route will return markdown instead:

  • /blog/[slug] with Accept: text/markdown returns markdown
  • /guides/[...slug] with Accept: text/markdown returns markdown
  • /kickstarts/[...slug] with Accept: text/markdown returns markdown
  • /livestreams/[...slug] with Accept: text/markdown returns markdown

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.