📦

Zero Dependencies

Pure TypeScript parser — no DOM, no runtime deps.

🌐

Web-Native Renderer

Web Animations API + CSS transforms. No Canvas, no GSAP.

🤖

AI-Agent Friendly

Structured DSL that LLMs can generate, validate, and iterate.

🧩

Framework Agnostic

Works anywhere. Astro island component included.

Ecosystem

Lightweight Packages

Two packages to render a scene anywhere. Everything else is an optional add-on for your stack.

@markdy/core

Required

Parser + AST types. Every other package builds on this — no DOM, no dependencies.

import { parse } from "@markdy/core";

~12 KBEngine

@markdy/renderer-dom

Required

Takes a parsed scene and animates it in the browser via the Web Animations API.

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

~22 KBDOM

@markdy/astro

Astro island. Pass your scene as a code prop — it hydrates only when scrolled into view.

<Markdy code={code} autoplay />

~2 KBAstro

@markdy/mdx

Write fenced markdy code blocks straight in Markdown/MDX — no component imports needed.

remarkPlugins: [remarkMarkdy]

~8 KBMDX

@markdy/cli

Lint, format, render, and preview .markdy files from your terminal — no browser needed.

markdy render scene.markdy --out out.html

NodeTooling

@markdy/language-server

Diagnostics, autocomplete, and hover docs for any LSP-capable editor (VS Code, Neovim, Zed).

npx @markdy/language-server

NodeLSP

@markdy/stdlib-systems

Optional add-on: service/db/queue/client actors for drawing system architecture diagrams.

registerActorPack(systemsPack);

<1 KBActor Pack

Interactive

Playground

Start from a real shipped example, tweak the script, and preview the result instantly.

Editor

# The newest Love Story / Full Story variant from recent history.
scene width=800 height=400 fps=30 bg=#fafafa

var skin_a = #c68642
var skin_b = #8d5524
var skin_g = #fad4c0

def fighter(skin, face) {
  figure(${skin}, m, ${face})
}

def girl(skin, face) {
  figure(${skin}, f, ${face})
}

seq hit(side, power) {
  @+0.0: $.punch(side=${side}, dur=0.3)
  @+0.05: $.shake(intensity=${power}, dur=0.3)
}

actor act1 = caption("I. Boys See Girl") at top opacity 0
actor act2 = caption("II. Boys Fight") at top opacity 0
actor act3 = caption("III. Girl Says No") at top opacity 0
actor act4 = caption("IV. Girl Picks the Loser") at top opacity 0

actor chad = fighter(${skin_a}, 😏) at (640, 180)
actor kevin = fighter(${skin_b}, 😤) at (100, 180)
actor mia = girl(${skin_g}, 👧) at (370, 180) opacity 0
actor bush = text("🪨") at (50, 285) size 80 opacity 0

scene "rivals" {
  @+0.0: act1.fade_in(dur=0.3)
  @+0.1: mia.fade_in(dur=0.5)
  @+0.0: chad.enter(from=right, dur=0.6)
  @+0.0: kevin.enter(from=left, dur=0.6)
  @+0.2: chad.wave(side=left, dur=0.5)
  @+0.0: kevin.wave(side=right, dur=0.5)
  @+0.2: chad.face("😍")
  @+0.0: kevin.face("😍")
  @+0.2: chad.say("Hey gorgeous 😘", dur=1.3)
  @+0.3: kevin.say("Back off, she's mine!", dur=1.3)
  @+0.6: act1.fade_out(dur=0.3)
  @+0.1: mia.face("😳")
  @+0.2: mia.say("…do I get a say?", dur=1.2)
  @+0.4: mia.move(to=(600, 180), dur=0.5, ease=out)
}

