Markdy Documentation

60-Second Quickstart

Install the Markdy CLI, create your first .markdy scene, and compile it to an interactive HTML preview:

# 1. Install Markdy CLI globally (or run with npx)
npm install -g @markdy/cli

# 2. Render and open your animated architecture diagram in the browser
markdy render architecture.markdy --open

Here is a complete, runnable architecture.markdy scene:

scene theme=paper layout=LR

client WebBrowser "Client App"
gateway ApiGateway "API Gateway"
cache RedisCluster "Redis Cache"
database PostgresDB "PostgreSQL (Master)"

group caching: RedisCluster
group persistence: PostgresDB

beat setup "Initial System Reveal":
  show $nodes stagger=60ms

beat flow "Cache Lookup & Fallback":
  WebBrowser -> ApiGateway "GET /product/42"
  ApiGateway -> RedisCluster "1. Check Cache (MISS)"
  ApiGateway -> PostgresDB "2. Query Database"
  ApiGateway -> RedisCluster "3. Populate Cache"
  WebBrowser <- ApiGateway "200 OK (JSON)"

Core Philosophy

Markdy is diagram-native: MarkdyScript isn't a config format bolted onto a chart library — it's a small DSL purpose-built for describing systems, and every part of the toolchain treats it as a first-class language:

• Diagrams as code. A scene is plain text, so it lives in your repo, reviews in a pull request, and diffs like any other source file — no binary design-tool exports to go stale.
• Parsing is separate from rendering. @markdy/core compiles MarkdyScript into a render plan (positioned nodes, routed edges, timed cues); @markdy/renderer-dom turns that plan into DOM and SVG. Anything that can consume the render plan can become a renderer.
• Motion, not just layout. Diagrams are told through beats — discrete timeline steps — driven by the browser's native Web Animations API, so playback is seekable and scrubbable instead of a single static export.
• Semantic nodes over generic boxes. Declaring a node's kind (service, database, queue, ...) carries meaning the renderer uses for styling and iconography, instead of hand-picking shapes and colors per node.

Scene Declaration

Every Markdy script starts with an optional scene header declaring canvas metadata, visual theme, and reading direction:

scene theme=paper layout=LR width=1280 height=720

Semantic Node Kinds

Markdy uses semantic node declarations. Rather than generic boxes, each node kind automatically receives domain-specific styling, iconography, and rendering metadata:

Groups & Subsystem Boundaries

Declare logical architectural boundaries, network VPCs, Kubernetes namespaces, or cluster tiers using the group keyword:

# Syntax: group <group_id> [label="Display Title"]: <node1> <node2> ...
group ingress "Public Ingress Tier": WebClient ApiGateway
group storage "Data Persistence": RedisCluster PostgresDB

Flow Operators & Routing

Markdy provides 6 expressive flow operators to distinguish synchronous requests, asynchronous event streams, and streaming data pipes:

Multi-Hop Chaining

Chain multi-stage operations cleanly on a single line:

WebApp -> ApiGateway "POST /checkout" -> PaymentWorker "charge" -> PostgresDB "save"

Timeline Beats & Motion Choreography

Markdy diagrams are animated through discrete beats. Each beat represents a step in a walkthrough, story, or lifecycle:

Universal Ingestion & 1-Click Migration

Convert existing static architecture files directly into animated MarkdyScript using @markdy/compat:

markdy import flow.mmd --out flow.markdy

markdy import docker-compose.yml

markdy import k8s-manifest.yaml

markdy import terraform.tfstate

AI Coding Agents & Official MCP Server

Connect Claude Desktop, Cursor, Antigravity, or any LLM agent to the official Model Context Protocol server:

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

AI agents can access markdy.com/AGENT.md and call validate_markdy_script to test and self-heal diagrams during generation.

Architecture Governance & CI/CD Linter

Integrate automated Well-Architected governance checks in your continuous integration pipeline:

Framework Integrations: JavaScript, Astro, MDX & React

import { createDiagram } from "@markdy/renderer-dom";

const diagram = createDiagram({
  container: document.getElementById("scene"),
  code: sceneCode,
});

diagram.play();

import { Markdy } from "@markdy/astro";

<Markdy code={sceneCode} autoplay />

```markdy
scene theme=paper
client Browser -> service Api -> database DB
```

Ecosystem Package Directory