A sequence diagram answers "what calls what, and in what order?" Static tools draw the whole ladder at once, which buries the very thing you're trying to explain: the order. With Markdy you script the steps as a timeline, so each call and return appears when it happens.
Set type=sequence to get participant columns, lifelines, ordered messages, and lightweight activation spans. Pair it with theme=editorial when the scene belongs in documentation or an architecture review.
1. Declare the participants
Sequence "participants" are just nodes. Use whatever kind fits — client, service, database, auth:
scene theme=editorial type=sequence
layout LR
participant User
participant API "Auth API"
participant OIDC "OIDC Provider"
participant DB "User DB"2. Reveal them, then play the calls
Wrap the flow in a beat. Use -> for a request and <- for a response (Markdy draws the response back toward the caller). Each line animates in order:
beat login:
show $nodes stagger=80ms
User -> API "POST /login"
API -> OIDC "verify token"
API <- OIDC "claims"
API -> DB "load profile"
API <- DB "user row"
User <- API "session cookie"That reads top-to-bottom like a classic sequence diagram, but it plays — the request travels, the response returns, and a labeled pulse follows each edge.
3. Emphasize the important step
Split phases into separate beats and add emphasis with glow or focus:
beat highlight:
glow OIDC color=#f59e0b & focus API zoom=1.1Async steps and fan-out
Not every call is synchronous. Use ~> for an event/publish and & to run two steps together — handy for fan-out to a queue while you also write to a database:
beat write:
API -> DB "persist" & API ~> Events "user.created"Why animate a sequence at all?
Because comprehension follows attention. In a talk, a launch post, or onboarding docs, revealing one step at a time keeps the reader with you. It's the same diagram-as-codeworkflow — reviewable in PRs, and easy for an AI to draft. Try the login example above in the playground, then read thedocs for the full cue reference.