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.

pip install minidoc-dsl Python 3.11+ MIT License MCP Ready

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

Example	Audience	Markdown	minidoc DSL	Rendered HTML
URL Shortener — System Design Architecture · Data model · Scalability	Engineering	.md	.minidoc	Open →
Q3 Business Review Revenue · Growth · Product · Forecast	Executive	.md	.minidoc	Open →
Incident Postmortem Timeline · Root cause · Action items	DevOps	.md	.minidoc	Open →
Sales Pipeline Dashboard Pipeline · Forecast · Rep performance	Sales	.md	.minidoc	Open →
E-commerce Real-Time Reporting Kafka · Flink · Spark · Data quality · ML features	Data Engineering	.md	.minidoc	Open →
ML Experiment Log Model comparison · Features · Deployment	Data Science	.md	.minidoc	Open →

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.