HoangYell/markdy-com

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

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.

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"

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) ↗

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 ↗

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 ↗

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 ↗

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 ↗

• @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).

Markdy is architected as a modular monorepo where each package fulfills a focused responsibility:

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 ↗

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

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

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)

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"]
    }
  }
}

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

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"]
    }
  }
}

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

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

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

• 🔍 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) ↗

Every pull request and build must pass the automated full-cycle verification pipeline: