Why minidoc

When you ask an LLM to produce a report, it has three options:

Option 1 — Generate Markdown. Easy for the LLM, but Markdown has limited expressiveness — charts, diagrams, tabs, and metric cards simply can't be represented. Everything degrades to tables and plain text. Hard to share with non-technical stakeholders.

Option 2 — Generate raw HTML. The output looks good, but it costs 3× more tokens, and LLMs make frequent mistakes — unclosed tags, broken CSS units, broken JavaScript. Output quality varies every run.

Option 3 — Generate minidoc DSL. Same token cost as Markdown. The compiler handles all the HTML, CSS, and JS. Output is a polished, self-contained HTML file the reader can open in any browser — or forward as an email attachment.

Real numbers: URL shortener system design

We wrote the same system design document in both Markdown and minidoc DSL and measured the difference.

minidoc costs about the same as Markdown to generate, but produces an HTML document as rich as raw HTML — without the token waste or the reliability problems.

Benchmark source: showcase/ — measured with tiktoken (cl100k_base).

Quick start

pip install minidoc-dsl
# or
uv add minidoc-dsl

Create report.minidoc:

@doc title="Q3 Report" theme=light

# Q3 Business Review

[columns]
[col][metric label="MRR" value="$48K" trend=+12% color=green][/col]
[col][metric label="Churn" value="2.1%" trend=-0.4% color=blue][/col]
[col][metric label="NPS" value="61" trend=+8 color=purple][/col]
[/columns]

[chart type=bar title="Monthly Revenue"
  Jan=38 Feb=41 Mar=44 Apr=46 May=48
]

[table cols="Initiative,Owner,Status"
  Mobile redesign | Design team | ✅ Done
  API v2          | Backend     | 🔄 In progress
  SOC 2           | Security    | 📋 Planned
]

Compile:

minidoc report.minidoc -o report.html

Open report.html in any browser. No internet required after compile.

Features

• Token-efficient — the entire DSL reference fits in a single system prompt
• LLM-reliable — constrained syntax means fewer hallucinations and malformed output
• Zero runtime — compiled HTML is fully self-contained; share it as an email attachment or static file
• Rich component library — metrics, KPIs, charts, tables, diagrams, code blocks, timelines, tabs, accordions
• MCP server — native integration with Claude and any MCP-compatible agent
• Dark mode — theme=dark via Pico CSS CSS variables
• Mermaid diagrams — flowchart, sequence, ER, Gantt — all declarative
• Syntax highlighting — 100+ languages via highlight.js

Usage

CLI

# Compile a file
minidoc report.minidoc -o output.html

# Read from stdin
echo '@doc title="Hello" theme=light
# Hello World' | minidoc -o hello.html

Python API

from minidoc import compile_to_html

dsl = """
@doc title="My Report" theme=light
# Hello
[metric label="Users" value="1,240" color=blue]
"""

html = compile_to_html(dsl)
with open("report.html", "w") as f:
    f.write(html)

MCP server (for Claude and LLM agents)

Add to .mcp.json (or Claude Code settings):

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

Available tools:

Available prompts:

Recommended workflow in Claude:

1. Start with the minidoc_guide prompt to load the DSL reference
2. Ask Claude to generate a report
3. Claude calls render_and_open — the result opens in your browser instantly

DSL reference

Document header

@doc title="Title" theme=light

theme: light (default) · dark

Text

# H1  /  ## H2  /  ### H3
> blockquote
paragraph text with **bold**, *italic*, `code`, [link](url)
[divider]

Metrics

[metric label="ARR" value="$4.8M" trend=+18% color=green]
[kpi label="ARR" value="$4.8M" target="$5.0M" trend=+18% color=green]
[progress label="Q3 Goal" value=72 color=green target="$2.2M"]
[badge text="On Track" color=green]

Data

[table cols="Name,Stage,Value"
  Acme   | Negotiation | $120k
  Globex | Proposal    | $85k
]

[chart type=bar title="Revenue"
  Jan=40 Feb=55 Mar=72
]

Content blocks

[alert type=info text="Message here."]
[callout icon=💡 title="Insight" text="Detail here." color=blue]

[code lang=python title="app.py"
def hello():
    return "world"
]

[diagram
flowchart TD
    A[Client] --> B[API] --> C[(Database)]
]

[image src="https://..." alt="..." caption="Figure 1" width=800]

Layout

[columns]
[col][metric label="MRR" value="$700K"][/col]
[col][metric label="NRR" value="118%"][/col]
[/columns]

[section title="Title" style=card]
content here
[/section]

[tabs]
[tab title="Overview"] ... [/tab]
[tab title="Details"]  ... [/tab]
[/tabs]

[accordion title="Show more"] ... [/accordion]

Lists & timelines

[list style=check]
- Shipped feature A
- Fixed bug B
[/list]

[timeline color=blue]
- Q1: Launched MVP — 500 users
- Q2: Series A closed — $4M
[/timeline]

Colors: green red blue yellow purple gray
Alert types: info warning error success
Chart types: bar line pie doughnut
Code languages: python javascript typescript sql bash json yaml go rust
List styles: bullet numbered check

Frontend stack

Compiled HTML files load all dependencies from CDN — no bundler, no build step, no Node.js.

License

MIT