scene "duel" {
  @+0.0: act2.fade_in(dur=0.3)
  @+0.3: chad.face("😠")
  @+0.0: kevin.face("😠")
  @+0.1: chad.move(to=(400, 180), dur=0.5, ease=in)
  @+0.0: kevin.move(to=(320, 180), dur=0.5, ease=in)
  @+0.3: act2.fade_out(dur=0.3)
  @+0.2: kevin.say("En garde, bro!", dur=1.0)
  @+0.3: chad.play(hit, side=left, power=7)
  @+0.0: camera.shake(intensity=6, dur=0.3)
  @+0.1: kevin.play(hit, side=right, power=7)
  @+0.2: kevin.kick(side=right, dur=0.3)
  @+0.0: chad.shake(intensity=9, dur=0.3)
  @+0.2: chad.say("Is that all?", dur=0.9)
  @+0.9: chad.punch(side=left, dur=0.25)
  @+0.0: camera.shake(intensity=16, dur=0.5)
  @+0.0: kevin.face("😵")
  @+0.0: bush.fade_in(dur=0.2)
  @+0.1: kevin.move(to=(110, 275), dur=0.55, ease=out)
  @+0.0: kevin.rotate(to=-80, dur=0.55, ease=out)
  @+0.4: bush.shake(intensity=7, dur=0.4)
  @+0.0: bush.fade_out(dur=0.3)
  @+0.0: kevin.face("🤕")
  @+0.3: chad.face("😎")
  @+0.2: chad.say("Too easy. She's mine!", dur=1.4)
}

scene "rejection" {
  @+0.0: act3.fade_in(dur=0.3)
  @+0.3: chad.face("🥰")
  @+0.0: chad.move(to=(520, 180), dur=0.6, ease=out)
  @+0.5: chad.say("My queen 👑", dur=1.1)
  @+0.3: mia.face("🙅")
  @+0.2: mia.say("Hard pass.", dur=1.1)
  @+0.0: mia.shake(intensity=5, dur=0.4)
  @+0.4: act3.fade_out(dur=0.3)
  @+0.1: chad.face("😨")
  @+0.2: chad.say("But… I WON??", dur=1.3)
  @+0.4: mia.face("😒")
  @+0.2: mia.say("That's the problem.", dur=1.4)
  @+0.6: chad.face("😭")
  @+0.4: chad.exit(to=right, dur=0.8)
}

scene "aftermath" {
  @+0.0: act4.fade_in(dur=0.3)
  @+0.2: mia.face("🥺")
  @+0.1: mia.move(to=(230, 210), dur=1.2, ease=out)
  @+0.0: camera.pan(to=(100, 345), dur=1.2, ease=out)
  @+0.0: camera.zoom(to=1.3, dur=1.2, ease=out)
  @+0.6: act4.fade_out(dur=0.3)
  @+0.3: mia.face("😊")
  @+0.2: mia.say("You okay down there?", dur=1.6)
  @+0.2: kevin.face("🥲")
  @+0.2: kevin.face("🥹")
  @+0.2: kevin.say("Mission failed…", dur=1.3)
  @+0.2: kevin.say("…successfully. 💖", dur=1.6)
  @+0.2: mia.face("😘")
}

Preview

Step-by-Step

Learn MarkdyScript

Follow this guide from basics to advanced. Each card builds on the last.

Scene Setup

Every animation starts by defining the canvas. This must be the first line in your .markdy file.

scene width=800 height=400 fps=30 bg=#fafafa

Property	Default	Description
`width`	`800`	Canvas width in pixels
`height`	`400`	Canvas height in pixels
`fps`	`30`	Frame rate for the rendering engine
`bg`	`white`	Any CSS color value (e.g. `#1a1a2e`)
`duration`	auto	Override total length in seconds

Actors & Positioning

Actors are the objects in your scene. Place them with at (x, y) and add optional modifiers.

