Turn architecture diagrams into step-by-step explanations of how your system works.
Markdy turns text into animated diagrams for system design, documentation, and walkthroughs.

Cache hit: return from Redis. Cache miss: query PostgreSQL and refill the cache.
Try this example →  •  View the source
_{Open in your browser. No installation or AI account required.}

Documentation  •  Examples  •  VS Code Extension  •  AI & Agent Guide  •  Sponsor & Pro Blueprints

💼 Sponsorship & Commercial Use: Markdy is free and open source under the MIT license. If you use Markdy in commercial projects or want to support ongoing engineering, consider sponsoring on GitHub.

---

⚡ Why Markdy?

• Explain behavior, not just topology. Walk through requests, responses, and background events one step at a time.
• Keep the explanation beside the code. Store diagrams as readable .markdy files you can review and version in Git.
• Start in the browser. Try an example, edit it, and share it. Use an AI agent to help write the script when you need one.

🚀 Quick Start

1. Try the Live Example

Open the cache-aside walkthrough. Play it or step through the timeline to follow the cache hit and miss paths.

2. Make It Yours

Edit the example in the studio, or start with the smaller script below. Write MarkdyScript yourself, or ask your coding agent to generate it.

Optional: generate a diagram with your AI 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 installed, just ask: "Create an animated Markdy architecture diagram for our cache-aside service.")

