Recipes
Recipes for serving Markdown.
Minimal working setups for the stacks developers actually use. Each recipe follows the same shape: request → match → respond → cache.
Web servers
Reverse proxies and static file servers.
- NginxServe Markdown from the same URL as HTML using Nginx's
map+try_files. - CaddyCaddy's named matchers make content negotiation concise. Serve pre-rendered
.mdfiles to AI agents and HTML to browsers from the same URL. - ApacheServe prebuilt Markdown and HTML from the same canonical URL in Apache using rewrite + proxy fallback for strict
Accepthandling.
Node.js
JavaScript meta-frameworks and edge runtimes.
- Cloudflare WorkersStatic site on Workers Assets with a thin negotiation Worker — proper
q-values,Vary: Accept,406, andLink: rel="alternate". Bring your own Markdown build step. - Next.jsMiddleware-driven negotiation for Next.js App Router, with proper
Acceptparsing,Vary,406, and deploy-target notes for Vercel, Cloudflare, and self-hosted Node. - AstroMiddleware-driven negotiation for Astro, with adapter-specific notes for Cloudflare, Vercel, and Node.
- SvelteKitUse a SvelteKit
handlehook forAcceptnegotiation and serve Markdown from route endpoints withVary: Accept,406, andLink: rel="alternate". - Nuxt / NitroImplement strict
Acceptnegotiation in Nitro server middleware and serve Markdown from API routes withVary: Accept,406, andLink: rel="alternate". - ExpressA plain Express middleware + route pattern for strict
Acceptnegotiation with Markdown siblings,Vary: Accept,406, andLink: rel="alternate".
PHP, Ruby, Python, Go
Traditional backend frameworks and stdlib HTTP servers.
- WordPressThe Roots post-content-to-markdown plugin serves post content as Markdown when requested via the
Acceptheader, with properVary,406, and q-value handling. - DiscourseThe Roots discourse-to-markdown plugin serves topics, categories, tags, and topic lists as Markdown when requested via the
Acceptheader, with properVary,406, and q-value handling. - LaravelThree approaches — Markdown-as-source, HTML-in-database, or middleware that converts rendered Blade/Livewire output to Markdown on request.
- RailsRails ships a
text/markdownMIME type, amarkdown:renderer, and autoVary: Accept. Defineto_markdownon your model andrespond_tothe:mdformat. - GoStdlib
net/httpmiddleware that parses Accept (q-values, RFC 9110 specificity), serves Markdown siblings, sets Vary, returns 406, and advertises the alternate via Link. - DjangoAdd negotiation middleware in Django and return Markdown or HTML from the same view with proper
Vary: Acceptand406semantics.