Alpha
Mermaid Presentation Framework

Interactive presentations on top of Mermaid diagrams.

Finsteps adds a presentation runtime and MPD DSL on top of Mermaid, giving you camera moves, overlays, navigation, and an editor that stay in sync with your diagrams.

Get started View live examples

Built around presentMermaid(), MPD, and a controller API that works in both static sites and live editors.

Finsteps editor and presentation over a Mermaid diagram
Drop your hero image at docs/assets/finsteps-hero.png

Why Finsteps?

A small, focused runtime that turns static diagrams into guided walkthroughs.

MPD: Mermaid Presentation DSL

Describe camera moves, highlights, and overlays alongside your Mermaid diagrams using a small, purpose-built DSL.

Presentation controller

A typed controller with next, prev, goto, and events you can bind to your own UI or host frameworks.

Editor-friendly design

Accessors, hooks, and dynamic AST updates (per ADR-0008) make it easy to embed Finsteps in live editors without hacks.

Camera & overlays

Built-in camera handle and overlay primitives for zooming, panning, and annotating regions via data-id.

Framework-agnostic

Works with plain HTML, React, Reveal.js, or your own host framework—wherever Mermaid can render.

Clear architecture

Backed by ADRs and requirements: MPD (ADR-0001), rendering lifecycle (ADR-0003), editor refactoring (ADR-0008).

How it works

Finsteps parses MPD into a PresentationAst and wires it into a MermaidController. The controller drives camera, overlays, and bindings on top of Mermaid's SVG output.

  • MPD: declarative steps, actions, and bindings.
  • Controller: navigation and events with lifecycle hooks.
  • Adapters: diagram, camera, and overlay abstractions.

Read the design docs: ADR-0001, ADR-0003, ADR-0008. See also: MPD Grammar, JSON Schemas. 

// Minimal presentMermaid usage
import { presentMermaid } from 
  "https://cdn.jsdelivr.net/gh/cablepull/finsteps@v0.4.4/dist/finsteps.esm.min.js";

const controller = await presentMermaid({
  mountEl: document.getElementById("diagram-mount"),
  mermaidText: `
flowchart LR
  A[User] --> B[Finsteps] --> C[Diagram]
`,
  mpdText: `
mpd 1.0

deck {
  scene default {
    step overview {
      camera fit(target: dataId("A"))
    }
  }
}
`
});

Live examples

Explore Finsteps running on different diagram types and host environments.

Featured Examples

Live editor

Edit Mermaid + MPD side-by-side and drive the controller.

Architecture walkthrough

Step through a system diagram with camera moves and overlays.

Floating controls

Built-in UI controls for navigation and camera operations.

Compact controls

Size, theme, orientation, and playback speed options.

Reveal.js integration

Multiple diagrams in a Reveal.js presentation deck.

Reveal.js plugin

Declarative HTML API with data-finsteps attributes.

Stable Diagram Types

Sequence diagram

Order processing flow with participants and messages.

Class diagram

Inheritance hierarchy and composition relationships.

State diagram

State machine with transitions and nested states.

ER diagram

Entity-relationship model for e-commerce system.

Pie chart

Device usage distribution with animated transitions.

User journey

Signup and onboarding flow with engagement scores.

Git graph

Branch structure, commits, and merge workflow.

Gantt chart

Project timeline with phases and task highlighting.

Experimental Diagram Types (BETA)

Requirement diagram BETA

Requirements and their relationships to functions.

C4 Context BETA

System boundaries and external interactions.

C4 Container BETA

System containers and their relationships.

C4 Component BETA

Internal components within containers.

Block diagram BETA

Simple decision flow process blocks.

Timeline BETA

Software release history across versions.

Quadrant chart BETA

Market positioning across four quadrants.

Mindmap BETA

Hierarchical mindmap with node targeting.

XY chart BETA

Chart with labels and series targeting.

Kanban BETA

Kanban board with columns and tasks.

Packet diagram BETA

Network packet structure with layer labels.

Radar chart BETA

Multi-axis radar chart with metric labels.

Sankey diagram BETA

Flow diagram with node targeting.

Treemap BETA

Hierarchical treemap with group labels.

ZenUML BETA

ZenUML sequence diagram with participant targeting.

Wardley Map EXPERIMENTAL

Strategic map showing evolution and dependencies (requires tractorjuice fork).
View all examples →

Getting started

Use Finsteps directly from jsDelivr CDN, or clone the repository to run examples locally.

CDN (jsDelivr)

Load Finsteps directly in your HTML with no build step:

Latest version: https://cdn.jsdelivr.net/gh/cablepull/finsteps@latest/dist/finsteps.esm.min.js
Pinned version (v0.4.4): https://cdn.jsdelivr.net/gh/cablepull/finsteps@v0.4.4/dist/finsteps.esm.min.js

Note: You must load Mermaid.js separately before using Finsteps. See README for complete usage examples.

Local development

To experiment locally or contribute:

  1. Clone the repository from GitHub.
  2. Run the local examples (see README for run-example.sh).
  3. Open the editor example and tweak Mermaid + MPD side-by-side.
  4. Explore the ADRs and requirements to understand the architecture.

Project links