Sketch Diagrams

Sketch is a text-to-diagram engine that generates visual layouts from plain text descriptions. Instead of manually positioning shapes and connectors, you define the relationships between entities, and Sketch handles the positioning and rendering.

Sketch is designed for creating flowcharts, concept maps, system architectures, process diagrams, timelines, and study guides.

---

1. Quick Start

The fundamental building block of a Sketch diagram is a connection between two nodes.

Student -> Book
Student -> Teacher
Teacher -> Whiteboard

Adding Labels

To add context to a connection, append a colon (:) followed by the label text:

Student -> Book : reads
Student -> Teacher : asks questions
Teacher -> Whiteboard : explains

---

2. Syntax and Core Concepts

Nodes and Identifiers

By default, any single word is treated as a node. If your node name contains spaces, special characters, or requires a stable reference, use an explicit ID (in brackets) and a Label (in quotes):

# Simple nodes (best for quick diagrams)
Cell -> Nucleus

# Explicit IDs and Labels (best for complex or changing diagrams)
[student] "Student"
[textbook] "Biology Textbook"

[student] -> [textbook] : reads

• ID ([student]): The internal key used to reference the node in your code.
• Label ("Biology Textbook"): The text displayed visually in the diagram.
• Recommendation: Use explicit IDs to decouple your layout logic from the displayed text. This allows you to rename labels without breaking existing connections.

Connection Types

Syntax	Connection Type	Typical Use Case
A -> B	Directed (one-way)	Flows, sequences, or dependency relationships
A <-> B	Bidirectional (two-way)	Mutual interaction or communication
A -- B	Undirected	General relationships or associations

---

3. Styling and Reusability

Inline Styles

You can customize individual nodes by adding a property block using curly braces {}:

Student {
  fill: blue
  shape: rounded-rect
  stroke: darkblue
  stroke-width: 2.5
}

Supported Styling Properties

• fill: Background color.
• stroke: Border color.
• stroke-width: Border thickness (numeric value).
• shape: The node geometry. Supported values: rect, rounded-rect, circle, diamond.

Classes

To avoid repeating style definitions for similar entities, define a reusable class and apply it to multiple nodes.

# Define the class
class person {
  shape: rounded-rect
  fill: blue
}

# Apply the class
Student { class: person }
Teacher { class: person }

# Apply and override specific properties
Administrator {
  class: person
  fill: green
}

---

4. Layout and Structure

Groups

Use the group block to visually cluster related nodes within a container:

group classroom "Classroom" {
  Student
  Teacher
  Whiteboard
}

Student -> Teacher : asks
Teacher -> Whiteboard : explains

Diagram-wide Settings

Configure global parameters for your diagram using the sketch block:

sketch {
  title: "Application Architecture"
  layout: dag
  direction: left-to-right
}

• title: Sets the metadata/header title for the diagram.
• layout: Sets the rendering engine (e.g., dag for directed acyclic graphs).
• direction: Sets the flow direction. Options include:
  • left-to-right (Default/horizontal flow)
  • top-to-bottom (Vertical flow)
  • right-to-left
  • bottom-to-top

---

5. Additional Features

Interactive Nodes

You can add hover information (tooltips) or hyperlinks to nodes:

Book {
  tooltip: "A source of information"
  link: "https://example.com/book"
}

If you are using Mnemo, you can deep-link directly to internal notes or blocks:

Mitosis {
  opens: "block://biology/mitosis"
}

Comments

Use the # symbol to add inline or block comments. The renderer ignores these lines:

# This is a comment and will not render
Cloud -> Rain : falls

---

6. Complete Example

Below is a comprehensive example combining layout configuration, classes, groups, and explicit node definitions:

sketch {
  title: "Educational Ecosystem"
  layout: dag
  direction: left-to-right
}

# Style Definitions
class human {
  shape: rounded-rect
  fill: blue
}

class asset {
  shape: rect
  fill: yellow
}

# Structural Containers
group classroom "Physical Classroom" {
  [student]
  [teacher]
  [board]
}

# Node Configuration
[student] "Student" {
  class: human
  tooltip: "Classroom learner"
}

[teacher] "Teacher" {
  class: human
}

[book] "Textbook" {
  class: asset
}

[board] "Whiteboard" {
  class: asset
}

# Connection Logic
[student] -> [teacher] : asks questions
[student] -> [book] : reads
[teacher] -> [board] : explains

---

7. Syntax Reference (Cheat Sheet)

Basic Syntax

Goal	Syntax
Node with implicit ID	NodeName
Node with explicit ID/Label	[node_id] "Display Label"
Directed connection	A -> B
Labeled connection	A -> B : Label
Bidirectional connection	A <-> B
Undirected connection	A -- B
Comments	# Comment text

Styling & Configuration

Goal	Syntax
Inline style block	Node { fill: red; shape: circle }
Define a class	class name { fill: red }
Apply a class	Node { class: name }
Create a group	group group_id "Group Label" { Node1 Node2 }
Global configuration	sketch { title: "Title"; direction: left-to-right }
Interactivity	Node { tooltip: "Info"; link: "url" }