package
Markdown for the web. HTML for humans, Markdown for agents.
npm install mkdnsiteGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
"markdown site" — a Markdown-first web server
Your Markdown is your website. No build required.
Docs · Hosted Service · GitHub · npm · Docker
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.
# Install
bun add -g mkdnsite # or: npm i -g mkdnsite
# Serve any directory of .md files
mkdnsite ./docs
# That's it. Open http://localhost:3000# For humans → beautiful HTML
curl http://localhost:3000
# For AI agents → raw Markdown
curl -H "Accept: text/markdown" http://localhost:3000
# Content index for LLMs
curl http://localhost:3000/llms.txtThe 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.
--github owner/repo.Rendering & Content
Accept: text/markdown returns raw Markdown, text/html returns rendered pages[!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]Theming & Design
AI & Interoperability
/llms.txt — AI agents discover and index your contentx-markdown-tokens header — Cloudflare-compatible token countContent-Signal header — AI training and indexing consent signalsInfrastructure
mkdnsite.config.ts and as a CLI flagbun add -g mkdnsite # Bun (recommended)
npm i -g mkdnsite # requires Node 22+No JavaScript runtime installed? No problem:
docker run -v ./docs:/content -p 3000:3000 nexdrew/mkdnsite (Docker Hub)mkdnsite ./my-docsAny directory of .md files works. mkdnsite builds navigation from the file structure, renders pages on request, and serves static assets.
mkdnsite --github owner/repo
mkdnsite --github owner/repo --github-path docsServe content directly from a public GitHub repository — no clone needed.
Also works on Deno:
deno run --allow-read --allow-net src/cli.ts ./my-docsCreate mkdnsite.config.ts for full control:
import type { MkdnSiteConfig } from 'mkdnsite'
export default {
contentDir: './docs',
staticDir: './static',
site: {
title: 'My Documentation',
description: 'Docs for my project.',
url: 'https://docs.example.com'
},
theme: {
colorScheme: 'system',
logo: { src: '/logo.svg', alt: 'My Project' },
logoText: 'My Project',
showNav: true,
showToc: true,
prevNext: true
},
client: {
themeToggle: true,
Or use CLI flags — every config option has a corresponding flag:
mkdnsite ./docs --port 8080 --title "My Docs"
mkdnsite ./docs --color-scheme dark --no-theme-toggle
mkdnsite ./docs --logo /logo.png --logo-text "My Project"
mkdnsite ./docs --no-math --no-mermaid --no-searchSee the full configuration reference for all options.
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 →
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 |
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 API
Bun.serve({ fetch: handler, port: 3000 })Contributions are welcome! See open issues for the roadmap and current priorities.
Estimated unpacked size across 65 packages.
75.9 MB+
Includes dependencies.
^4.0.3
4.0.3
^6.0.0
6.0.0
^6.0.0
6.0.0
^0.577.0
1.73.0
^7.0.1
7.0.1
^9.0.0
10.1.0
^6.0.0
6.0.0
^4.0.2
4.0.3
^1.27.1
1.32.2
2.1.0