markdy-com

KO | EN

gitlite — search

#hacktoberfest #typescript #llm #android #machine-learning #rust #deep-learning #docker #awesome #kubernetes #security #pytorch #ios #open-source

(★ 84)

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

파일 탐색기

최종 버전 다운로드 (.zip)

- settings.json
- - bug_report.yml
  - config.yml
  - feature_request.yml
- - ci.yml
  - release.yml
- copilot-instructions.md
- dependabot.yml
- FUNDING.yml
- PULL_REQUEST_TEMPLATE.md
- - markdy-ai-agent-workflow.webp
  - markdy-framework-integrations.webp
  - markdy-governance-audit.webp
  - markdy-layouts-themes.webp
  - markdy-split-editor.webp
  - markdy-studio-hero.webp
  - markdy-themes-showcase.webp
  - markdy-universal-ingestion.webp
  - markdy-vs-mermaid-comparison.webp
  - scene-cicd-pipeline.webp
  - scene-concurrency-decision-flowchart.webp
  - scene-concurrency-fanin.webp
  - scene-consistent-hash-tree.webp
  - scene-data-flywheel.webp
  - scene-database-radar.webp
  - scene-distributed-2pc-state.webp
  - scene-ecommerce-swimlanes.webp
  - scene-editorial-api-platform.webp
  - scene-engineering-roadmap.webp
  - scene-fintech-governance.webp
  - scene-kubernetes-cluster.webp
  - scene-lakehouse-medallion.webp
  - scene-nebula-constellation.webp
  - scene-nested-security.webp
  - scene-oauth-oidc-flow.webp
  - scene-oauth-pkce-sequence.webp
  - scene-osi-layers.webp
  - scene-platform-milestones-timeline.webp
  - scene-platform-pyramid.webp
  - scene-product-market-fit-venn.webp
  - scene-sketchy-whiteboard.webp
  - scene-strategic-quadrant.webp
  - scene-terminal-cli.webp
  - scene-twitter-timeline.webp
  - scene-url-shortener.webp
  - scene-youtube-pipeline.webp
  - scene-zero-trust-paved-road.webp
- - LAUNCH_PLAN.md
  - PRODUCT_HUNT_LAUNCH.md
  - SHOW_HN_DRAFT.md
  - TUTORIAL_DRAFT_DEVTO.md
  - X_THREAD_DRAFT.md
- AGENT.md
- ARCHITECTURE.md
- COMPARISONS.md
- CONTENT_ROADMAP.md
- GETTING_STARTED.md
- GITHUB_PACKAGES.md
- GUIDES.md
- SYNTAX.md
- TROUBLESHOOTING.md
- TUTORIAL.md
- - .stackblitzrc
  - astro.config.mjs
  - package.json
- - cicd-delivery-pipeline.markdy
  - concurrency-decision-flowchart.markdy
  - consistent-hash-tree.markdy
  - cross-functional-swimlanes.markdy
  - data-flywheel-loop.markdy
  - database-radar-benchmark.markdy
  - distributed-2pc-state.markdy
  - editorial-architecture.markdy
  - editorial-flowchart.markdy
  - editorial-sequence.markdy
  - editorial-state.markdy
  - editorial-tree.markdy
  - engineering-gantt-roadmap.markdy
  - enterprise-value-pyramid.markdy
  - fanin-concurrency-bottleneck.markdy
  - fintech-governance-engine.markdy
  - kubernetes-cluster-architecture.markdy
  - lakehouse-medallion-pipeline.markdy
  - microservices-mesh-ingest.markdy
  - nebula-constellation.markdy
  - nested-security-perimeter.markdy
  - oauth-oidc-login-flow.markdy
  - oauth-pkce-sequence.markdy
  - osi-abstraction-layers.markdy
  - platform-milestones-timeline.markdy
  - product-market-fit-venn.markdy
  - secure-paved-road-enforcement.markdy
  - sketchy-whiteboard-flow.markdy
  - strategic-decision-quadrant.markdy
  - technical-diagram-vocabulary.markdy
  - terminal-cli-architecture.markdy
  - twitter-timeline-service.markdy
  - url-shortener-architecture.markdy
  - youtube-processing-pipeline.markdy
