minidoc

Stop writing documentation in Markdown. Write it once, render it beautifully.

A compact DSL that compiles to polished, self-contained HTML — with charts, diagrams, tabs, metrics, and syntax highlighting. Write the same amount, get dramatically more.

The problem with Markdown documentation

Markdown is everywhere — READMEs, wikis, design docs, postmortems. It's easy to write, but hard to read at scale. By the time a document has tables, code blocks, and a system diagram, it's a wall of symbols that no one wants to open.

minidoc was built to fix that. Write a compact DSL (or have an LLM write it), get back a self-contained HTML file with real charts, interactive tabs, Mermaid diagrams, and a clean visual layout. The kind of document people actually open.

Real benchmark: URL shortener system design

We compiled the same system design document in both Markdown and minidoc DSL and measured the result.

	Markdown	minidoc DSL
Input tokens to write	3908	4598 (~same effort)
Charts	❌ not supported	✅ Chart.js
Architecture diagrams	❌ not supported	✅ Mermaid
Tabs / accordions	❌ not supported	✅ built-in
KPI / metric cards	❌ not supported	✅ built-in
Syntax highlighting	renderer-dependent	✅ highlight.js
Shareable without tools	❌	✅ any browser
Compiled output size	flat text	13394 tokens of rendered HTML

💡

Same effort. Dramatically better output.

You write roughly the same amount. minidoc compiles it into something Markdown never could.

Live examples

URL Shortener — System Design

Senior-level distributed system design: 100M writes/day · 10B redirects/day · 99.99% availability. Architecture diagram, data model, scalability strategy, and design decisions — all in one page.

ℹ️ → Open live example

Quick start

Install

pip install minidoc-dsl

Compile

minidoc report.minidoc -o report.html

Python API

from minidoc import compile_to_html

html = compile_to_html(dsl_string)

MCP server — for Claude and LLM agents

Add to your .mcp.json — no cloning, no setup, no venv:

.mcp.json

{
"mcpServers": {
"minidoc": {
"type": "stdio",
"command": "uvx",
"args": ["minidoc-mcp"]
}
}
}

Tool	Description
render_and_open(dsl)	Compile DSL → HTML, save, open in browser
render_minidoc(dsl)	Compile DSL → HTML, return file path
minidoc_guide prompt	Load full DSL reference into model context

Frontend stack

Layer	Library
CSS	Pico CSS v2 — classless, CSS-variable theming
Charts	Chart.js
Diagrams	Mermaid.js v11
Syntax highlight	highlight.js — github-dark theme

✅ All libraries loaded from CDN. Compiled HTML is fully self-contained — open in any browser, share as an attachment.