A small cache-aside scene (system.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

3. Preview Locally (Optional)

Prefer your own editor or terminal? Save the script as system.markdy:

• VS Code / Cursor Extension — 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:

  npx @markdy/cli render system.markdy --out diagram.html

Embed in Web Apps & Docs

Choose the package that fits your stack:

• Web Apps (Vanilla JS, React, Vue, Svelte) — @markdy/renderer-dom:

  npm install @markdy/renderer-dom

  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:

  npm install @markdy/astro

  (Zero-CLS SSR island: <Markdy code={code} client:visible /> — see Astro Guide ↓)

• Next.js / MDX Docs — @markdy/mdx:

  npm install @markdy/mdx

  (Auto-renders fenced ```markdy blocks — see MDX Guide ↓)

👉 DOM Renderer Guide ↗  •  Astro Guide ↗  •  MDX Guide ↗  •  Core Compiler ↗

---

Technical Capabilities

Explore the technical capabilities

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.
• 🔬 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, 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, 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

Markdy goes beyond basic diagram drawing into a comprehensive Architecture Intelligence Platform:

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	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)	Automated visual diffing and animated migration timeline generation
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 & README cards with active route/blast-radius telemetry
9-Point Showcase Quality Gate	markdy verify <file> --quality showcase	Deterministic SHA-256 integrity receipt & responsive viewport validation
Architecture Recipe Guidance	markdy guide "<query>"	Instant AI scenario pattern matching for cache-aside, EDA, zero-trust, and lakehouse
Native Vector Symbols	icon=redis, icon=kafka	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:

# 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 ↗  •  1-Click Install for VS Code ↗  •  Full JSON Configs for 6 IDEs ↓  •  AI Agent Guide (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:

# Visual Studio Code
code --install-extension hoangyell.markdy-vscode

# Cursor / VSCodium (Open VSX Registry)
cursor --install-extension hoangyell.markdy-vscode

👉 VS Code Marketplace ↗  •  Open VSX Registry ↗  •  Extension Docs ↗

🚀 Astro Integration (`@markdy/astro`)

Zero-CLS, SSR-placeholder islands with viewport-triggered lazy hydration for Astro documentation sites and blogs:

pnpm add @markdy/astro

---
import { Markdy } from "@markdy/astro";
import code from "./diagram.markdy?raw";
---

<Markdy code={code} client:visible />

👉 @markdy/astro Package Guide ↗

📝 MDX / React / Next.js Integration (`@markdy/mdx`)

Render fenced ```markdy code blocks directly inside .mdx files with automatic lazy loading:

pnpm add @markdy/mdx react react-dom

// mdx.config.js
import { remarkMarkdy } from "@markdy/mdx";

export default {
  remarkPlugins: [[remarkMarkdy, { componentName: "MarkdyDiagram" }]],
};

👉 @markdy/mdx Package Guide ↗

⚡ Terminal CLI & CI/CD (`@markdy/cli`, `@markdy/compat`)

Render standalone HTML diagrams or run architecture linting in CI/CD pipelines:

# 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

👉 CLI Package Guide ↗  •  Universal Ingestion Guide ↗

🏗️ Systems Vocabulary & Language Server (`@markdy/stdlib-systems`, `@markdy/language-server`)

• @markdy/stdlib-systems: Standard library of semantic cloud and distributed systems node kinds.
• @markdy/language-server: Headless LSP for custom editor integrations (Neovim, Helix, Emacs).

---

📊 Feature Comparison

Feature Matrix (vs Mermaid, PlantUML, 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 Linter	❌ None	❌ None	✅ Built-in rules (e.g. anti-pattern detection)
Universal Ingestion	❌ Manual rewrite	❌ Manual export	✅ 1-Click Transpiler for Mermaid, Compose, K8s, Terraform
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	Compiler Core & AST Engine	parse(), compile(), formatScene(), diagnoseMarkdyCode(), validateArchitecture(). Zero dependencies (~14 kB).
@markdy/renderer-dom	Motion Graphics & Rendering	createDiagram(), exportDiagramAsVectorSvg(), exportDiagramAsPng(), exportDiagramAsGif(). 60fps WAAPI timeline.
markdy-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	Universal Ingestion Suite	Transpilers for Mermaid, Docker Compose, Kubernetes YAMLs, Terraform state, and Draw.io XML.
@markdy/cli	Terminal Tool & CI/CD	markdy lint, markdy render, markdy format, markdy import, markdy diff.
@markdy/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 & @markdy/mdx	Docs & Blog Integrations	Zero-CLS, SSR-placeholder islands with viewport hydration for content sites.
@markdy/language-server	Headless LSP Server	Diagnostic publishing, hover docs, formatting, and completions for language clients.
@markdy/stdlib-systems	Domain Vocabulary	Semantic primitives for cloud, infrastructure, and distributed systems.

---

🔍 Detailed Features & Advanced Usage

🎨 17 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, 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 17+ interactive scenes in the Live Gallery ↗

🔄 Universal Ingestion (1-Command Migration)

Convert existing diagrams and infrastructure configs into animated MarkdyScript scenes:

markdy import flow.mmd            --out flow.markdy        # Mermaid.js Flowcharts & Sequences
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) and live specification resources (markdy://spec/agent-reference).

⚡ Quick MCP Server Setup & Installation

AI Environment	Setup Action	Method
Cursor		1-Click Install ↗ or JSON Config
VS Code / Copilot		1-Click Install ↗ or JSON Config
Claude Code & Desktop		CLI (claude mcp add) & JSON
Google Antigravity		1-Command CLI (agy mcp add)
Cline / Roo Code		Config File (cline_mcp_settings.json)
Windsurf / Cascade		Config File (mcp_config.json)
Zed Editor		Config File (settings.json)

---

🛠️ Client Configuration Snippets

1. Claude Code & Claude Desktop

Claude Code (Anthropic CLI):

claude mcp add markdy -- npx -y @markdy/mcp-server

Claude Desktop GUI (claude_desktop_config.json):

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

2. Cursor & VS Code (.cursor/mcp.json or .vscode/mcp.json)

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

3. Google Antigravity & Gemini CLI

Via 1-Command CLI:

agy mcp add markdy -- npx -y @markdy/mcp-server

Or via Config File (~/.gemini/antigravity/mcp_config.json or .agents/mcp_config.json):

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

4. Cline & Roo Code (cline_mcp_settings.json)

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

5. Windsurf / Cascade (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

6. Zed Editor (settings.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, Docker Compose, Kubernetes, Terraform, or Draw.io into valid MarkdyScript.
• 📚 markdy://spec/agent-reference: Full AST grammar reference and token catalog.
• 🏛️ 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) ↗

---

🚦 Verification Gates & Quality Engineering

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)	Full DSL grammar, flow operators, selectors, cues, and player settings
Step-by-Step Tutorial (TUTORIAL.md)	Step-by-step guide from basic flows to multi-beat kinetic scenes
AI Agent Guide (AGENT.md)	LLM system prompts, token rules, and anti-patterns
Architecture Internals (ARCHITECTURE.md)	Compiler pipelines, WAAPI loop, and orthogonal routing geometry
VS Code Extension Guide	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.}