Diagram-as-code DSL for animated architecture & system design explainers.
Prompt your AI agent → generate declarative MarkdyScript → render 60fps kinetic diagrams powered by the Web Animations API.
⚡ Live Studio •
🔌 VS Code Extension •
📖 Documentation •
🌟 33 Blueprints •
🤖 AI & Agent Guide
---
## 💡 How It Works
> **Describe your system in plain English → your AI agent generates the Markdy script → your browser renders the animated diagram.**
---
## 🚀 Quick Start (60 Seconds)
### 1. Prompt Your AI Agent
You don't need to write MarkdyScript manually. Ask **Cursor**, **Claude Code**, **Google Antigravity**, **ChatGPT**, or any coding agent:
💬 Example Prompt (Copy & Paste to your Agent)
> "Follow the canonical Markdy specification (https://markdy.com/AGENT.md) and generate a `.markdy` scene:
> Explain a **Cache-Aside Architecture** with a Web Client, API Gateway, URL Service, Redis Cluster, and PostgreSQL database. Include two animated storyboard beats: **1. Cache Hit Path** and **2. Cache Miss & Async Warm**."
*(Tip: If you have the official [Markdy MCP Server](#mcp-setup) installed, just ask: `"Create an animated Markdy architecture diagram for our cache-aside service."`)*
🤖 AI-Generated MarkdyScript (system.markdy)
```markdy
scene "Cache-Aside Architecture" theme=auto
layout LR
browser Client "Web Client"
gateway Gateway "API Gateway"
service Svc "URL Service"
cache Redis "Redis Cluster"
database Postgres "PostgreSQL 16"
beat cache_hit "1. Cache Hit Path":
show $nodes stagger=60ms
frame Client Gateway Svc Redis zoom=1.12
Client -> Gateway "GET /link" -> Svc "resolve"
Svc -> Redis "GET key:link"
Svc <- Redis "200 Target URL"
Client <- Gateway "301 Redirect"
beat cache_miss "2. Cache Miss & Async Warm":
frame Svc Redis Postgres zoom=1.15
Svc -> Postgres "SELECT destination WHERE key = 'link'"
Svc <- Postgres "Row Found"
Svc ~> Redis "SETEX key:link (Warm Cache)"
glow Postgres color=#38bdf8 & glow Redis color=#22c55e
```
### 2. Preview & Explore
Choose your preferred preview environment:
- **Interactive Web Studio**: **[markdy.com/playground ↗](https://markdy.com/playground/)**:
Instant browser playground with timeline scrubbing, GIF/SVG export, and shareable links.
- **VS Code / Cursor Extension**: [`hoangyell.markdy-vscode`](https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode):
Press **`Cmd+K V`** *(macOS)* or **`Ctrl+K V`** *(Windows/Linux)* for live side-by-side animated preview.
- **Terminal CLI**: [`@markdy/cli`](packages/cli/README.md):
```bash
npx @markdy/cli render system.markdy --out diagram.html
```
### 3. Embed in Web Apps & Docs
Choose the package that fits your stack:
- **Web Apps (Vanilla JS, React, Vue, Svelte)**: [`@markdy/renderer-dom`](packages/renderer-dom/README.md):
```bash
npm install @markdy/renderer-dom
```
```ts
import { createDiagram } from "@markdy/renderer-dom";
// Mount and render interactive 60fps WAAPI diagram directly from code
const diagram = createDiagram({
container: document.getElementById("diagram-container")!,
code: markdyScriptCode,
});
```
- **Astro Sites & Blogs**: [`@markdy/astro`](packages/astro/README.md):
```bash
npm install @markdy/astro
```
*(Zero-CLS SSR island: `` - see [Astro Guide ↓](#astro-integration))*
- **Next.js / MDX Docs**: [`@markdy/mdx`](packages/mdx/README.md):
```bash
npm install @markdy/mdx
```
*(Auto-renders fenced ```` ```markdy ```` blocks - see [MDX Guide ↓](#mdx-integration))*
👉 **[DOM Renderer Guide ↗](packages/renderer-dom/README.md)** • **[Astro Guide ↗](packages/astro/README.md)** • **[MDX Guide ↗](packages/mdx/README.md)** • **[Core Compiler ↗](packages/core/README.md)**
---
## ⚡ Why Markdy?
Kinetic Motion Graphics vs. Static Architecture Diagrams
Static boxes and arrows fail to capture distributed systems in action. **Markdy turns text into choreographed 60fps motion graphics** directly in your browser.
- 🎬 **Kinetic Storytelling**: Choreograph requests (`->`), responses (`<-`), and events (`~>`) across sequential `beat` timelines with auto-zooms and glow cues.
- 📐 **Dynamic Port Multiplexing**: Automatically balances parallel connections across node boundaries with zero line congestion or overlapping paths.
- 🔗 **Code Provenance & Git Grounding**: Anchor high-level architecture nodes directly to verified source code (`@src="src/auth.ts#L10-L50"`) with automated in-tree Git verification.
- 🔄 **Architectural Evolution Matrix**: Compare architecture states across Git commits and automatically synthesize animated migration storyboards (`markdy diff`).
- 🏛️ **C4 Hierarchy & Architecture Drift**: Native Context, Container, Component, and Code level projections (`markdy c4`) with automatic drift detection (`markdy drift`).
- 🔬 **Blast Radius & Route Pathfinder**: Compute upstream dependency callers, downstream failure blast radius, and shortest message paths in real-time.
- 💎 **Native Vector Symbol Registry**: Embedded, zero-dependency SVG vector glyphs for AWS, GCP, Kubernetes, Docker, Postgres, Redis, Kafka, Grafana, and 20+ stacks.
- ⚡ **Zero-Dep & Web-Native**: Powered by pure CSS/SVG transforms and the Web Animations API (WAAPI): ~14 kB parser, no Canvas, no GSAP.
- 🔄 **Universal Ingestion**: 1-click migration from Mermaid, D2, PlantUML, Draw.io, Docker Compose, Kubernetes manifests, and Terraform states.
- 🤖 **AI-Native & MCP**: Official Model Context Protocol (MCP) server for Claude, Cursor, Antigravity, and Cline with self-healing syntax diagnostics.
- 🛡️ **Architecture Governance**: Built-in rules prevent deadlock cycles and cross-layer bypasses.
---
## 🌟 Advanced Engineering Superpowers
Architecture Intelligence Platform (Code Provenance, C4, Drift, Blast Radius)
Markdy goes beyond basic diagram drawing into a comprehensive **Architecture Intelligence Platform**:
```markdy
scene "Cloud Native Microservices Mesh" theme=paper
layout LR
gateway ApiGateway "API Gateway" icon=nginx @src="src/gateway/router.ts#L20"
service OrderSvc "Order Service" icon=nodejs @src="src/orders/service.ts#L45"
service UserSvc "User Service" icon=golang @src="src/users/handler.go#L30"
cache Redis "Redis Cluster" icon=redis
database Postgres "PostgreSQL 16" icon=postgresql
beat workflow:
show $nodes stagger=60ms
ApiGateway -> OrderSvc "POST /orders" & ApiGateway -> UserSvc "GET /profile"
OrderSvc -> Postgres "Write Order" & UserSvc -> Postgres "Read User"
OrderSvc ~> Redis "Cache Invalidation"
```
| Superpower | Syntax / API / CLI | Developer Impact |
| :--- | :--- | :--- |
| **Dynamic Port Multiplexing** | Auto-calculated | Perfectly balanced multi-lane fan-in/fan-out with smooth fillet curves |
| **Code Provenance Anchors** | `@src="path/file.ts#L10"` | Guaranteed synchronization between architecture diagrams and real Git code |
| **Evolution Git-Diff** | `diffDiagramASTs(v1, v2)` / `markdy diff` | Automated visual diffing and animated migration timeline generation |
| **Architecture Drift Detection** | `detectArchitectureDrift()` / `markdy drift` | Detect broken `@src` anchors and orphan microservices against Git history |
| **C4 Hierarchy Modeling** | `analyzeC4Model()` / `markdy c4` | Native Context, Container, Component, and Code level views and transitions |
| **Blast Radius Lens** | `calculateBlastRadius(node, ast)` | Real-time upstream impact and downstream failure cascade isolation |
| **Contextual Share Cards (1200×630)** | `exportRouteShareCard()`, `exportReachShareCard()` | High-impact social and README cards with active route/blast-radius telemetry |
| **9-Point Showcase Quality Gate** | `markdy verify --quality showcase` | Deterministic SHA-256 integrity receipt and responsive viewport validation |
| **Architecture Recipe Guidance** | `markdy guide ""` / `markdy recipe` | Instant AI scenario pattern matching for cache-aside, EDA, zero-trust, and lakehouse |
| **Native Vector Symbols** | `icon=redis`, `icon=kafka`, `icon=grafana` | Zero-CDN, lightweight vector badges embedded directly in the artifact |
---
## 🔌 Integrations & Ecosystem
Extend Markdy across your favorite AI agents, editors, frameworks, and deployment workflows:
🤖 AI Coding Agents & MCP Server (Recommended)
Equip Claude, Cursor, Antigravity, VS Code, Cline, Windsurf, or Zed with self-healing syntax diagnostics, auto-repair, and transpilers:
```bash
# Claude Code / CLI
claude mcp add markdy -- npx -y @markdy/mcp-server
# Google Antigravity & Gemini CLI
agy mcp add markdy -- npx -y @markdy/mcp-server
```
👉 **[1-Click Install for Cursor ↗](https://markdy.com/mcp/cursor)** • **[1-Click Install for VS Code ↗](https://markdy.com/mcp/vscode)** • **[Full JSON Configs for 6 IDEs ↓](#mcp-setup)** • **[AI Agent Guide (`AGENT.md`) ↗](AGENT.md)**
🔌 IDE Extensions (VS Code, Cursor, Windsurf, VSCodium)
Live side-by-side animated preview (`Cmd+K V`), syntax highlighting, auto-completion, error squiggles, and SVG/PNG export:
```bash
# Visual Studio Code
code --install-extension hoangyell.markdy-vscode
# Cursor / VSCodium (Open VSX Registry)
cursor --install-extension hoangyell.markdy-vscode
```
👉 **[VS Code Marketplace ↗](https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode)** • **[Open VSX Registry ↗](https://open-vsx.org/extension/hoangyell/markdy-vscode)** • **[Extension Docs ↗](packages/vscode/README.md)**
🚀 Astro Integration (`@markdy/astro`)
Zero-CLS, SSR-placeholder islands with viewport-triggered lazy hydration for Astro documentation sites and blogs:
```bash
pnpm add @markdy/astro
```
```astro
---
import { Markdy } from "@markdy/astro";
import code from "./diagram.markdy?raw";
---
```
👉 **[@markdy/astro Package Guide ↗](packages/astro/README.md)**
📝 MDX / React / Next.js Integration (`@markdy/mdx`)
Render fenced ```markdy code blocks directly inside `.mdx` files with automatic lazy loading:
```bash
pnpm add @markdy/mdx react react-dom
```
```ts
// mdx.config.js
import { remarkMarkdy } from "@markdy/mdx";
export default {
remarkPlugins: [[remarkMarkdy, { componentName: "MarkdyDiagram" }]],
};
```
👉 **[@markdy/mdx Package Guide ↗](packages/mdx/README.md)**
⚡ Terminal CLI & CI/CD (`@markdy/cli`, `@markdy/compat`)
Render standalone HTML diagrams, verify showcase quality, or run architecture linting in CI/CD pipelines:
```bash
# Global install
npm install -g @markdy/cli
# Render diagram to animated HTML or SVG
markdy render system.markdy --out diagram.html
# Lint Markdy architecture scenes in CI/CD
markdy lint **/*.markdy
# Verify showcase blueprint quality gate
markdy verify system.markdy --quality showcase
# Detect architecture drift against Git source code
markdy drift system.markdy
# Model C4 multi-level architectural hierarchy
markdy c4 system.markdy --level container
# Transpile external diagrams (Mermaid, D2, PlantUML, Compose, K8s, Terraform, Draw.io)
markdy import flow.mmd --out flow.markdy
```
👉 **[CLI Package Guide ↗](packages/cli/README.md)** • **[Universal Ingestion Guide ↗](packages/compat/README.md)**
🏗️ Systems Vocabulary & Language Server (`@markdy/stdlib-systems`, `@markdy/language-server`)
- **[`@markdy/stdlib-systems`](packages/stdlib-systems/README.md)**: Standard library of semantic cloud and distributed systems node kinds.
- **[`@markdy/language-server`](packages/markdy-language-server/README.md)**: Headless LSP for custom editor integrations (Neovim, Helix, Emacs).
---
## 📊 Feature Comparison
Feature Matrix (vs Mermaid, PlantUML, D2, Excalidraw, Draw.io)
| Capability | Mermaid / PlantUML | Excalidraw / Draw.io | Markdy |
|---|---|---|---|
| **Animation & Timing** | ❌ Static SVG / PNG | ❌ Static canvas | ✅ **60fps WAAPI motion & step-by-step narrative beats** |
| **Authoring Style** | Text DSL | Manual drag-and-drop | ✅ **Declarative text DSL + Live Editor Preview** |
| **Return Flows & Cycles** | ⚠️ Rank distortion / tangling | Manual curve placement | ✅ **Cycle-safe returns (`<-`) & async event arcs (`~>`)** |
| **AI Agent Reliability** | ⚠️ High hallucination | ❌ Coordinate hallucination | ✅ **Strict grammar AST + Self-healing MCP Server** |
| **Architecture Governance** | ❌ None | ❌ None | ✅ **Built-in rules, drift detection (`markdy drift`), and C4 hierarchy** |
| **Universal Ingestion** | ❌ Manual rewrite | ❌ Manual export | ✅ **1-Click Transpiler for Mermaid, D2, PlantUML, Compose, K8s, Terraform, Draw.io** |
| **Core Footprint** | ~2 MB+ runtime | Heavy web app | ✅ **~14 kB core parser, zero dependencies** |
---
## 📦 Component Responsibilities & Packages
Monorepo Package Directory & Core Responsibilities
Markdy is architected as a modular monorepo where each package fulfills a focused responsibility:
| Package | Responsibility | Primary Exports |
|---|---|---|
| **[`@markdy/core`](packages/core)** | **Compiler Core & AST Engine** | `parse()`, `compile()`, `formatScene()`, `diagnoseMarkdyCode()`, `validateArchitecture()`, `detectArchitectureDrift()`, `analyzeC4Model()`. Zero dependencies (~14 kB). |
| **[`@markdy/renderer-dom`](packages/renderer-dom)** | **Motion Graphics & Rendering** | `createDiagram()`, `exportDiagramAsVectorSvg()`, `exportDiagramAsPng()`, `exportDiagramAsGif()`, `exportRouteShareCard()`. 60fps WAAPI timeline. |
| **[`markdy-vscode`](packages/vscode)** | **IDE Extension (VS Code & Cursor)** | Side-by-side live animated preview, document formatter (`Shift+Alt+F`), QuickFix lightbulbs (`💡 Fix`), Universal Ingestion, CodeLens. |
| **[`@markdy/compat`](packages/compat)** | **Universal Ingestion Suite** | Transpilers for Mermaid, D2, PlantUML, Docker Compose, Kubernetes YAMLs, Terraform state, and Draw.io XML. |
| **[`@markdy/cli`](packages/cli)** | **Terminal Tool & CI/CD** | `markdy lint`, `markdy render`, `markdy fmt`, `markdy import`, `markdy diff`, `markdy verify`, `markdy drift`, `markdy c4`, `markdy guide`. |
| **[`@markdy/mcp-server`](packages/mcp-server)** | **AI Agent Integration (MCP)** | Model Context Protocol server exposing validation, auto-healing, and transpilation tools for Claude, Cursor, Antigravity, Cline, Windsurf. |
| **[`@markdy/astro`](packages/astro)** & **[`@markdy/mdx`](packages/mdx)** | **Docs & Blog Integrations** | Zero-CLS, SSR-placeholder islands with viewport hydration for content sites. |
| **[`@markdy/language-server`](packages/markdy-language-server)** | **Headless LSP Server** | Diagnostic publishing, hover docs, formatting, and completions for language clients. |
| **[`@markdy/stdlib-systems`](packages/stdlib-systems)** | **Domain Vocabulary** | Semantic primitives for cloud, infrastructure, and distributed systems. |
---
## 🔍 Detailed Features & Advanced Usage
🎨 18 Specialized Layout Engines & 10 Editorial Themes
Markdy provides topological layout algorithms tailored to specific system patterns:
- **Distributed Systems**: `architecture`, `flowchart`, `tree`, `state`, `sequence`
- **Security & Structure**: `layers`, `nested`, `swimlane`, `quadrant`, `pyramid`
- **Data & Product Loops**: `medallion`, `timeline`, `gantt`, `flywheel`, `loop`, `constellation`, `radar`, `venn`
**Themes**: `midnight` (dark modern), `paper` (light technical), `blueprint` (CAD cyan), `editorial` (serif publication), `graphite` (minimal dark), `nebula` (cosmic violet), `terminal` (CLI retro), `sketchy` (hand-drawn), `ink` (blue ballpoint & fountain pen ink), `doodle` (playful doodle).
👉 *[Explore all 33+ interactive scenes in the Live Gallery ↗](https://markdy.com/examples/)*
🔄 Universal Ingestion (1-Command Migration)
Convert existing diagrams and infrastructure configs into animated MarkdyScript scenes:
```bash
markdy import flow.mmd --out flow.markdy # Mermaid.js Flowcharts & Sequences
markdy import architecture.d2 --out arch.markdy # D2 Architecture & Sequence Diagrams
markdy import system.puml --out system.markdy # PlantUML Component & Sequence Specs
markdy import docker-compose.yml --out compose.markdy # Docker Compose Services & Networks
markdy import k8s-manifests/ --out cluster.markdy # Kubernetes Ingress, Pods & Services
markdy import terraform.tfstate --out infra.markdy # Terraform Provisioned State
markdy import architecture.drawio --out diagram.markdy # Draw.io / diagrams.net XML
```
🤖 AI Coding Agents & Model Context Protocol (MCP) Setup (Cursor, VS Code, Claude, Antigravity)
Equip your favorite AI Coding Agent with native Markdy tools (`validate_markdy_code`, `diagnose_markdy_syntax`, `fix_markdy_code`, `transpile_to_markdy`, `explain_architecture`, `generate_markdy_prompt`, `get_architecture_catalog`, `get_markdy_intellicode`) and live specification resources (`markdy://spec/agent-reference`).
### ⚡ Quick MCP Server Setup & Installation
| AI Environment | Setup Action | Method |
|---|---|---|
| **Cursor** | [](https://markdy.com/mcp/cursor) | **[1-Click Install ↗](https://markdy.com/mcp/cursor)** or [JSON Config](#cursor-setup) |
| **VS Code / Copilot** | [](https://markdy.com/mcp/vscode) | **[1-Click Install ↗](https://markdy.com/mcp/vscode)** or [JSON Config](#vscode-setup) |
| **Claude Code & Desktop** | [](#claude-setup) | **CLI (`claude mcp add`) & JSON** |
| **Google Antigravity** | [](#antigravity-setup) | **1-Command CLI (`agy mcp add`)** |
| **Cline / Roo Code** | [](#cline-setup) | **Config File (`cline_mcp_settings.json`)** |
| **Windsurf / Cascade** | [](#windsurf-setup) | **Config File (`mcp_config.json`)** |
| **Zed Editor** | [](#zed-setup) | **Config File (`settings.json`)** |
---
### 🛠️ Client Configuration Snippets
#### 1. Claude Code & Claude Desktop
**Claude Code (Anthropic CLI):**
```bash
claude mcp add markdy -- npx -y @markdy/mcp-server
```
**Claude Desktop GUI (`claude_desktop_config.json`):**
```json
{
"mcpServers": {
"markdy": {
"command": "npx",
"args": ["-y", "@markdy/mcp-server"]
}
}
}
```
#### 2. Cursor & VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)
```json
{
"mcpServers": {
"markdy": {
"command": "npx",
"args": ["-y", "@markdy/mcp-server"]
}
}
}
```
#### 3. Google Antigravity & Gemini CLI
**Via 1-Command CLI:**
```bash
agy mcp add markdy -- npx -y @markdy/mcp-server
```
**Or via Config File (`~/.gemini/antigravity/mcp_config.json` or `.agents/mcp_config.json`):**
```json
{
"mcpServers": {
"markdy": {
"command": "npx",
"args": ["-y", "@markdy/mcp-server"]
}
}
}
```
#### 4. Cline & Roo Code (`cline_mcp_settings.json`)
```json
{
"mcpServers": {
"markdy": {
"command": "npx",
"args": ["-y", "@markdy/mcp-server"]
}
}
}
```
#### 5. Windsurf / Cascade (`~/.codeium/windsurf/mcp_config.json`)
```json
{
"mcpServers": {
"markdy": {
"command": "npx",
"args": ["-y", "@markdy/mcp-server"]
}
}
}
```
#### 6. Zed Editor (`settings.json`)
```json
{
"context_servers": {
"markdy": {
"command": {
"path": "npx",
"args": ["-y", "@markdy/mcp-server"]
}
}
}
}
```
---
### 🧰 Available Agent Tools & Resources
- 🔍 `validate_markdy_code`: Check syntax, unresolved node references, and cycle rules.
- 💡 `diagnose_markdy_syntax`: Detailed diagnostics with exact line numbers and remediation steps.
- 🩹 `fix_markdy_code`: Self-healing code repair that fixes common syntax mistakes and formats AST.
- 🔄 `transpile_to_markdy`: Convert Mermaid, D2, PlantUML, Docker Compose, Kubernetes, Terraform, or Draw.io into valid MarkdyScript.
- 🧭 `explain_architecture`: Structural topology summaries, component role counts, and governance health metrics.
- 💬 `generate_markdy_prompt`: Optimal LLM system prompts and grammar constraints for AI coding agents.
- 📦 `get_architecture_catalog`: Golden architecture templates with full runnable MarkdyScript code.
- ⚡ `get_markdy_intellicode`: Zero-dependency predictive completion and proactive recommendations.
- 📚 `markdy://spec/agent-reference`: Full AST grammar reference and token catalog.
- 📐 `markdy://spec/grammar-rules`: Grammar conventions and cycle-safe routing rules.
- 🏛️ `markdy://governance/rules`: Architecture rules (Well-Architected, cycle bounds, layer separation).
- 📦 `markdy://templates/catalog`: 33 production-grade architecture blueprints.
👉 *[Read the Full AI Agent Reference Guide (`AGENT.md`) ↗](https://markdy.com/agent/)*
---
## 🚦 Verification Gates & Quality Engineering
Automated Verification Gates & CI/CD Quality Pipeline
Every pull request and build must pass the automated full-cycle verification pipeline:
| Command | Verification Gate | Focus Area |
|---|---|---|
| `pnpm test` | **Unit & Integration Suite** | AST parser, compiler math, layout solvers, CLI |
| `pnpm test:visual` | **Automated Visual Gate** | Headless Chrome + Pixelmatch against golden baselines (`tests/visual-baselines/`) |
| `pnpm test:perf` | **Sub-Frame Performance Gate** | Chrome DevTools Protocol tracing (sub-40ms render, <25MB JS heap) |
| `pnpm verify:examples` | **Canonical Showcase Gate** | 33 production blueprints compile with zero warnings |
| `cleanroom-guard check` | **Anti-Leak & Clean-Room** | Pre-commit secret scanning and clean-room zero-footprint protection |
---
## 📖 Documentation Links
| Guide | Description |
|---|---|
| **[Syntax Reference (SYNTAX.md)](docs/SYNTAX.md)** | Full DSL grammar, flow operators, selectors, cues, and player settings |
| **[Step-by-Step Tutorial (TUTORIAL.md)](docs/TUTORIAL.md)** | Step-by-step guide from basic flows to multi-beat kinetic scenes |
| **[AI Agent Guide (AGENT.md)](AGENT.md)** | LLM system prompts, token rules, and anti-patterns |
| **[Architecture Internals (ARCHITECTURE.md)](docs/ARCHITECTURE.md)** | Compiler pipelines, WAAPI loop, and orthogonal routing geometry |
| **[VS Code Extension Guide](packages/vscode/README.md)** | Shortcuts, settings, and IDE features |
---
Empowering engineers and AI agents to create living architecture diagrams.
Built with ❤️ by Hoang Yell & the community. Distributed under the MIT License.