@markdy/astro

Astro island component for MarkdyScript animated scenes.

Features

• SSR placeholder — correctly-sized <div> prevents layout shift before hydration
• Viewport-triggered hydration — IntersectionObserver with 100px root margin
• View Transition compatible — re-observes elements on astro:page-load
• Semantic node cards — inherits renderer SVG glyphs for technical node kinds
• Zero config — pass your MarkdyScript code as a prop

Installation

pnpm add @markdy/astro

Package position (text)

@markdy/core -> @markdy/renderer-dom -> @markdy/astro

Astro integration provides an island wrapper for lazy client-side hydration.

Output preview

Usage

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

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

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

In MDX

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

export const code = `
  scene "Request" theme=paper width=600 height=300
  browser Web
  service API
  beat main:
    show $nodes
    Web -> API "GET /users"
`;

<Markdy code={code} width={600} height={300} bg="#07111f" autoplay />

Props

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

Tip: Match width, height, and bg props to your scene declaration values to avoid a visual flash on hydration.

How It Works

1. Server: renders a sized placeholder <div> with a ▶ markdy label
2. Client: an IntersectionObserver watches all .markdy-root elements
3. On viewport entry: the observer fires, clears the placeholder, and calls createPlayer() from @markdy/renderer-dom
4. View Transitions: listens for astro:page-load to re-observe newly added elements

Documentation

• Tutorial — step-by-step guide from zero to animated scenes
• Syntax Reference — complete DSL language spec

License

MIT