HoangYell/markdy-com
HoangYell/markdy-com has 106 GitHub stars and 3 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 19:46 UTC. Last push 2026-11-15.
What you can do
- 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
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
π¬ Open-source animated architecture diagrams as code. Diagram-native DSL, 17 layout engines, Web Animations API, and MCP server for AI agents.
Creative & MediaREADME.md
Original
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 β’ π 91+ 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
.markdyscene:
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.")
π€ AI-Generated MarkdyScript (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
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:
PressCmd+K V(macOS) orCtrl+K V(Windows/Linux) for live side-by-side animated preview.Terminal CLI:
@markdy/cli:# Interactive HTML preview npx @markdy/cli render system.markdy --out diagram.html # Direct pure vector SVG & standalone offline HTML npx @markdy/cli render system.markdy --out diagram.svg npx @markdy/cli render system.markdy --out scene.html --offline
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-domimport { 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
```markdyblocks - see MDX Guide β)
π DOM Renderer Guide β β’ Astro Guide β β’ MDX Guide β β’ Core Compiler β
β‘ 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 sequentialbeattimelines 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, Azure, Kubernetes, Docker, Postgres, Redis, Kafka, Grafana, Vercel, Next.js, Hono, Neon, Clerk, Stripe, Supabase, Tailwind, and 35+ 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:
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 <file> --quality showcase |
Deterministic SHA-256 integrity receipt and responsive viewport validation |
| Architecture Recipe Guidance | markdy guide "<query>" / 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:
# 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 />
π 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" }]],
};
β‘ Terminal CLI & CI/CD (`@markdy/cli`, `@markdy/compat`)
Render standalone HTML diagrams, verify showcase quality, 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
# 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 β β’ 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, 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 |
Compiler Core & AST Engine | parse(), compile(), formatScene(), diagnoseMarkdyCode(), validateArchitecture(), detectArchitectureDrift(), analyzeC4Model(). Zero dependencies (~14 kB). |
@markdy/renderer-dom |
Motion Graphics & Rendering | createDiagram(), exportDiagramAsVectorSvg(), exportDiagramAsPng(), exportDiagramAsGif(), exportRouteShareCard(). 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, D2, PlantUML, Docker Compose, Kubernetes YAMLs, Terraform state, and Draw.io XML. |
@markdy/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 |
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
π¨ 18 Specialized Layout Engines & 12 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: cad (engineered-paper blueprint), cad-dark (dark slate architecture CAD), 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 β
π 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 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 | 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, 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.
π¦ 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) | 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.