minidoc-dsl 0.1.3

Stop writing docs in Markdown. Write compact DSL, get polished HTML with charts, diagrams, and more.

minidoc

A compact DSL for LLMs to generate readable, shareable HTML documents.

LLMs already generate reports, dashboards, and design docs — but Markdown has limited expressiveness (no charts, no diagrams, no tabs), and raw HTML costs too many tokens to generate reliably. minidoc gives your LLM a better option: a constrained DSL that compiles to polished, self-contained HTML with charts, diagrams, and interactive layout — ready to share with anyone, no tools required.

English · 中文

Example	Audience	Markdown	minidoc DSL	Live HTML
URL Shortener — System Design	Engineering	.md 3,908 tokens	.minidoc 4,598 tokens	→ Open 13,432 tokens
Q3 Business Review	Executive	.md 868 tokens	.minidoc 1,060 tokens	→ Open 5,526 tokens
Incident Postmortem	DevOps	.md 958 tokens	.minidoc 1,065 tokens	→ Open 3,553 tokens
Sales Pipeline Dashboard	Sales	.md 891 tokens	.minidoc 1,182 tokens	→ Open 4,596 tokens
ML Experiment Log	Data Science	.md 1,158 tokens	.minidoc 1,456 tokens	→ Open 5,187 tokens

---

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.

	LLM → Markdown	LLM → Raw HTML	LLM → minidoc DSL
Token cost	3,908	~13,000+	4,598
LLM reliability	High	Low — CSS/JS errors	High — constrained syntax
Charts & diagrams	❌	✅ fragile	✅ declarative
Tabs / accordions	❌	✅ fragile	✅ built-in
KPI / metric cards	❌	✅ fragile	✅ built-in
Shareable without tools	❌ needs renderer	✅	✅
Compiled output	flat text	~13,000 tokens	13,394 tokens

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:

Tool	Description
render_and_open(dsl, output_path?)	Compile DSL, save to path, open in browser
render_minidoc(dsl, output_path?)	Compile DSL, save to path, return file path

Available prompts:

Prompt	Description
minidoc_guide	Loads the full DSL reference into the model context

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.

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

---

License

MIT