Markdy Com

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. Access production architectural templates, custom diagram kits, and direct support via GitHub Sponsors & Pro Blueprints.

---

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