servemd

Serve docs to humans and AI.

Beautiful markdown documentation with native llms.txt support. Zero configuration, production-ready.

---

Why servemd?

Unlike basic markdown servers, servemd is built for the AI era:

Markdown → Beautiful HTML    → Humans
         → llms.txt          → AI/LLMs
         → llms-full.txt     → Complete AI context
         → /mcp endpoint     → AI assistants (250x less context)

For humans: Nuxt UI-inspired design, three-column layout, zero configuration. For AI: Native llms.txt support, structured context, ready for the Model Context Protocol era.

---

✨ Features

• 🎨 Beautiful Design — Nuxt UI-inspired three-column layout (sidebar, content, TOC)
• 🤖 AI-Native — Built-in llms.txt and llms-full.txt for Claude, ChatGPT, Cursor, etc.
• 🔌 MCP Support — Model Context Protocol endpoint for interactive AI queries (250x less context)
• ✨ Zero Configuration — Drop .md files and go
• ⚡ Fast — Smart disk caching, <5ms cached responses
• 🐳 Docker Ready — Production-optimized container
• 🧪 Well Tested — 208 tests, 100% passing
• 📱 Responsive — Mobile, tablet, and desktop support

---

🚀 Quick Start

Install

pip install servemd

Run

# Serve docs from current directory
servemd

# Or specify a directory
servemd ./my-docs

Visit http://localhost:8080 — your documentation is live.

Live demo: https://servemd.me.cloudns.cl

Alternative: Docker

# Quick start - mount your docs
docker run -p 8080:8080 -v $(pwd)/docs:/app/__docs__ jberends/servemd:latest

# Or build custom image with docs baked in
FROM jberends/servemd:latest
COPY ./my-docs/ /app/__docs__/

See DOCKER_README.md for complete Docker usage guide.

Alternative: uvx (no install)

uvx servemd ./my-docs

📚 Complete Setup Guide →

For Contributors

git clone https://github.com/servemd/servemd
cd servemd
uv sync
uv run python -m docs_server

---

🤖 AI-Native: llms.txt & MCP Support

servemd automatically serves your docs in AI-friendly formats:

Endpoint	Purpose	Audience	Context Size
/{page}.html	Rendered HTML with navigation	Humans	N/A
/{page}.md	Raw markdown	AI/LLMs	Per-page
/llms.txt	Documentation index	AI assistants	Small (~5KB)
/llms-full.txt	Complete context (all pages)	AI deep context	Large (~500KB+)
/mcp	Interactive queries	AI (MCP clients)	Minimal (250x less)

llms.txt - Static Index

Example: Give an AI assistant your docs:

"Read my documentation at https://docs.example.com/llms.txt"

The AI gets a structured index with absolute URLs to every page. For complete context, use /llms-full.txt which includes all page content inline.

MCP - Interactive Queries (Recommended for AI)

Model Context Protocol provides on-demand documentation access with 250x less context:

POST /mcp
{
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "query": "authentication",
      "limit": 5
    }
  }
}

Benefits:

• 🎯 Precise — AI queries only what it needs
• ⚡ Fast — No sending entire documentation every time
• 💰 Cost-effective — 250x less tokens than llms-full.txt
• 🔍 Smart — Full-text search with Whoosh

Available MCP Tools:

• search_docs — Semantic search across documentation
• get_doc_page — Retrieve specific pages with section filtering
• list_doc_pages — List all available pages by category

See MCP Integration Guide for details.

---

✨ Key Features

For Humans

• 🎨 Nuxt UI-inspired three-column layout (sidebar, content, TOC)
• 🎨 Syntax highlighting with Pygments
• 🎨 Responsive design (mobile, tablet, desktop)
• 🎨 Dark mode ready
• ✅ Tables, task lists, footnotes, Mermaid diagrams

For AI

• 🤖 llms.txt — Structured documentation index (5KB)
• 🤖 llms-full.txt — Complete context export (500KB+)
• 🔌 MCP endpoint — Interactive queries via Model Context Protocol
  • 250x less context than llms-full.txt
  • Full-text search with Whoosh
  • On-demand page retrieval
  • Section filtering
• 🤖 Automatic link transformation to absolute URLs
• 🤖 Curated or auto-generated indexes

For Developers

• ⚡ Fast — disk caching, <5ms cached responses
• 🔥 Hot reload in debug mode
• 🔧 Zero configuration required
• 🐍 Python 3.11-3.14, FastAPI, Pydantic
• 🧪 208 tests, 100% passing

---

📁 File Structure

Your documentation needs just 3 required files:

docs/
├── index.md       # Homepage (required)
├── sidebar.md     # Navigation (required)
├── topbar.md      # Top bar (required)
├── llms.txt       # AI index (optional)
└── your-content.md # Your pages

---

⚙️ Configuration

Configure via environment variables:

DOCS_ROOT=./docs                 # Documentation directory
CACHE_ROOT=./__cache__           # Cache directory
PORT=8080                        # Server port
DEBUG=true                       # Enable debug mode
BASE_URL=https://docs.site.com   # Base URL for llms.txt
MCP_ENABLED=true                 # Enable MCP endpoint (default: true)
MCP_RATE_LIMIT_REQUESTS=120      # MCP rate limit (requests per window)
MCP_RATE_LIMIT_WINDOW=60         # MCP rate limit window (seconds)

See Configuration Guide for details.

---

🎯 Use Cases

servemd is perfect for:

• SaaS Documentation — Customer-facing support docs with AI assistant integration
• Open Source Projects — Self-hosted, beautiful docs
• Internal Teams — Company knowledge bases and wikis
• API Documentation — REST/GraphQL API docs
• Technical Writing — Blogs and tutorials

📘 Deployment

Method	Best For
Local Development	Development, previewing
Docker	Production, CI/CD
Cloud Platforms	Heroku, Railway, Fly.io, DigitalOcean
Kubernetes	k8s, k3s, Helm charts

🛠️ Examples

Check examples/ for ready-to-use templates:

• Dockerfile.user-template — Custom Docker image
• docker-compose.user.yml — Docker Compose setup
• k8s-simple.yaml — Kubernetes deployment

---

🏗️ Architecture

Clean, modular FastAPI application:

src/docs_server/
├── config.py           # Settings & environment
├── helpers.py          # Utilities & navigation
├── caching.py          # Smart caching
├── markdown_service.py # Markdown rendering
├── llms_service.py     # LLMs.txt generation
├── templates.py        # HTML templates
├── main.py             # FastAPI routes
└── mcp/                # Model Context Protocol
    ├── server.py       # MCP JSON-RPC handler
    ├── tools.py        # MCP tools (search, get, list)
    ├── search.py       # Full-text search with Whoosh
    └── indexer.py      # Documentation indexing

---

🧪 Testing

uv run pytest tests/ -v

# 208 tests, 100% passing ✅

---

🔧 Development

git clone https://github.com/servemd/servemd
cd servemd
uv sync --group dev
uv run pytest tests/ -v
DEBUG=true uv run python -m docs_server

---

📊 Performance

Endpoint	First Request	Cached
Rendered HTML	50-100ms	<5ms
Raw Markdown	<10ms	<10ms
LLMs.txt	100-200ms	<5ms

---

📖 Documentation

• Quick Setup — Get running in 5 minutes
• Markdown Features — Tables, code blocks, diagrams
• LLMs.txt Guide — AI assistant integration
• MCP Integration — Interactive queries for LLMs
• Navigation — Sidebar and topbar configuration
• Configuration — Environment variables
• API Reference — HTTP endpoints

---

🙋 Support

• 📖 Documentation: docs.servemd.dev or run locally
• 🚀 Live demo: servemd.me.cloudns.cl
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

📜 License

MIT License — use freely for any project.

---

🎉 Get Started Now

pip install servemd
servemd ./my-docs

Visit http://localhost:8080 — beautiful docs for humans, structured context for AI.

---

servemd — Serve docs to humans and AI

Built with Python, FastAPI, and Markdown

Documentation · Live Demo · PyPI · GitHub