┌─────────────────────

─────────────────────┘

Open source · MIT License · npm install sketchmark

Diagrams that feel
hand-drawn.
Written in plain text.

A DSL for architects, engineers, and educators who want expressive, animated system diagrams — without touching a mouse.

Parse any diagram from plain text → render hand-drawn SVG via rough.js → step through animations → export SVG/PNG.

Try playground ↗Read the docs See examples

roughjs peer dep · works in any bundler or via CDN

diagram.sketchmark — everything is text

# define reusable colour themes
theme primary fill="#e8f4ff" stroke="#0044cc"  # per-element
config theme=sketch                          # or global palette

# describe structure — layout engine figures out positions
group services label="Microservices" layout=column gap=16 padding=30
{
  box auth  label="Auth Service"    theme=primary width=140 height=55
  box queue label="Job Queue"       theme=primary width=140 height=55
}

# step through animation — runs on click or play()
step highlight auth
step draw auth-->queue
step move queue dx=0 dy=-20 duration=400

Why Sketchmark

Everything a diagram tool should be. Nothing it shouldn't.

No mouse. No drag-and-drop. No proprietary file formats. Just a text file that your whole team can read, diff, review, and run.

✏

Hand-drawn rendering

Every shape rendered by rough.js — slightly wobbly, slightly imperfect. Diagrams that look drawn, not printed. Perfect for ideas still forming.

▶

Built-in step animation

step highlight, step draw, step move, step fade, step scale, step rotate — 13 actions, all elements, from DSL.

⌨

Plain text DSL

No XML. No JSON. No visual editor. Write diagrams like code — in your editor, in version control, in a PR description. Diffs that make sense.

⚡

Flexbox layout engine

Row, column, grid. Nested groups with justify, align, gap, padding. Auto-sizes everything. Override with explicit width/height when you need pixel control.

📄

Markdown blocks

Embed prose with markdown blocks — headings, bold, italic, paragraphs — alongside diagram elements in the same file.

◑

9 theme palettes + 11 fonts

light, dark, ocean, forest, sunset, slate, rose, midnight, sketch. Caveat, DM Mono, Playfair, Patrick Hand. One line to switch. All Google Fonts, loaded automatically.

📊

Tables, notes & charts

Bar, line, area, pie, donut, scatter charts. Sticky notes with fold. Data tables with headers, dividers, cell alignment. All in the same DSL.

↓

Export anywhere

SVG, PNG, self-contained HTML. Transparent background. Clean SVG source. Embed in GitHub READMEs, Notion, Confluence, or any web app.

Animation

Step through your architecture live

Add step instructions after your diagram elements. Click next — or call anim.play() — and nodes draw themselves, edges animate in, elements highlight, fade, move, and scale.

Walk an audience through a system design one connection at a time. Works on nodes, groups, tables, notes, charts, and edges.

animation.sketchmark

step highlight client
step draw    client-->gateway
step move    server dx=0 dy=-60 duration=500
step scale   gateway factor=1.3
step fade    oldbox
step color   alert fill="#ff4444"
step rotate  broken deg=25

Layout Engine

Flexbox-style groups,
nested infinitely

Groups are independent flex containers. Set layout=row, layout=column, or layout=grid. Nest groups inside groups. Justify and align just like CSS flexbox.

The layout engine measures every element, resolves sizes, and places everything — you describe structure, it figures out coordinates.

layout.sketchmark

group platform layout=column gap=20
{
  group frontend layout=row justify=center
  {
    box react label="React"
    box next  label="Next.js"
  }
  group data layout=grid columns=2
  {
    cylinder pg    label="Postgres"
    cylinder redis label="Redis"
  }
}

Themes & Fonts

9 palettes. 11 fonts.
Infinite custom.

Switch the entire diagram with one line. Define named themes inline and apply them to individual elements. Built-in fonts load automatically from Google Fonts — hand-drawn, monospace, serif.

The sketch palette with font=caveat gives you that authentic whiteboard feel. The midnight palette looks great in dark-mode docs.

themes.sketchmark

# built-in palettes
config theme=sketch   # graphite pencil
config theme=ocean    # cool blues
config theme=midnight # dark code-editor

# + hand-drawn fonts
config font=caveat

# or inline per-element themes
theme brand fill="#f0e8ff" stroke="#7700cc"
box a theme=brand font=playfair

Markdown Blocks

Prose and diagrams.
Same file.

The markdown block renders headings, bold, and italic text inline alongside diagram elements. Write your explanation and your diagram together — no more switching between tools.

with-prose.sketchmark

bare page layout=row gap=60
{
  markdown intro width=280 font=caveat
  """
  # Auth Service

  Validates credentials against
  the **Users DB** and returns a
  *signed JWT* on success.
  """

  group flow layout=column gap=20 padding=30
  {
    box api label="API"     theme=primary
    box auth label="Auth"    theme=primary
    cylinder db label="Users DB" theme=success
  }
}

Who it's for

Built for people who think
in systems.

Whether you're documenting an architecture, teaching a concept, or building a tool — Sketchmark gives you diagrams that live where your work lives.

Software Engineers

Architecture docs that live in git

Write diagrams alongside code. Review them in PRs. No binary blobs, no drag-drop sessions, no shared Lucidchart link that's always out of date.

git diff auth-flow.sketchmark # - box auth label="JWT" # + box auth label="OAuth2"

Engineering Managers

System walkthroughs that actually walk

Use step animations to guide teams through a new architecture. Reveal each service as you explain it. Highlight the bottleneck. Fade out the deprecated system.

step highlight bottleneck step color bottleneck fill="#ff4444" step pulse bottleneck

Educators & Tech Writers

Teach concepts with progressive reveal

TCP handshakes, OSI layers, auth flows, microservice patterns. Diagrams that unfold step by step. Hand-drawn style signals explanation, not specification.

step draw layer7 step draw layer7-->layer6 step highlight layer6

Developers building tools

Embed diagrams in your own product

npm package with a one-call API. render() returns an SVG, an AnimationController, and export functions. Integrate into docs sites, wikis, notebooks, dashboards.

const { anim, svg } = render({ container, dsl }); anim.play(800);

Compare

Why not Mermaid, Excalidraw,
or Lucidchart?

Each tool solves part of the problem. Sketchmark is the only one that combines text-based DSL, hand-drawn rendering, and step-by-step animation.

Feature	Mermaid	Excalidraw	Lucidchart	Sketchmark
Text-based DSL	✓	✗	✗	✓
Hand-drawn render	✗	✓	✗	✓
Step animation	✗	✗	✗	✓
Nested groups	limited	✗	✓	✓
Custom named themes	limited	✗	✓	✓
npm package	✓	✓	✗	✓
Tables & charts in DSL	partial	✗	✗	✓
Markdown prose blocks	✗	✗	✗	✓
Version-control friendly	✓	✗	✗	✓
Transparent export	✓	✓	✓	✓
move / scale / rotate	✗	✗	✗	✓
Encrypted share links	✗	partial	✗	✓

Get started

Two lines to your first
hand-drawn diagram.

Works in any bundler. Works in Next.js, Vite, webpack. Works directly in the browser via CDN. Zero configuration.

$npm install sketchmark roughjs

first-diagram.ts

import { render } from 'sketchmark';

render({
  container: document.getElementById('diagram'),
  dsl: `diagram
  box a label="Hello"
  box b label="World"
  a --> b label="connects"
  step draw a
  step draw a-->b
  step draw b
  end`,
});

rough.js is a peer dependency — load it before sketchmark.
Works in any bundler (Vite, webpack, Next.js) or directly via CDN with an import map.

Open playground ↗Read the docs See all examples

Diagrams that feelhand-drawn.Written in plain text.