hoangyell/markdy-com

101 stars 3 forks Quality 89 Trend 48MIT

🎬 Open-source animated architecture diagrams as code. Diagram-native DSL, 17 layout engines, Web Animations API, and MCP server for AI agents.

Overview

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 You don't need to write MarkdyScript manually. Ask , , , , 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 with a Web Client, API Gateway, URL Service, Redis Cluster, and PostgreSQL database. Include two animated storyboard beats: and ." (Tip: If you have the official Markdy MCP Server installed, just ask: "Create an animated Markdy architecture diagram for our cache-aside service.") 🤖 AI-Generated MarkdyScript ( system.markdy ) Choose your preferred preview environment:

README

⚡ 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:

2. Preview & Explore

Choose your preferred preview environment:

Interactive Web Studio: markdy.com/playground ↗:
Instant browser playground with timeline scrubbing, GIF/SVG export, and shareable links.
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

3. 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: `` - 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 ↗

⚡ Why Markdy?

🌟 Advanced Engineering Superpowers

🔌 Integrations & Ecosystem

Extend Markdy across your favorite AI agents, editors, frameworks, and deployment workflows:

📊 Feature Comparison

📦 Component Responsibilities & Packages

🔍 Detailed Features & Advanced Usage

🚦 Verification Gates & Quality Engineering

📖 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.

View the full README on GitHub

Install

npx -y @markdy/mcp-server

New to MCP? Start with the mcpskill.org guide →

Configuration

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