mkdnsite serves a directory of Markdown files as a fully styled website — instantly, with no content build pipeline. The same URL delivers rendered HTML to browsers and raw Markdown to AI agents, using standard HTTP content negotiation.
One source. Two audiences. Zero build steps.
# Installbun add -g mkdnsite # or: npm i -g mkdnsite# Serve any directory of .md filesmkdnsite ./docs# That's it. Open http://localhost:3000
# For humans → beautiful HTMLcurl http://localhost:3000# For AI agents → raw Markdowncurl -H "Accept: text/markdown" http://localhost:3000# Content index for LLMscurl http://localhost:3000/llms.txt
Why mkdnsite?
The web has a Markdown problem. Everyone writes in Markdown — docs, blogs, READMEs, notes — but to put it on the web, you feed it through a static site generator, wait for a build, and ship HTML. Then when AI agents come along, services like Cloudflare and Vercel convert that HTML back into Markdown.
That's a round trip that shouldn't exist.
Traditional: Markdown → build step → HTML → reverse-convert → Markdown (for AI)mkdnsite: Markdown → serve it.
mkdnsite skips the content build pipeline. Your .md files are served directly — rendered as HTML for browsers, delivered as raw Markdown for agents. No static site generation. No build artifacts. No HTML-to-Markdown reconversion.
Traditional SSGs earn their complexity through build-time optimizations — image processing, bundling, prefetching. mkdnsite trades that for radical simplicity and native AI agent support. If your content is Markdown and your audience includes both humans and machines, you don't need a build step in between.
What this means in practice
Edit a file, refresh the page. Not just in dev — in production too. No rebuild, no redeploy.
AI agents get your original Markdown, not HTML converted back to Markdown.
Your content stays portable. Markdown files in a directory. Move them anywhere.
Serve from GitHub. Point mkdnsite at any public or private repo with --github owner/repo.
Features
Rendering & Content
🚀 Zero build step — runtime Markdown → HTML via React SSR
Don't want to self-host? mkdn.io runs mkdnsite for you — connect your GitHub repos, get a live site with custom domains, analytics, and zero infrastructure.
GitHub Pages
mkdn.io
Content pipeline
Jekyll build or Actions
No build — serves Markdown directly
AI agent support
Manual setup
Built-in content negotiation + MCP
Content format
Builds and ships HTML
Serves Markdown, renders HTML
LLMs.txt
Manual
Auto-generated
Theme ecosystem
Thousands of Jekyll themes
Config-based theming (growing)
Maturity
Battle-tested since 2008
New project
mkdn.io is best for documentation sites and blogs where AI agent access and simplicity matter more than deep theme customization. Get started free →
Content Negotiation
mkdnsite implements the same content negotiation standard used by Cloudflare and Vercel — but in the opposite direction. Instead of converting HTML to Markdown for AI, mkdnsite starts with Markdown and renders HTML for humans.
Client
What it sends
What it gets
Browser
Accept: text/html
Rendered HTML page
Claude Code
Accept: text/markdown
Raw Markdown
Cursor
Accept: text/markdown
Raw Markdown
Any URL + .md suffix
—
Raw Markdown
/llms.txt
—
AI content index
/mcp
—
MCP server endpoint
Programmatic API
Use mkdnsite as a library in any JavaScript runtime:
import { createHandler, resolveConfig, FilesystemSource, createRenderer} from 'mkdnsite'const config = resolveConfig({ site: { title: 'My Site' }})const source = new FilesystemSource('./content')const renderer = await createRenderer('portable')const handler = createHandler({ source, renderer, config })// Works with any platform's serve APIBun.serve({ fetch: handler, port: 3000 })
Contributing
Contributions are welcome! See open issues for the roadmap and current priorities.