- 01-first-diagram.markdy
- 02-flow-operators.markdy
- 03-beats-and-groups.markdy
- 04-patterns-and-styles.markdy
- 05-universal-ingestion.markdy
- 06-architecture-governance.markdy
- 07-flywheel-loop.markdy
- 08-medallion-lakehouse.markdy
- 09-strategic-quadrant.markdy
- 10-cross-functional-swimlane.markdy
- 11-enterprise-pyramid.markdy
- 12-multi-axis-radar.markdy
- 13-secure-paved-road.markdy
- 14-fanin-queue-bottleneck.markdy
- 15-project-timeline.markdy
- 16-gantt-roadmap.markdy
- 17-venn-overlap.markdy
- 18-layer-stack.markdy
- 19-nested-containment.markdy
- 20-player-configuration.markdy
- README.md
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
  - tsup.config.ts
  - vitest.config.ts
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
  - tsup.config.ts
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
  - tsup.config.ts
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
  - tsup.config.ts
  - vitest.config.ts
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
  - tsup.config.ts
- - LICENSE
  - package.json
  - README.md
  - THIRD_PARTY_LICENSES.md
  - tsconfig.json
  - tsup.config.ts
  - vitest.config.ts
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
  - tsup.config.ts
- system-prompt.json
- system-prompt.md
- capture-harness-diagrams.mjs
- chrome-devtools-adaptive-test.mjs
- convert-brand-assets.mjs
- generate-all-assets.mjs
- generate-all-decorated-images.mjs
- github.sh
- publish-packages.mjs
- regenerate-all.ts
- release.sh
- verify-examples.ts
- - _headers
  - favicon.svg
  - icon.svg
  - og-image.webp
  - robots.txt
  - site.webmanifest
- - chrome-devtools-audit.mjs
  - comprehensive-mcp-audit.mjs
  - run-mcp-devtools.mjs
  - validate-playground-refactor.mjs
- astro.config.mjs
- package.json
- tsconfig.json
- wrangler.jsonc
.editorconfig
.env.example
.gitattributes
.gitignore
.npmrc
.prettierrc
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
SECURITY.md
tsconfig.base.json

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<a href="https://markdy.com">
 <img src="docs/images/mascot/markdy-com.webp" width="380" alt="markdy.com" />
 </a> 
 Open-source DSL for animated architecture &amp; system diagrams. 
 Write diagram-native MarkdyScript → get browser-native motion graphics that stay version-controlled, PR-friendly, and AI-native.

<a href="https://markdy.com/playground/">⚡ Launch Studio Playground</a> &nbsp;•&nbsp;
 <a href="https://markdy.com/docs/">📖 Documentation</a> &nbsp;•&nbsp;
 <a href="https://markdy.com/examples/">🌟 17+ Examples Gallery</a> &nbsp;•&nbsp;
 <a href="https://markdy.com/agent/">🤖 AI &amp; Agent Guide</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, zero 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 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 & engines** | `@markdy/core` is pure TypeScript — AST parser, architecture linter, semantic classifier, AST diff engine, brand theme generator, and URL state codec |
