KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #codex #developer-tools #ai-agents #cli #claude-code #ios #open-source #ai-agent #python #mcp #react

markdy-com

★ 83 Open GitHub ↗

Open-source text-to-motion animation DSL. Write MarkdyScript to render animated scenes in the browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Markdy 
 Open-source DSL for animated architecture & system diagrams. 
 Write diagram-native MarkdyScript → get browser-native animated architecture diagrams.

<a href="https://markdy.com/playground/">✨ Try the Interactive Playground</a>

---

## What is Markdy?

**Markdy is a framework-agnostic, diagram-native DSL for animated architecture and system diagrams.** Declare semantic nodes, groups, beats, flows, and cues in MarkdyScript — Markdy handles layout, edge routing, timing, and browser-native rendering with the Web Animations API. No Canvas, no GSAP, no bloated dependencies.

> Markdy is built for **animated architecture diagrams and system-design explainers**.
> The built-in vocabulary expresses architecture, cloud, Kubernetes, CI/CD, auth, data, messaging, state-machine, and flow diagrams.
>
> If you are searching for a **Mermaid alternative with animation**, **animated architecture diagrams**, **diagram as code**, **AI-generated diagrams**, **text-to-diagram**, **architecture as code**, or **docs-as-code motion graphics**, Markdy is designed for that workflow.

```markdy
scene "Request path" theme=paper
layout LR

browser Client
service API
database DB

beat main "Trace the request":
 show $nodes
 frame Client API zoom=1.12
 Client -> API "GET /items" -> DB "query"
 Client <- API "200 OK"
```

### Key Features