actor a = figure(#c68642, m, 😎) at (100, 200) scale 1.2
actor b = text("Hello World") at (50, 50) size 24
actor c = box() at (300, 200)

Type	Arguments	Description
`text`	`"quoted string"`	Plain text label. Customise with `size`.
`box`	—	100x100 solid box. Great for prototyping.
`figure`	skinColor, gender, face	Stick figure with articulatable limbs.
`sprite`	asset name	Renders an image or icon asset.

Modifiers: opacity (0–1), scale, rotate, size (text only), z (layer order).

Timeline & Motion

Schedule actions on a timeline with @time: actor.action(). Time is in decimal seconds.

@0.5: a.enter(from=left, dur=0.8)
@1.5: a.move(to=(400, 200), dur=1.0, ease=out)
@3.0: a.fade_out(dur=0.5)

Action	Parameters	What it does
`enter`	from, dur	Slides in from canvas edge
`move`	to, dur, ease	Translates to target coordinates
`fade_in` / `fade_out`	dur	Animates opacity
`scale` / `rotate`	to, dur	Transforms the actor

Easing: linear, in, out, inout

Speech & Effects

Make actors talk with comic speech bubbles and add dynamic effects like shaking.

@1.0: a.say("Hello! 👋", dur=1.5)
@2.5: a.shake(intensity=8, dur=0.4)

Action	Parameters	What it does
`say`	`"text"`, dur	Shows an anchored speech bubble
`shake`	intensity, dur	Oscillates on the X axis
`throw`	asset, to, dur	Launches a projectile between actors

Expressions & Limbs

figure actors have articulated limbs you can individually control for expressive animations.

@1.0: a.face("😵")
@1.5: a.rotate_part(part=arm_right, to=130, dur=0.4)
@2.0: a.punch(side=right, dur=0.2)
@2.5: a.kick(side=left, dur=0.3)

Action	Parameters
`face`	`"emoji"` — instant expression swap
`rotate_part`	part, to (degrees), dur
`punch` / `kick`	side (left\|right), dur

Body parts: head, face, body, arm_left, arm_right, leg_left, leg_right

Gestures & Posing

Built-in gestures save you from chaining rotate_part calls. pose sets multiple parts at once.

@1.0: a.wave(side=right, dur=0.8)
@2.0: a.nod(dur=0.4)
@3.0: a.pose(arm_left=70, arm_right=-70, dur=0.4)
@4.0: a.jump(height=25, dur=0.5)
@4.5: a.bounce(intensity=12, count=3, dur=0.5)

Action	Parameters	What it does
`wave`	side, dur	Wave gesture — arm up, oscillate, return
`nod`	dur	Head nod — down and up twice
`pose`	arm_left, arm_right, leg_left, leg_right, head, body, dur	Set multiple parts at once
`jump`	height, dur	Jump with squash/stretch
`bounce`	intensity, count, dur	Diminishing vertical bounce

Assets & Sprites

Load external images and vector icons as assets, then render them as sprite actors.

# Declare assets first
asset cat = image("https://example.com/cat.gif")
asset fire = icon("lucide:flame")

# Render them as actors
actor meme = sprite(cat) at (400, 200) scale 0.5
actor icon = sprite(fire) at (100, 100) scale 2.0

`image("url")`	Loads images, GIFs, photos — any URL or local path.
`icon("set:name")`	Loads SVG icons from Iconify. Never blurs when scaled.

Variables & Templates

Avoid repetition with var for values and def for reusable actor templates.

var accent_skin = #fad4c0

def char(skin, face) {
  figure($${skin}, f, $${face})
}

actor lily = char($${accent_skin}, 😊) at (100, 200)

var substitutes values (robust for #hex colors). def creates actor factory templates — build character systems without any JavaScript.

Sequences

Package multi-step choreographies into reusable seq blocks. The ultimate power move.

seq wave(arm, angle) {
  @+0.0: $.rotate_part(part=$${arm}, to=$${angle}, dur=0.3)
  @+0.3: $.rotate_part(part=$${arm}, to=25, dur=0.3)
}

@2.0: lily.play(wave, arm=arm_left, angle=-80)

$ refers to the calling actor. Times with @+ are relative offsets from when .play() is triggered.

Vibe Coding

AI-Friendly by Design

MarkdyScript is a structured DSL that AI agents can generate, validate, and iterate on. Just describe what you want.

How it works

Point your AI to the docs
Share the AGENT.md — a single all-in-one reference with grammar, actions, patterns and examples.
Describe your scene in plain English
Tell the AI what you want to visualize — characters, actions, emotions, timing.
Get valid MarkdyScript back
The AI generates syntactically correct code. Paste it into the playground or your app.

Example prompt

You → Claude / ChatGPT / Copilot

Use https://github.com/HoangYell/markdy-com/blob/main/docs/AGENT.md as a complete reference (grammar, actions, patterns, examples), then write a Markdy scene:

"A guy holding a coffee cup walks in, trips on a rock, and loses his coffee cup. The cup flies and smashes. He looks sad."

The AI reads the docs, understands the grammar, and outputs a complete .markdy scene with actors, timeline events, and expressions — ready to render.

Works with any AI that accepts URL context

ClaudeChatGPTGitHub CopilotCursorWindsurf

Community