| **Web-native renderer** | Web Animations API + CSS transforms. No Canvas, no GSAP, zero dependencies |
| **17 Specialized Layout Engines** | `architecture` (LR, RL, TB, BT), `flowchart`, `tree`, `state`, `sequence`, `constellation`, `loop`/`flywheel`, `medallion`, `quadrant`, `swimlane`, `pyramid`, `radar`, `timeline`, `gantt`, `venn`, `grid`, and `radial` |
| **8 Semantic Themes** | `paper`, `editorial`, `nebula`, `midnight`, `blueprint`, `graphite`, `terminal` (CLI/TUI dark mode), and `sketchy` (editorial hand-drawn) |
| **Universal Ingestion** | Instant transpilers for Mermaid, draw.io, Docker Compose, Kubernetes manifests, and Terraform state into animated MarkdyScript scenes (`markdy import`) |
| **Brand Theme Generator** | Extract and generate WCAG-compliant light and dark themes from any brand hex color (`generateThemeFromBrand()`) |
| **Output Size Presets** | 8 standard export presets (`doc-inline`, `doc-wide`, `slide-16x9`, `slide-4x3`, `social-og`, `social-square`, `print-a4`, `print-letter`) |
| **Architecture Governance** | Built-in Well-Architected validation: layer boundaries, deadlock cycle detection, gateway checks, and isolation rules (`markdy lint --arch-rules`) |
| **Semantic AST Diffing** | Compares architecture versions, outputs Markdown audit tables, and generates animated evolution scenes (`markdy diff`) |
| **Media Exporters** | Zero-dep GIF89a encoder with LZW compression for animated GitHub READMEs and vector SVG export for Figma |
| **Model Context Protocol (MCP)** | `@markdy/mcp-server` equips Claude, Cursor, Antigravity, and AI agents with validation, transpilation, and architecture explanation tools |
| **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 collision-aware orthogonal Manhattan 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, hub, station, medals, and more |
| **Editorial Callouts** | Italic-serif annotations with dashed Bézier leaders, landing dots, and color intents (`accent`, `muted`, `neutral`) |
| **Astro & MDX Ready** | `<Markdy />` islands that hydrate on viewport entry with zero layout shift |
| **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 diff, architecture linter, semantic classifier, URL codec (zero runtime deps) | ~14 KB |
| [`@markdy/compat`](packages/compat) | Universal transpilers (Mermaid, Docker Compose, Kubernetes, Terraform) & snapshot gates | ~8 KB |
| [`@markdy/renderer-dom`](packages/renderer-dom) | Web Animations API renderer, GIF89a encoder, SVG exporter, presentation controller | ~24 KB |
| [`@markdy/cli`](packages/cli) | CLI for linting, architecture rules, formatting, importing, diffing, explaining, and sharing | Node package |
| [`@markdy/mcp-server`](packages/mcp-server) | Official Model Context Protocol (MCP) server for AI coding assistants & agents | 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 |

