Skip to content
Back to search

markdy-com

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/HoangYell/markdy-com with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/HoangYell/markdy-com'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hoangyell--markdy-com/badge.svg)](/listings/hoangyell--markdy-com)

HTML

<a href="/listings/hoangyell--markdy-com"><img src="/api/listings/hoangyell--markdy-com/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Try the Live Example

Open the **[cache-aside walkthrough](https://markdy.com/playground/?example=url-shortener-architecture)**. 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.

<details> <summary><b>Optional: generate a diagram with your AI agent</b></summary> <br>

> "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."`)*

</details>

<details> <summary><b>A small cache-aside scene (<code>system.markdy</code>)</b></summary> <br>

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

</details>

3. Preview Locally (Optional)

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

- **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):

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

plugin.json Β· Manifest Β· 33 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "markdy",
  3. "version": "1.1.1",
  4. "description": "Declarative 60fps kinetic architecture diagrams as code. Design animated cloud, microservices, and system diagrams directly with MarkdyScript and AI agents.",
  5. "author": {
  6. "name": "Hoang Yell",
  7. "email": "hoangyell@gmail.com"
  8. },
  9. "homepage": "https://markdy.com",
  10. "repository": "https://github.com/HoangYell/markdy-com",
  11. "license": "MIT",
  12. "keywords": [
  13. "diagrams",
  14. "architecture",
  15. "animation",
  16. "waapi",
  17. "system-design",
  18. "mermaid",
  19. "mcp",
  20. "cursor-plugin"
  21. ],
  22. "logo": "docs/images/mascot/icon.svg",
  23. "skills": "skills/",
  24. "rules": "rules/",
  25. "agents": "agents/",
  26. "commands": "commands/",
  27. "mcpServers": {
  28. "markdy": {
  29. "command": "npx",
  30. "args": ["-y", "@markdy/mcp-server"]
  31. }
  32. }
  33. }
README.md Β· README Β· 597 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://markdy.com">
  3. <img src="docs/images/mascot/markdy-com.webp" width="340" alt="Markdy" />
  4. </a>
  5. </p>
  6. <p align="center">
  7. <strong>Diagram-as-code DSL for animated architecture &amp; system design explainers.</strong><br>
  8. Prompt your AI agent β†’ generate declarative MarkdyScript β†’ render 60fps kinetic diagrams powered by the Web Animations API.
  9. </p>
  10. <p align="center">
  11. <a href="https://markdy.com/playground/"><b>⚑ Live Studio</b></a> &nbsp;β€’&nbsp;
  12. <a href="https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode"><b>πŸ”Œ VS Code Extension</b></a> &nbsp;β€’&nbsp;
  13. <a href="https://markdy.com/docs/"><b>πŸ“– Documentation</b></a> &nbsp;β€’&nbsp;
  14. <a href="https://markdy.com/examples/"><b>🌟 91+ Blueprints</b></a> &nbsp;β€’&nbsp;
  15. <a href="https://markdy.com/agent/"><b>πŸ€– AI &amp; Agent Guide</b></a>
  16. </p>
  17. <p align="center">
  18. <a href="https://github.com/HoangYell/markdy-com/actions/workflows/ci.yml"><img src="https://github.com/HoangYell/markdy-com/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a>
  19. <a href="https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode"><img src="https://vsmarketplacebadges.dev/version-short/hoangyell.markdy-vscode.svg" alt="VS Code Extension" /></a>
  20. <a href="https://open-vsx.org/extension/hoangyell/markdy-vscode"><img src="https://img.shields.io/open-vsx/v/hoangyell/markdy-vscode?color=purple&label=Open%20VSX" alt="Open VSX Extension" /></a>
  21. <a href="https://www.npmjs.com/package/@markdy/core"><img src="https://img.shields.io/npm/v/@markdy/core?color=blue&label=%40markdy%2Fcore" alt="npm version" /></a>
  22. <a href="https://www.npmjs.com/package/@markdy/mcp-server"><img src="https://img.shields.io/npm/v/@markdy/mcp-server?color=purple&label=MCP%20Server" alt="MCP Server version" /></a>
  23. <a href="https://www.npmjs.com/package/@markdy/core"><img src="https://img.shields.io/badge/core_size-~14_kB-brightgreen" alt="Core Bundle Size" /></a>
  24. <a href="https://github.com/HoangYell/markdy-com/blob/main/LICENSE"><img src="https://img.shields.io/github/license/HoangYell/markdy-com" alt="MIT License" /></a>
  25. </p>
  26. <p align="center">
  27. <a href="https://markdy.com/playground/">
  28. <img src="docs/images/markdy-split-editor.webp" width="100%" alt="Markdy Interactive Studio" />
  29. </a>
  30. </p>
  31. ---
  32. ## πŸ’‘ How It Works
  33. > **Describe your system in plain English β†’ your AI agent generates the Markdy script β†’ your browser renders the animated diagram.**
  34. <p align="center">
  35. <img src="docs/images/ai-paradigm-flow.webp" width="100%" alt="How to Use Markdy with AI Agents" />
  36. </p>
  37. ---
  38. ## πŸš€ Quick Start (60 Seconds)
  39. ### 1. Prompt Your AI Agent
  40. You don't need to write MarkdyScript manually. Ask **Cursor**, **Claude Code**, **Google Antigravity**, **ChatGPT**, or any coding agent:
  41. <details>
  42. <summary><b>πŸ’¬ Example Prompt (Copy &amp; Paste to your Agent)</b></summary>
  43. <br>
  44. > "Follow the canonical Markdy specification (https://markdy.com/AGENT.md) and generate a `.markdy` scene:
  45. > 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**."
  46. *(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."`)*
  47. </details>
  48. <details>
  49. <summary><b>πŸ€– AI-Generated MarkdyScript (<code>system.markdy</code>)</b></summary>
  50. <br>
  51. ```markdy
  52. scene "Cache-Aside Architecture" theme=auto
  53. layout LR
  54. browser Client "Web Client"
  55. gateway Gateway "API Gateway"
  56. service Svc "URL Service"
  57. cache Redis "Redis Cluster"
  58. database Postgres "PostgreSQL 16"
  59. beat cache_hit "1. Cache Hit Path":
  60. show $nodes stagger=60ms
  61. frame Client Gateway Svc Redis zoom=1.12
  62. Client -> Gateway "GET /link" -> Svc "resolve"
  63. Svc -> Redis "GET key:link"
  64. Svc <- Redis "200 Target URL"
  65. Client <- Gateway "301 Redirect"
  66. beat cache_miss "2. Cache Miss & Async Warm":
  67. frame Svc Redis Postgres zoom=1.15
  68. Svc -> Postgres "SELECT destination WHERE key = 'link'"
  69. Svc <- Postgres "Row Found"
  70. Svc ~> Redis "SETEX key:link (Warm Cache)"
  71. glow Postgres color=#38bdf8 & glow Redis color=#22c55e
  72. ```
  73. </details>
  74. ### 2. Preview & Explore
  75. Choose your preferred preview environment:
  76. - **Interactive Web Studio**: **[markdy.com/playground β†—](https://markdy.com/playground/)**:
  77. Instant browser playground with timeline scrubbing, GIF/SVG export, and shareable links.
  78. - **VS Code / Cursor Extension**: [`hoangyell.markdy-vscode`](https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode):
  79. Press **`Cmd+K V`** *(macOS)* or **`Ctrl+K V`** *(Windows/Linux)* for live side-by-side animated preview.
  80. - **Terminal CLI**: [`@markdy/cli`](packages/cli/README.md):
  81. ```bash
  82. # Interactive HTML preview
  83. npx @markdy/cli render system.markdy --out diagram.html
  84. # Direct pure vector SVG & standalone offline HTML
  85. npx @markdy/cli render system.markdy --out diagram.svg
  86. npx @markdy/cli render system.markdy --out scene.html --offline
  87. ```
  88. ### 3. Embed in Web Apps & Docs
  89. Choose the package that fits your stack:
  90. - **Web Apps (Vanilla JS, React, Vue, Svelte)**: [`@markdy/renderer-dom`](packages/renderer-dom/README.md):
  91. ```bash
  92. npm install @markdy/renderer-dom
  93. ```
  94. ```ts
  95. import { createDiagram } from "@markdy/renderer-dom";
  96. // Mount and render interactive 60fps WAAPI diagram directly from code
  97. const diagram = createDiagram({
  98. container: document.getElementById("diagram-container")!,
  99. code: markdyScriptCode,
  100. });
  101. ```
  102. - **Astro Sites & Blogs**: [`@markdy/astro`](packages/astro/README.md):
  103. ```bash
  104. npm install @markdy/astro
  105. ```
  106. *(Zero-CLS SSR island: `<Markdy code={code} client:visible />` - see [Astro Guide ↓](#astro-integration))*
  107. - **Next.js / MDX Docs**: [`@markdy/mdx`](packages/mdx/README.md):
  108. ```bash
  109. npm install @markdy/mdx
  110. ```
  111. *(Auto-renders fenced ```` ```markdy ```` blocks - see [MDX Guide ↓](#mdx-integration))*
  112. πŸ‘‰ **[DOM Renderer Guide β†—](packages/renderer-dom/README.md)** &nbsp;β€’&nbsp; **[Astro Guide β†—](packages/astro/README.md)** &nbsp;β€’&nbsp; **[MDX Guide β†—](packages/mdx/README.md)** &nbsp;β€’&nbsp; **[Core Compiler β†—](packages/core/README.md)**
  113. ---
  114. ## ⚑ Why Markdy?
  115. <details>
  116. <summary><b>Kinetic Motion Graphics vs. Static Architecture Diagrams</b></summary>
  117. <br>
  118. Static boxes and arrows fail to capture distributed systems in action. **Markdy turns text into choreographed 60fps motion graphics** directly in your browser.
  119. - 🎬 **Kinetic Storytelling**: Choreograph requests (`->`), responses (`<-`), and events (`~>`) across sequential `beat` timelines with auto-zooms and glow cues.
  120. - πŸ“ **Dynamic Port Multiplexing**: Automatically balances parallel connections across node boundaries with zero line congestion or overlapping paths.
  121. - πŸ”— **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.
  122. - πŸ”„ **Architectural Evolution Matrix**: Compare architecture states across Git commits and automatically synthesize animated migration storyboards (`markdy diff`).
  123. - πŸ›οΈ **C4 Hierarchy & Architecture Drift**: Native Context, Container, Component, and Code level projections (`markdy c4`) with automatic drift detection (`markdy drift`).
  124. - πŸ”¬ **Blast Radius & Route Pathfinder**: Compute upstream dependency callers, downstream failure blast radius, and shortest message paths in real-time.
  125. - πŸ’Ž **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.
  126. - ⚑ **Zero-Dep & Web-Native**: Powered by pure CSS/SVG transforms and the Web Animations API (WAAPI): ~14 kB parser, no Canvas, no GSAP.
  127. - πŸ”„ **Universal Ingestion**: 1-click migration from Mermaid, D2, PlantUML, Draw.io, Docker Compose, Kubernetes manifests, and Terraform states.
  128. - πŸ€– **AI-Native & MCP**: Official Model Context Protocol (MCP) server for Claude, Cursor, Antigravity, and Cline with self-healing syntax diagnostics.
  129. - πŸ›‘οΈ **Architecture Governance**: Built-in rules prevent deadlock cycles and cross-layer bypasses.
  130. </details>
  131. ---
  132. ## 🌟 Advanced Engineering Superpowers
  133. <details>
  134. <summary><b>Architecture Intelligence Platform (Code Provenance, C4, Drift, Blast Radius)</b></summary>
  135. <br>
  136. Markdy goes beyond basic diagram drawing into a comprehensive **Architecture Intelligence Platform**:
  137. ```markdy
  138. scene "Cloud Native Microservices Mesh" theme=paper
  139. layout LR
  140. gateway ApiGateway "API Gateway" icon=nginx @src="src/gateway/router.ts#L20"
  141. service OrderSvc "Order Service" icon=nodejs @src="src/orders/service.ts#L45"
  142. service UserSvc "User Service" icon=golang @src="src/users/handler.go#L30"
  143. cache Redis "Redis Cluster" icon=redis
  144. database Postgres "PostgreSQL 16" icon=postgresql
  145. beat workflow:
  146. show $nodes stagger=60ms
  147. ApiGateway -> OrderSvc "POST /orders" & ApiGateway -> UserSvc "GET /profile"
  148. OrderSvc -> Postgres "Write Order" & UserSvc -> Postgres "Read User"
  149. OrderSvc ~> Redis "Cache Invalidation"
  150. ```
  151. | Superpower | Syntax / API / CLI | Developer Impact |
  152. | :--- | :--- | :--- |
  153. | **Dynamic Port Multiplexing** | Auto-calculated | Perfectly balanced multi-lane fan-in/fan-out with smooth fillet curves |
  154. | **Code Provenance Anchors** | `@src="path/file.ts#L10"` | Guaranteed synchronization between architecture diagrams and real Git code |
  155. | **Evolution Git-Diff** | `diffDiagramASTs(v1, v2)` / `markdy diff` | Automated visual diffing and animated migration timeline generation |
  156. | **Architecture Drift Detection** | `detectArchitectureDrift()` / `markdy drift` | Detect broken `@src` anchors and orphan microservices against Git history |
  157. | **C4 Hierarchy Modeling** | `analyzeC4Model()` / `markdy c4` | Native Context, Container, Component, and Code level views and transitions |
  158. | **Blast Radius Lens** | `calculateBlastRadius(node, ast)` | Real-time upstream impact and downstream failure cascade isolation |
  159. | **Contextual Share Cards (1200Γ—630)** | `exportRouteShareCard()`, `exportReachShareCard()` | High-impact social and README cards with active route/blast-radius telemetry |
  160. | **9-Point Showcase Quality Gate** | `markdy verify <file> --quality showcase` | Deterministic SHA-256 integrity receipt and responsive viewport validation |
  161. | **Architecture Recipe Guidance** | `markdy guide "<query>"` / `markdy recipe` | Instant AI scenario pattern matching for cache-aside, EDA, zero-trust, and lakehouse |
  162. | **Native Vector Symbols** | `icon=redis`, `icon=kafka`, `icon=grafana` | Zero-CDN, lightweight vector badges embedded directly in the artifact |
  163. </details>
  164. ---
  165. ## πŸ”Œ Integrations & Ecosystem
  166. Extend Markdy across your favorite AI agents, editors, frameworks, and deployment workflows:
  167. <details>
  168. <summary><b>πŸ€– AI Coding Agents &amp; MCP Server (Recommended)</b></summary>
  169. <br>
  170. Equip Claude, Cursor, Antigravity, VS Code, Cline, Windsurf, or Zed with self-healing syntax diagnostics, auto-repair, and transpilers:
  171. ```bash
  172. # Claude Code / CLI
  173. claude mcp add markdy -- npx -y @markdy/mcp-server
  174. # Google Antigravity & Gemini CLI
  175. agy mcp add markdy -- npx -y @markdy/mcp-server
  176. ```
  177. πŸ‘‰ **[1-Click Install for Cursor β†—](https://markdy.com/mcp/cursor)** &nbsp;β€’&nbsp; **[1-Click Install for VS Code β†—](https://markdy.com/mcp/vscode)** &nbsp;β€’&nbsp; **[Full JSON Configs for 6 IDEs ↓](#mcp-setup)** &nbsp;β€’&nbsp; **[AI Agent Guide (`AGENT.md`) β†—](AGENT.md)**
  178. </details>
  179. <details>
  180. <summary><b>πŸ”Œ IDE Extensions (VS Code, Cursor, Windsurf, VSCodium)</b></summary>
  181. <br>
  182. Live side-by-side animated preview (`Cmd+K V`), syntax highlighting, auto-completion, error squiggles, and SVG/PNG export:
  183. ```bash
  184. # Visual Studio Code
  185. code --install-extension hoangyell.markdy-vscode
  186. # Cursor / VSCodium (Open VSX Registry)
  187. cursor --install-extension hoangyell.markdy-vscode
  188. ```
  189. πŸ‘‰ **[VS Code Marketplace β†—](https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode)** &nbsp;β€’&nbsp; **[Open VSX Registry β†—](https://open-vsx.org/extension/hoangyell/markdy-vscode)** &nbsp;β€’&nbsp; **[Extension Docs β†—](packages/vscode/README.md)**
  190. </details>
  191. <a id="astro-integration"></a>
  192. <details id="astro-integration">
  193. <summary><b>πŸš€ Astro Integration (`@markdy/astro`)</b></summary>
  194. <br>
  195. Zero-CLS, SSR-placeholder islands with viewport-triggered lazy hydration for Astro documentation sites and blogs:
  196. ```bash
  197. pnpm add @markdy/astro
  198. ```
  199. ```astro
  200. ---
  201. import { Markdy } from "@markdy/astro";
  202. import code from "./diagram.markdy?raw";
  203. ---
  204. <Markdy code={code} client:visible />
  205. ```
  206. πŸ‘‰ **[@markdy/astro Package Guide β†—](packages/astro/README.md)**
  207. </details>
  208. <a id="mdx-integration"></a>
  209. <details id="mdx-integration">
  210. <summary><b>πŸ“ MDX / React / Next.js Integration (`@markdy/mdx`)</b></summary>
  211. <br>
  212. Render fenced ```markdy code blocks directly inside `.mdx` files with automatic lazy loading:
  213. ```bash
  214. pnpm add @markdy/mdx react react-dom
  215. ```
  216. ```ts
  217. // mdx.config.js
  218. import { remarkMarkdy } from "@markdy/mdx";
  219. export default {
  220. remarkPlugins: [[remarkMarkdy, { componentName: "MarkdyDiagram" }]],
  221. };
  222. ```
  223. πŸ‘‰ **[@markdy/mdx Package Guide β†—](packages/mdx/README.md)**
  224. </details>
  225. <details>
  226. <summary><b>⚑ Terminal CLI &amp; CI/CD (`@markdy/cli`, `@markdy/compat`)</b></summary>
  227. <br>
  228. Render standalone HTML diagrams, verify showcase quality, or run architecture linting in CI/CD pipelines:
  229. ```bash
  230. # Global install
  231. npm install -g @markdy/cli
  232. # Render diagram to animated HTML or SVG
  233. markdy render system.markdy --out diagram.html
  234. # Lint Markdy architecture scenes in CI/CD
  235. markdy lint **/*.markdy
  236. # Verify showcase blueprint quality gate
  237. markdy verify system.markdy --quality showcase
  238. # Detect architecture drift against Git source code
  239. markdy drift system.markdy
  240. # Model C4 multi-level architectural hierarchy
  241. markdy c4 system.markdy --level container
  242. # Transpile external diagrams (Mermaid, D2, PlantUML, Compose, K8s, Terraform, Draw.io)
  243. markdy import flow.mmd --out flow.markdy
  244. ```
  245. πŸ‘‰ **[CLI Package Guide β†—](packages/cli/README.md)** &nbsp;β€’&nbsp; **[Universal Ingestion Guide β†—](packages/compat/README.md)**
  246. </details>
  247. <details>
  248. <summary><b>πŸ—οΈ Systems Vocabulary &amp; Language Server (`@markdy/stdlib-systems`, `@markdy/language-server`)</b></summary>
  249. <br>
  250. - **[`@markdy/stdlib-systems`](packages/stdlib-systems/README.md)**: Standard library of semantic cloud and distributed systems node kinds.
  251. - **[`@markdy/language-server`](packages/markdy-language-server/README.md)**: Headless LSP for custom editor integrations (Neovim, Helix, Emacs).
  252. </details>
  253. ---
  254. ## πŸ“Š Feature Comparison
  255. <details>
  256. <summary><b>Feature Matrix (vs Mermaid, PlantUML, D2, Excalidraw, Draw.io)</b></summary>
  257. <br>
  258. | Capability | Mermaid / PlantUML | Excalidraw / Draw.io | Markdy |
  259. |---|---|---|---|
  260. | **Animation & Timing** | ❌ Static SVG / PNG | ❌ Static canvas | βœ… **60fps WAAPI motion & step-by-step narrative beats** |
  261. | **Authoring Style** | Text DSL | Manual drag-and-drop | βœ… **Declarative text DSL + Live Editor Preview** |
  262. | **Return Flows & Cycles** | ⚠️ Rank distortion / tangling | Manual curve placement | βœ… **Cycle-safe returns (`<-`) & async event arcs (`~>`)** |
  263. | **AI Agent Reliability** | ⚠️ High hallucination | ❌ Coordinate hallucination | βœ… **Strict grammar AST + Self-healing MCP Server** |
  264. | **Architecture Governance** | ❌ None | ❌ None | βœ… **Built-in rules, drift detection (`markdy drift`), and C4 hierarchy** |
  265. | **Universal Ingestion** | ❌ Manual rewrite | ❌ Manual export | βœ… **1-Click Transpiler for Mermaid, D2, PlantUML, Compose, K8s, Terraform, Draw.io** |
  266. | **Core Footprint** | ~2 MB+ runtime | Heavy web app | βœ… **~14 kB core parser, zero dependencies** |
  267. </details>
  268. ---
  269. ## πŸ“¦ Component Responsibilities & Packages
  270. <details>
  271. <summary><b>Monorepo Package Directory &amp; Core Responsibilities</b></summary>
  272. <br>
  273. Markdy is architected as a modular monorepo where each package fulfills a focused responsibility:
  274. | Package | Responsibility | Primary Exports |
  275. |---|---|---|
  276. | **[`@markdy/core`](packages/core)** | **Compiler Core & AST Engine** | `parse()`, `compile()`, `formatScene()`, `diagnoseMarkdyCode()`, `validateArchitecture()`, `detectArchitectureDrift()`, `analyzeC4Model()`. Zero dependencies (~14 kB). |
  277. | **[`@markdy/renderer-dom`](packages/renderer-dom)** | **Motion Graphics & Rendering** | `createDiagram()`, `exportDiagramAsVectorSvg()`, `exportDiagramAsPng()`, `exportDiagramAsGif()`, `exportRouteShareCard()`. 60fps WAAPI timeline. |
  278. | **[`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. |
  279. | **[`@markdy/compat`](packages/compat)** | **Universal Ingestion Suite** | Transpilers for Mermaid, D2, PlantUML, Docker Compose, Kubernetes YAMLs, Terraform state, and Draw.io XML. |
  280. | **[`@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`. |
  281. | **[`@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. |
  282. | **[`@markdy/astro`](packages/astro)** & **[`@markdy/mdx`](packages/mdx)** | **Docs & Blog Integrations** | Zero-CLS, SSR-placeholder islands with viewport hydration for content sites. |
  283. | **[`@markdy/language-server`](packages/markdy-language-server)** | **Headless LSP Server** | Diagnostic publishing, hover docs, formatting, and completions for language clients. |
  284. | **[`@markdy/stdlib-systems`](packages/stdlib-systems)** | **Domain Vocabulary** | Semantic primitives for cloud, infrastructure, and distributed systems. |
  285. </details>
  286. ---
  287. ## πŸ” Detailed Features & Advanced Usage
  288. <details>
  289. <summary><b>🎨 18 Specialized Layout Engines &amp; 12 Editorial Themes</b></summary>
  290. <br>
  291. Markdy provides topological layout algorithms tailored to specific system patterns:
  292. - **Distributed Systems**: `architecture`, `flowchart`, `tree`, `state`, `sequence`
  293. - **Security & Structure**: `layers`, `nested`, `swimlane`, `quadrant`, `pyramid`
  294. - **Data & Product Loops**: `medallion`, `timeline`, `gantt`, `flywheel`, `loop`, `constellation`, `radar`, `venn`
  295. **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).
  296. πŸ‘‰ *[Explore all 33+ interactive scenes in the Live Gallery β†—](https://markdy.com/examples/)*
  297. </details>
  298. <details>
  299. <summary><b>πŸ”„ Universal Ingestion (1-Command Migration)</b></summary>
  300. <br>
  301. Convert existing diagrams and infrastructure configs into animated MarkdyScript scenes:
  302. ```bash
  303. markdy import flow.mmd --out flow.markdy # Mermaid.js Flowcharts & Sequences
  304. markdy import architecture.d2 --out arch.markdy # D2 Architecture & Sequence Diagrams
  305. markdy import system.puml --out system.markdy # PlantUML Component & Sequence Specs
  306. markdy import docker-compose.yml --out compose.markdy # Docker Compose Services & Networks
  307. markdy import k8s-manifests/ --out cluster.markdy # Kubernetes Ingress, Pods & Services
  308. markdy import terraform.tfstate --out infra.markdy # Terraform Provisioned State
  309. markdy import architecture.drawio --out diagram.markdy # Draw.io / diagrams.net XML
  310. ```
  311. </details>
  312. <a id="mcp-setup"></a>
  313. <details id="mcp-setup">
  314. <summary><b>πŸ€– AI Coding Agents &amp; Model Context Protocol (MCP) Setup (Cursor, VS Code, Claude, Antigravity)</b></summary>
  315. <br>
  316. 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`).
  317. ### ⚑ Quick MCP Server Setup & Installation
  318. | AI Environment | Setup Action | Method |
  319. |---|---|---|
  320. | **Cursor** | [![Install in Cursor](https://img.shields.io/badge/⚑_Install_in-Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white)](https://markdy.com/mcp/cursor) | **[1-Click Install β†—](https://markdy.com/mcp/cursor)** or [JSON Config](#cursor-setup) |
  321. | **VS Code / Copilot** | [![Install in VS Code](https://img.shields.io/badge/⚑_Install_in-VS_Code-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://markdy.com/mcp/vscode) | **[1-Click Install β†—](https://markdy.com/mcp/vscode)** or [JSON Config](#vscode-setup) |
  322. | **Claude Code & Desktop** | [![Setup in Claude](https://img.shields.io/badge/⚑_Setup_in-Claude-D97706?style=for-the-badge&logo=anthropic&logoColor=white)](#claude-setup) | **CLI (`claude mcp add`) & JSON** |
  323. | **Google Antigravity** | [![Setup in Antigravity](https://img.shields.io/badge/⚑_Setup_in-Antigravity-4285F4?style=for-the-badge&logo=google&logoColor=white)](#antigravity-setup) | **1-Command CLI (`agy mcp add`)** |
  324. | **Cline / Roo Code** | [![Config in Cline](https://img.shields.io/badge/Config_in-Cline-6366F1?style=for-the-badge)](#cline-setup) | **Config File (`cline_mcp_settings.json`)** |
  325. | **Windsurf / Cascade** | [![Config in Windsurf](https://img.shields.io/badge/Config_in-Windsurf-09B6A2?style=for-the-badge&logo=codeium&logoColor=white)](#windsurf-setup) | **Config File (`mcp_config.json`)** |
  326. | **Zed Editor** | [![Config in Zed](https://img.shields.io/badge/Config_in-Zed-4B5563?style=for-the-badge)](#zed-setup) | **Config File (`settings.json`)** |
  327. ---
  328. ### πŸ› οΈ Client Configuration Snippets
  329. <a id="claude-setup"></a>
  330. #### 1. Claude Code & Claude Desktop
  331. **Claude Code (Anthropic CLI):**
  332. ```bash
  333. claude mcp add markdy -- npx -y @markdy/mcp-server
  334. ```
  335. **Claude Desktop GUI (`claude_desktop_config.json`):**
  336. ```json
  337. {
  338. "mcpServers": {
  339. "markdy": {
  340. "command": "npx",
  341. "args": ["-y", "@markdy/mcp-server"]
  342. }
  343. }
  344. }
  345. ```
  346. <a id="cursor-setup"></a>
  347. <a id="vscode-setup"></a>
  348. #### 2. Cursor & VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)
  349. ```json
  350. {
  351. "mcpServers": {
  352. "markdy": {
  353. "command": "npx",
  354. "args": ["-y", "@markdy/mcp-server"]
  355. }
  356. }
  357. }
  358. ```
  359. <a id="antigravity-setup"></a>
  360. #### 3. Google Antigravity & Gemini CLI
  361. **Via 1-Command CLI:**
  362. ```bash
  363. agy mcp add markdy -- npx -y @markdy/mcp-server
  364. ```
  365. **Or via Config File (`~/.gemini/antigravity/mcp_config.json` or `.agents/mcp_config.json`):**
  366. ```json
  367. {
  368. "mcpServers": {
  369. "markdy": {
  370. "command": "npx",
  371. "args": ["-y", "@markdy/mcp-server"]
  372. }
  373. }
  374. }
  375. ```
  376. <a id="cline-setup"></a>
  377. #### 4. Cline & Roo Code (`cline_mcp_settings.json`)
  378. ```json
  379. {
  380. "mcpServers": {
  381. "markdy": {
  382. "command": "npx",
  383. "args": ["-y", "@markdy/mcp-server"]
  384. }
  385. }
  386. }
  387. ```
  388. <a id="windsurf-setup"></a>
  389. #### 5. Windsurf / Cascade (`~/.codeium/windsurf/mcp_config.json`)
  390. ```json
  391. {
  392. "mcpServers": {
  393. "markdy": {
  394. "command": "npx",
  395. "args": ["-y", "@markdy/mcp-server"]
  396. }
  397. }
  398. }
  399. ```
  400. <a id="zed-setup"></a>
  401. #### 6. Zed Editor (`settings.json`)
  402. ```json
  403. {
  404. "context_servers": {
  405. "markdy": {
  406. "command": {
  407. "path": "npx",
  408. "args": ["-y", "@markdy/mcp-server"]
  409. }
  410. }
  411. }
  412. }
  413. ```
  414. ---
  415. ### 🧰 Available Agent Tools & Resources
  416. - πŸ” `validate_markdy_code`: Check syntax, unresolved node references, and cycle rules.
  417. - πŸ’‘ `diagnose_markdy_syntax`: Detailed diagnostics with exact line numbers and remediation steps.
  418. - 🩹 `fix_markdy_code`: Self-healing code repair that fixes common syntax mistakes and formats AST.
  419. - πŸ”„ `transpile_to_markdy`: Convert Mermaid, D2, PlantUML, Docker Compose, Kubernetes, Terraform, or Draw.io into valid MarkdyScript.
  420. - 🧭 `explain_architecture`: Structural topology summaries, component role counts, and governance health metrics.
  421. - πŸ’¬ `generate_markdy_prompt`: Optimal LLM system prompts and grammar constraints for AI coding agents.
  422. - πŸ“¦ `get_architecture_catalog`: Golden architecture templates with full runnable MarkdyScript code.
  423. - ⚑ `get_markdy_intellicode`: Zero-dependency predictive completion and proactive recommendations.
  424. - πŸ“š `markdy://spec/agent-reference`: Full AST grammar reference and token catalog.
  425. - πŸ“ `markdy://spec/grammar-rules`: Grammar conventions and cycle-safe routing rules.
  426. - πŸ›οΈ `markdy://governance/rules`: Architecture rules (Well-Architected, cycle bounds, layer separation).
  427. - πŸ“¦ `markdy://templates/catalog`: 33 production-grade architecture blueprints.
  428. πŸ‘‰ *[Read the Full AI Agent Reference Guide (`AGENT.md`) β†—](https://markdy.com/agent/)*
  429. </details>
  430. ---
  431. ## 🚦 Verification Gates & Quality Engineering
  432. <details>
  433. <summary><b>Automated Verification Gates &amp; CI/CD Quality Pipeline</b></summary>
  434. <br>
  435. Every pull request and build must pass the automated full-cycle verification pipeline:
  436. | Command | Verification Gate | Focus Area |
  437. |---|---|---|
  438. | `pnpm test` | **Unit & Integration Suite** | AST parser, compiler math, layout solvers, CLI |
  439. | `pnpm test:visual` | **Automated Visual Gate** | Headless Chrome + Pixelmatch against golden baselines (`tests/visual-baselines/`) |
  440. | `pnpm test:perf` | **Sub-Frame Performance Gate** | Chrome DevTools Protocol tracing (sub-40ms render, <25MB JS heap) |
  441. | `pnpm verify:examples` | **Canonical Showcase Gate** | 33 production blueprints compile with zero warnings |
  442. | `cleanroom-guard check` | **Anti-Leak & Clean-Room** | Pre-commit secret scanning and clean-room zero-footprint protection |
  443. </details>
  444. ---
  445. ## πŸ“– Documentation Links
  446. | Guide | Description |
  447. |---|---|
  448. | **[Syntax Reference (SYNTAX.md)](docs/SYNTAX.md)** | Full DSL grammar, flow operators, selectors, cues, and player settings |
  449. | **[Step-by-Step Tutorial (TUTORIAL.md)](docs/TUTORIAL.md)** | Step-by-step guide from basic flows to multi-beat kinetic scenes |
  450. | **[AI Agent Guide (AGENT.md)](AGENT.md)** | LLM system prompts, token rules, and anti-patterns |
  451. | **[Architecture Internals (ARCHITECTURE.md)](docs/ARCHITECTURE.md)** | Compiler pipelines, WAAPI loop, and orthogonal routing geometry |
  452. | **[VS Code Extension Guide](packages/vscode/README.md)** | Shortcuts, settings, and IDE features |
  453. ---
  454. <p align="center">
  455. <img src="docs/images/mascot/male-markdy.webp" width="64" height="64" alt="Markdy Mascot" /><br>
  456. <strong>Empowering engineers and AI agents to create living architecture diagrams.</strong><br>
  457. <sub>Built with ❀️ by <a href="https://hoangyell.com">Hoang Yell</a> &amp; the community. Distributed under the <a href="LICENSE">MIT License</a>.</sub>
  458. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.