| Feature | Detail |
|---|---|
| **Zero-dep parser** | `@markdy/core` is pure TypeScript — no DOM, no runtime deps |
| **Web-native renderer** | Web Animations API + CSS transforms. No Canvas, no GSAP |
| **Diagram-native DSL** | Declare nodes, `group`s, and `beat`s; the engine handles layout, routing, timing, and rendering |
| **Auto-layout + routing** | Rank-based layout and orthogonal edge routing are built in — no coordinates required |
| **Flow operators** | `->` request, `<-` response, `~>` event, `--` dependency, each with its own edge style |
| **Beats + cues** | Sequence reveals with `beat` blocks, captions, and `show`/`hide`/`glow`/`focus`/`frame` cues; run cues together with `&` |
| **Semantic node cards** | Kind-aware SVG glyphs for browsers, services, gateways, queues, workers, databases, storage, CDN, security, platform, and more |
| **Patterns, styles, groups** | Reusable `pattern name(...)` + `use`, per-node `style`, and `group` fan-out with `stagger` |
| **Semantic themes** | `paper`, `editorial`, `nebula`, `midnight`, `blueprint`, and `graphite` — consistent colors per node role and edge kind |
| **Focused diagram modes** | Opt-in `architecture`, `flowchart`, `tree`, `state`, `sequence`, and `constellation` layouts |
| **Technical diagram vocabulary** | Optional systems pack adds architecture nodes, visual primitives, and labeled flows for software-engineering diagrams |
| **Astro-ready** | `<Markdy />` island that hydrates on viewport entry |
| **AI-agent friendly** | Structured DSL that LLMs can generate, validate, and iterate on ([Agent Guide](https://markdy.com/agent/)) |

---

## Packages

| Package | Description | Size |
|---|---|---|
| [`@markdy/core`](packages/core) | Parser + AST types (zero runtime deps) | ~12 KB |
| [`@markdy/renderer-dom`](packages/renderer-dom) | Web Animations API renderer | ~22 KB |
| [`@markdy/cli`](packages/cli) | CLI for linting, formatting, explaining, rendering, and local previews | Node package |
| [`@markdy/language-server`](packages/markdy-language-server) | Shared LSP server for editors and IDE integrations | Node package |
| [`@markdy/astro`](packages/astro) | Astro island component | ~2 KB |
| [`@markdy/mdx`](packages/mdx) | MDX remark plugin + lazy React diagram component | ~4 KB |
| [`@markdy/stdlib-systems`](packages/stdlib-systems) | Architecture nodes, visual primitives, and request/response/emit flows for animated diagrams | <1 KB |

---

## Search intent: when to use Markdy

Developers usually discover this problem through many names:

- "Mermaid but animated"
- "Markdown animation"
- "animated diagrams as code"
- "text-to-diagram with motion"
- "AI-generated architecture diagrams"
- "sequence diagrams for developer docs"
- "architecture visualization for docs"
- "docs-as-code animation"
- "LLM-friendly visual DSL"

Use Markdy when you want a diagram or explainer that is:

- **Text-first** — reviewable in pull requests and easy for AI agents to edit.
- **Time-based** — requests, responses, events, phased reveals, and emphasis happen in sequence.
- **Browser-native** — rendered with DOM/CSS/Web Animations instead of screenshots or video exports.
- **Documentation-friendly** — works in Astro, MDX, static sites, and package READMEs.

Use Mermaid, PlantUML, D2, Graphviz, Excalidraw, or draw.io when you need static diagrams. Use Markdy when the story depends on motion.

---

## CLI install note

`@markdy/cli` provides the `markdy` binary, but a normal project install does not put that binary on your shell PATH.

Use one of these depending on where you installed it:

```sh
npx markdy render examples/showcase/bullet-reveal.markdy --out examples/xscene.html
npm exec markdy render examples/showcase/bullet-reveal.markdy --out examples/xscene.html
npm i -g @markdy/cli
```

`--out` writes the generated HTML to the path you pass in, relative to the current working directory unless you give an absolute path.

## Ecosystem map (text)

```text
@markdy/core
  -> parses MarkdyScript into AST

@markdy/renderer-dom
  -> renders AST in the browser with Web Animations API

@markdy/astro, @markdy/mdx
  -> host integrations for site/content workflows

@markdy/cli
  -> lint, format, render, explain, and preview commands

@markdy/language-server
  -> diagnostics, completion, and hover in editors

@markdy/stdlib-systems
  -> optional node vocabulary manifest for architecture and technical diagrams
```

## Output preview

The dedicated playground mirrors this workflow: choose a shipped `.markdy` scene, edit syntax-highlighted MarkdyScript, resize the editor/preview split, and watch the embedded architecture preview update in the browser.

To preview a full scene result locally, run:

```sh
npx markdy render examples/showcase/url-shortener-architecture.markdy --out scene.html
```

## Quick Start

### Write a `.markdy` scene

Create `architecture.markdy`:

```markdy
scene "Request" theme=paper
layout LR

browser WebApp
service CheckoutApi
database OrdersDb

beat main:
 show $nodes stagger=80ms
 WebApp -> CheckoutApi "GET /orders" -> OrdersDb "query"
 WebApp <- CheckoutApi "200 OK"
```

Preview or validate it with the CLI:

```sh
pnpm add -D @markdy/cli
pnpm markdy lint architecture.markdy
pnpm markdy render architecture.markdy --out architecture.html
```

### Astro / MDX

```sh
pnpm add @markdy/astro
```

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

const code = `
  scene "Request" theme=paper width=800 height=400
  browser WebApp
  service CheckoutApi
  beat main:
    show $nodes
    WebApp -> CheckoutApi "GET /users"
`;
---

<Markdy code={code} width={800} height={400} bg="#07111f" autoplay />
```

### Parser Only (Node.js / Edge)

```ts
import { parse, ParseError } from "@markdy/core";

try {
  const ast = parse(source);
  console.log(ast.nodes);  // { API: { kind: "service", ... } }
  console.log(ast.beats);  // [{ name: "main", cues: [...] }]
} catch (e) {
  if (e instanceof ParseError) {
    console.error(`Line ${e.line}: ${e.message}`);
  }
}
```

---

## DSL at a Glance

Full reference: **[docs/SYNTAX.md](docs/SYNTAX.md)** · Step-by-step tutorial: **[docs/TUTORIAL.md](docs/TUTORIAL.md)** · Getting started: **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)** · Guides: **[docs/GUIDES.md](docs/GUIDES.md)** · Comparisons: **[docs/COMPARISONS.md](docs/COMPARISONS.md)** · Troubleshooting: **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** · AI agent guide: **[markdy.com/agent](https://markdy.com/agent/)**

### Nodes + Beats + Flows

```markdy
scene "Order Flow" theme=paper
layout LR

browser WebApp
service OrderService
database OrdersDb

beat main:
 show $nodes stagger=80ms
 WebApp -> OrderService "POST /order" -> OrdersDb "persist"
 WebApp <- OrderService "201 Created"
```

### Groups + Patterns

```markdy
group storage: Redis OrdersDb

pattern lookup(client, store):
 $client -> $store "lookup"
 $client <- $store "result"

beat read:
  use lookup(OrderService, Redis)
```

### Flow operators

| Operator | Edge kind | Rendered as |
|---|---|---|
| `->` | request | solid arrow |
| `<-` | response | dashed arrow, drawn back to the caller |
| `~>` | event | dotted arrow |
| `--` | dependency | thin link |

### Cues

Cues live inside a `beat` and are scheduled in order; put `&` between two cues to run them together.

| Cue | Description | Key parameters |
|---|---|---|
| `show` | Reveal nodes or groups | `stagger`, `dur` |
| `hide` | Fade nodes out | `dur` |
| `glow` | Emphasize with a colored glow | `color`, `strength`, `dur` |
| `focus` | Pulse-scale to draw attention | `zoom`, `dur` |
| `frame` | Move the scene camera to nodes or groups | `zoom`, `dur` |
| `use` | Expand a `pattern` | pattern args |

Selectors: `$nodes` targets every node, `$edges` targets structural and animated edges, and a group name targets its members. Themes: `paper` (light default), `editorial`, `nebula`, `midnight`, `blueprint`, and `graphite`.

---

## API Reference

### `parse(source: string, opts?: ParseOptions): DiagramAST`

Parses MarkdyScript source into a typed diagram AST. Throws `ParseError` with line numbers on structural errors. Pure function with no side effects — runs in Node.js, Deno, edge runtimes, or the browser.

```ts
interface ParseOptions {
  parseOnly?: boolean;  // Skip layout/schedule compilation; parse structure only.
}
```

`DiagramAST` exposes `ast.meta`, `ast.nodes`, `ast.edges`, `ast.groups`, `ast.patterns`, `ast.beats`, and `ast.diagnostics[]` (soft warnings such as unknown scene properties). Call `compile(ast)` to produce a `RenderPlan` with positioned nodes, routed edges, and scheduled cues. See [docs/AGENT.md](docs/AGENT.md) for the full shape.

### `createDiagram(options: DiagramOptions): Diagram`

Creates a DOM-based animated diagram.

```ts
interface DiagramOptions {
  container: HTMLElement;    // Mount point
  code: string;             // MarkdyScript source
  autoplay?: boolean;       // Start immediately (default: true)
  loop?: boolean;           // Loop at end (default: true)
  copyright?: boolean;      // "Powered by Markdy" badge (default: true)
  progressBar?: boolean;    // Deprecated: use sceneBoundaryProgress
  sceneBoundaryProgress?: boolean; // Rainbow border progress bar (default: true)
  playbackRate?: number;    // Timeline speed multiplier (default: 1)
  onWarning?: (w: Diagnostic) => void;                 // Soft parse warnings
  onTimeUpdate?: (seconds: number, duration: number) => void;
  onPlayStateChange?: (playing: boolean) => void;
}

interface Diagram {
  play(): void;             // Start / resume
  pause(): void;            // Pause at current position
  seek(seconds: number): void;  // Jump to time
  setPlaybackRate(rate: number): void; // Set timeline speed, e.g. 0.5 or 2
  playbackRate(): number;    // Current timeline speed multiplier
  seekToBeat(name: string): void;  // Jump to a named beat
  destroy(): void;          // Remove DOM + cancel animations
}
```

### `<Markdy />` (Astro Component)

| Prop | Type | Default | Description |
|---|---|---|---|
| `code` | `string` | *(required)* | MarkdyScript source |
| `width` | `number` | `800` | Placeholder width (px) |
| `height` | `number` | `400` | Placeholder height (px) |
| `bg` | `string` | `"white"` | Placeholder background colour |
| `assets` | `Record<string, string>` | `{}` | Asset URL overrides |
| `autoplay` | `boolean` | `true` | Auto-play when fully visible in viewport |
| `loop` | `boolean` | `true` | Loop the animation when it ends |
| `copyright` | `boolean` | `true` | Show a "Powered by Markdy" badge below the animation |
| `progressBar` | `boolean` | `true` | Show a rainbow progress bar around the viewport border |
| `sceneBoundaryProgress` | `boolean` | `progressBar` | Preferred flag for the rainbow scene-boundary progress bar |
| `playbackRate` | `number` | `1` | Timeline speed multiplier |
| `class` | `string` | — | CSS class for outer wrapper |

---

## Architecture

See **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** for technical details.

```
 MarkdyScript source
 │
 ▼
 ┌─────────────┐
 │ @markdy/core │ parse() → DiagramAST
 │ (parser) │ Pure TS, zero deps
 └──────┬──────┘
 │ DiagramAST
 ▼
 ┌──────────────────┐
 │ @markdy/renderer │ createDiagram() → Diagram
 │ -dom │ WAAPI + rAF loop
 └──────┬───────────┘
 │ Diagram
 ▼
 ┌──────────────────┐
 │ @markdy/astro │ <Markdy /> island
 │ (optional) │ SSR placeholder + IntersectionObserver
 └──────────────────┘
```

All WAAPI animations are permanently paused. A `requestAnimationFrame` loop manually sets `anim.currentTime = sceneMs` each frame. This avoids browser-specific quirks with `startTime`-based resumption and enables reliable `seek()`.

---

## Development

```sh
git clone https://github.com/HoangYell/markdy-com.git
cd markdy-com
pnpm install
pnpm build
pnpm test
```

### Project Structure

```
packages/
  core/              @markdy/core         — Parser + AST types (zero deps)
  renderer-dom/      @markdy/renderer-dom — WAAPI renderer
  cli/               @markdy/cli          — CLI for local authoring workflows
  astro/             @markdy/astro        — Astro island component
  mdx/               @markdy/mdx          — MDX plugin + React diagram component with viewport hydration
  stdlib-systems/    @markdy/stdlib-systems — System-diagram node vocabulary
  markdy-language-server/ @markdy/language-server — Shared LSP server for editors
website/               Official markdy.com playground & website (Astro)
docs/
  SYNTAX.md          Full DSL reference
  TUTORIAL.md        Step-by-step human tutorial
  AGENT.md           Guide for AI agents / LLMs
  ARCHITECTURE.md    Technical deep dive
```

### Scripts

| Command | Description |
|---|---|
| `pnpm build` | Build all packages and website |
| `pnpm test` | Run all tests (vitest) |
| `pnpm typecheck` | Type-check all packages |
| `pnpm clean` | Remove all `dist/` directories |
| `pnpm run release <version>` | Full release train: commit/bump/changelog/validate → release PR → merge → tag → publish |

### Deployment (Cloudflare)

The project is deployed via Cloudflare Pages (Workers Assets).
- **Project Name:** `markdy-com`
- **Build command:** `pnpm build`
- **Deploy command:** `cd website && npx wrangler deploy`
- **Path:** `/` (repo root)

---

## Documentation

| Document | Audience | Description |
|---|---|---|
| **[SYNTAX.md](docs/SYNTAX.md)** | All users | Complete DSL language reference |
| **[TUTORIAL.md](docs/TUTORIAL.md)** | Humans | Step-by-step guide from zero to animated scenes |
| **[AGENT.md](docs/AGENT.md)** | AI agents / LLMs | Maintained source for the hosted [agent guide](https://markdy.com/agent/) and [LLM context bundle](https://markdy.com/llms-full.txt) |
| **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** | Contributors | Technical design, renderer internals, AST shape |
| **[CONTRIBUTING.md](CONTRIBUTING.md)** | Contributors | Dev setup, code style, PR guidelines |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

---

## License

markdy-com

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README