> 📦 **Registries**: All packages are published to both [npmjs.com](https://www.npmjs.com) and [GitHub Packages](https://github.com/HoangYell/markdy-com/packages). See the [GitHub Packages Guide](docs/GITHUB_PACKAGES.md) for npm/pnpm authentication and configuration.

---

## 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/url-shortener-architecture.markdy --out examples/xscene.html
npm exec markdy render examples/showcase/url-shortener-architecture.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.

---

## 🏛️ 17 Specialized Diagram Layout Engines
 
Explore the [Live Examples Gallery](https://markdy.com/examples/) or click any preview below to open it in the [Markdy Studio](https://markdy.com/playground/):
 
| ⚡ Systems &amp; High Concurrency | 🚦 Decision Logic &amp; Consensus |
|:---:|:---:|
| **Architecture (Cache-Aside Pattern)** Sub-2ms Redis cache redirection &amp; database fallback <a href="https://markdy.com/playground/"><img src="docs/images/scene-url-shortener.webp" alt="Architecture (Cache-Aside Pattern)" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **Concurrency Strategy Flowchart** Thread safety, CAS atomics &amp; mutex contention <a href="https://markdy.com/playground/"><img src="docs/images/scene-concurrency-decision-flowchart.webp" alt="Concurrency Strategy Flowchart" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **Consistent Hash Ring Tree** `O(k/N)` minimal data rebalancing &amp; vNode partitions <a href="https://markdy.com/playground/"><img src="docs/images/scene-consistent-hash-tree.webp" alt="Consistent Hash Ring Tree" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **OAuth 2.0 PKCE Auth Sequence** Zero-trust Single Page App authentication exchange <a href="https://markdy.com/playground/"><img src="docs/images/scene-oauth-pkce-sequence.webp" alt="OAuth 2.0 PKCE Auth Sequence" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **Distributed 2PC Consensus State** Prepare/Commit/Abort multi-partition consensus <a href="https://markdy.com/playground/"><img src="docs/images/scene-distributed-2pc-state.webp" alt="Distributed 2PC Consensus State" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **OSI 7-Layer Protocol Stack** Full-width horizontal packet encapsulation bands <a href="https://markdy.com/playground/"><img src="docs/images/scene-osi-layers.webp" alt="OSI 7-Layer Protocol Stack" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **Zero-Trust Security Perimeter** Concentric defense-in-depth Kubernetes security enclaves <a href="https://markdy.com/playground/"><img src="docs/images/scene-nested-security.webp" alt="Zero-Trust Security Perimeter" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **Distributed Saga Order Swimlanes** Cross-functional lanes &amp; asynchronous rollback coordination <a href="https://markdy.com/playground/"><img src="docs/images/scene-ecommerce-swimlanes.webp" alt="Distributed Saga Order Swimlanes" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **Database WAL &amp; CDC Stream Timeline** Zero-collision alternating milestone baseline <a href="https://markdy.com/playground/"><img src="docs/images/scene-platform-milestones-timeline.webp" alt="Database WAL & CDC Stream Timeline" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **Zero-Downtime Migration Gantt** Multi-phase task spans &amp; critical path dependencies <a href="https://markdy.com/playground/"><img src="docs/images/scene-engineering-roadmap.webp" alt="Zero-Downtime Migration Gantt" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **Lakehouse Medallion Data Pipeline** Streaming Bronze &rarr; Silver &rarr; Gold transformations <a href="https://markdy.com/playground/"><img src="docs/images/scene-lakehouse-medallion.webp" alt="Lakehouse Medallion Data Pipeline" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **Decentralized Gossip Flywheel** Circular closed-loop anti-entropy sync engine <a href="https://markdy.com/playground/"><img src="docs/images/scene-data-flywheel.webp" alt="Decentralized Gossip Flywheel" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **Raft Quorum Constellation (Nebula)** Radial orbit geometry &amp; pulsating consensus halos <a href="https://markdy.com/playground/"><img src="docs/images/scene-nebula-constellation.webp" alt="Raft Quorum Constellation" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **CAP Theorem Decision Quadrant** Automated 2&times;2 matrix trade-off positioning <a href="https://markdy.com/playground/"><img src="docs/images/scene-strategic-quadrant.webp" alt="CAP Theorem Decision Quadrant" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **Cloud Observability Pyramid** Step-proportional telemetry &amp; monitoring tier stack <a href="https://markdy.com/playground/"><img src="docs/images/scene-platform-pyramid.webp" alt="Cloud Observability Pyramid" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **Storage Benchmark Radar** Multi-axis polygon database performance evaluation <a href="https://markdy.com/playground/"><img src="docs/images/scene-database-radar.webp" alt="Storage Benchmark Radar" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> |
| **ACID vs BASE Consistency Venn** 3-Circle concept intersection &amp; sweet spot overlap <a href="https://markdy.com/playground/"><img src="docs/images/scene-product-market-fit-venn.webp" alt="ACID vs BASE Consistency Venn" width="100%" /></a> <a href="https://markdy.com/playground/">⚡ Open Interactive Scene in Studio ↗</a> | **AI Agent Workflow &amp; Prompting** Autonomous MCP tool execution &amp; self-healing diagrams <a href="https://markdy.com/agent/"><img src="docs/images/markdy-ai-agent-workflow.webp" alt="AI Agent Workflow" width="100%" /></a> <a href="https://markdy.com/agent/">🤖 Explore Agent Integration Guide ↗</a> |

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

### Player Configuration

Everything outside the scene itself can live in one optional `player:` block. Keep it at the bottom so the diagram remains the first thing readers see:

```markdy
scene theme=paper
layout LR

browser Client
service API

beat request:
  show $nodes
  Client -> API "GET /orders"

player:
  playback:
    loop false
  controls:
    speed true
    speeds "0.5 1"
    fit true
    share true
  interaction:
    zoom true
    pan true
  chrome:
    badge true
    progress boundary
```

| Group | Owns |
|---|---|
| `playback` | when and how fast the timeline runs |
| `controls` | which toolbar affordances are mounted |
| `interaction` | what pointer and key input do |
| `chrome` | non-interactive decoration (badge, progress) |

Controls are explicit opt-ins: only leaves set to `true` are mounted. `fit` frames every item and pins the camera so `frame`/`focus` zoom cues stop moving the view; `prev_beat`/`next_beat` step through beats. `rate` sets the initial multiplier, while `speeds` provides viewer choices; the speed selector needs at least two distinct positive values. The linked badge stays at the footer's right edge. `keyboard` is opt-in (<kbd>←</kbd>/<kbd>→</kbd> beats, <kbd>Space</kbd> play, <kbd>Home</kbd> restart) because it captures window key events. Legacy directives and flat keys normalize into the same groups; explicit host options gate or supply defaults for script settings.

### Themes & Layout Modes

**Themes (`theme=`):**
- `paper` — clean light documentation canvas (default)
- `editorial` — flat editorial paper with serif headings and semantic ink/accent roles
- `terminal` — dark CLI/TUI canvas with monospace font and neon glow accents
- `sketchy` — organic hand-drawn whiteboard theme with displacement filter
- `nebula` — deep-space canvas with orbit rings, signal halos, and starfield
- `midnight` — modern dark developer canvas
- `blueprint` — technical cyan-grid CAD canvas
- `graphite` — restrained dark minimal canvas

**Layout Types (`type=`):**
- `architecture` — ranked multi-tier systems and platform topology (default)
- `flowchart` — top-down steps, decisions, and merges
- `tree` — parent/child hierarchies with shared sibling buses
- `state` — cycle-safe state transitions and self-loops
- `sequence` — participant columns, lifelines, ordered messages, and activations
- `timeline` — horizontal hairline baseline with collision-free alternating milestone cards
- `gantt` — phase-based horizontal bar stacking with temporal span tracking
- `venn` — 2–3 circle concept intersection with proximity scaling
- `radar` — multi-axis polygon comparison chart with series color palette
- `medallion` — multi-tier Bronze → Silver → Gold data lakehouse stages
- `flywheel` / `loop` — circular closed-loop engine with tangential flow paths
- `quadrant` — 2×2 decision and strategic positioning matrix
- `swimlane` — multi-tier cross-functional horizontal lane partitions
- `pyramid` — hierarchical tier pyramid with step-proportional width scaling
- `constellation` — radial focal node with orbital signal rings

---

## 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)
  interactiveViewport?: boolean; // true: default gestures; false: suppress script gestures
  controls?: boolean;       // true: legacy defaults; false: suppress script controls
  shareUrl?: string;        // Base URL for Share links
  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
  beats(): BeatRange[];         // Beat ranges in the compiled scene
  seekToBeat(name: string): void;  // Jump to a named beat
  nextBeat(): void;         // Step to the next beat from the current time
  prevBeat(): void;         // Step to the previous beat from the current time
  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` | script or `true` | Show the linked badge at the footer's right edge |
| `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` | script or `1` | Initial timeline speed multiplier |
| `interactiveViewport` | `boolean` | script | `true` supplies default gestures; `false` suppresses script gestures |
| `controls` | `boolean` | script | `true` supplies legacy defaults; `false` suppresses script controls |
| `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

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

markdy-com

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README