Skip to content

Commit cd34e31

Browse files
will-break-itwill-break-it
committed
docs: add d2 example + readme
1 parent d3e2611 commit cd34e31

File tree

2 files changed

+287
-0
lines changed

2 files changed

+287
-0
lines changed

‎docs/workshop/README.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Leios Diagrams
2+
3+
This directory contains D2 diagrams used to visualize Leios protocol concepts and scenarios.
4+
Read the following if you want to create your own.
5+
6+
## Setup
7+
8+
### Installing D2
9+
10+
D2 is a modern diagram scripting language that turns text to diagrams. Follow these steps to install:
11+
12+
#### macOS
13+
```bash
14+
# Using Homebrew
15+
brew install d2
16+
17+
# Or using curl
18+
curl -fsSL https://d2lang.com/install.sh | sh -s --
19+
```
20+
21+
#### Linux
22+
```bash
23+
curl -fsSL https://d2lang.com/install.sh | sh -s --
24+
```
25+
26+
#### Windows
27+
```bash
28+
# Using Scoop
29+
scoop install d2
30+
31+
# Or download from GitHub releases
32+
# https://github.com/terrastruct/d2/releases
33+
```
34+
35+
### Generating Diagrams
36+
37+
To generate SVG diagrams from the D2 files:
38+
39+
```bash
40+
# Generate a single diagram
41+
d2 leios-example.d2 leios-example.svg
42+
43+
# Generate PNG instead of SVG
44+
d2 leios-example.d2 leios-example.png
45+
46+
# Watch for changes and auto-regenerate
47+
d2 --watch leios-example.d2 leios-example.svg
48+
```
49+
50+
### IDE Integration & Previews
51+
52+
#### VS Code Extension
53+
Install the official D2 extension for syntax highlighting and live preview:
54+
- Search for "D2" in VS Code extensions
55+
- Or install via command: `code --install-extension terrastruct.d2`
56+
57+
#### Live Preview Server
58+
D2 includes a built-in preview server:
59+
```bash
60+
# Start preview server (opens browser automatically)
61+
d2 --watch --port 8080 leios-example.d2
62+
63+
# Preview specific file with custom port
64+
d2 --watch --port 3000 eb-dag.d2
65+
```
66+
67+
#### CLI Options
68+
```bash
69+
# Different output formats
70+
d2 diagram.d2 output.svg # SVG (default)
71+
d2 diagram.d2 output.png # PNG
72+
d2 diagram.d2 output.pdf # PDF
73+
74+
# Themes and styling
75+
d2 --theme=1 diagram.d2 # Dark theme
76+
d2 --sketch diagram.d2 # Hand-drawn style
77+
d2 --center diagram.d2 # Center the diagram
78+
79+
# Layout engines
80+
d2 --layout=elk diagram.d2 # ELK layout engine
81+
d2 --layout=dagre diagram.d2 # Dagre layout engine
82+
```
83+
84+
## Create Your Own
85+
86+
Use [`leios-example.d2`](leios-example.d2) as a template for creating new scenarios:
87+
88+
### 1. Copy the Template
89+
```bash
90+
cp leios-example.d2 my-scenario.d2
91+
```
92+
93+
### 2. Modify Elements
94+
The template includes:
95+
- **Ranking Blocks (RBs)**: `RB1`, `RB2`, `RB3` with class `rb`
96+
- **Endorsement Blocks (EBs)**: `EB1`, `EB2` with class `eb`
97+
- **Input Blocks (IBs)**: `IB1`, `IB2`, `IB3`, `IB4` with class `ib`
98+
99+
### 3. Available Styles
100+
From `styles.d2`:
101+
- `rb` - Standard ranking block
102+
- `rb_stacked` - Multiple ranking blocks
103+
- `rb_unconfirmed` - Unconfirmed ranking block (dashed)
104+
- `eb` - Standard endorsement block
105+
- `eb_unconfirmed` - Unconfirmed endorsement block (dashed)
106+
- `ib` - Standard input block
107+
- `ib_stacked` - Multiple input blocks
108+
- `ib_unconfirmed` - Unconfirmed input block (dashed)
109+
110+
### 4. Connection Types
111+
- `to_rb_arrow` - Blue arrows for RB connections
112+
- `to_eb_arrow` - Orange arrows for EB connections
113+
- `to_ib_arrow` - Yellow arrows for IB connections
114+
- `ledger_link` - Green links for ledger references
115+
- `eb_cert` - Dashed diamond arrows for EB certificates
116+
117+
### 5. Example Modifications
118+
119+
#### Adding more blocks:
120+
```d2
121+
RB4: {
122+
class: rb
123+
label: "RB4"
124+
}
125+
126+
# Connect to chain
127+
RB3 -> RB4: {
128+
class: to_rb_arrow
129+
}
130+
```
131+
132+
#### Creating unconfirmed blocks:
133+
```d2
134+
EB3: {
135+
class: eb_unconfirmed
136+
label: "EB3\n(Unconfirmed)"
137+
}
138+
```
139+
140+
#### Adding containers for complex scenarios:
141+
```d2
142+
pipeline_a: {
143+
label: "Pipeline A"
144+
class: container
145+
146+
EB1: {
147+
class: eb
148+
label: "EB1"
149+
}
150+
151+
IB1: {
152+
class: ib
153+
label: "IB1"
154+
}
155+
}
156+
```
157+
158+
## Example Diagram
159+
160+
Here's what the basic Leios example looks like:
161+
162+
![Leios Example](leios-example.png)
163+
164+
## Files
165+
166+
### Style Definitions
167+
- [`styles.d2`](styles.d2) - Shared style definitions for all diagrams
168+
169+
### Workshop Examples
170+
- [`leios-example.d2`](leios-example.d2) - Simple example showing basic Leios structure
171+
- [`rb-reference.d2`](rb-reference.d2) - Basic RB reference approach
172+
- [`rb-reference-detailed.d2`](rb-reference-detailed.d2) - Detailed RB reference with EBs
173+
- [`rb-reference-realistic.d2`](rb-reference-realistic.d2) - Realistic RB reference scenarios
174+
- [`eb-reference.d2`](eb-reference.d2) - EB reference approach diagram
175+
- [`eb-chain.d2`](eb-chain.d2) - EB chain approach diagram
176+
- [`eb-dag.d2`](eb-dag.d2) - EB DAG approach diagram
177+
- [`eb-dag-detailed.d2`](eb-dag-detailed.d2) - Detailed EB DAG with IBs
178+
179+
## Tips
180+
181+
1. **Keep it simple**: Start with the basic template and add complexity gradually
182+
2. **Use containers**: Group related elements for better organization
183+
3. **Consistent naming**: Use clear, descriptive labels
184+
4. **Leverage styles**: Use the predefined classes for consistency
185+
5. **Test frequently**: Use `--watch` flag to see changes in real-time
186+
187+
## Resources
188+
189+
- [D2 Documentation](https://d2lang.com/)
190+
- [D2 Playground](https://play.d2lang.com/)

‎docs/workshop/leios-example.d2

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
...@styles
2+
3+
title: {
4+
label: "Leios Example"
5+
near: top-center
6+
style.font-size: 24
7+
style.bold: true
8+
style.fill: "#ffffff"
9+
style.stroke: "#ffffff"
10+
}
11+
12+
# Ranking Blocks
13+
RB1: {
14+
class: rb
15+
label: "RB1"
16+
}
17+
18+
RB2: {
19+
class: rb
20+
label: "RB2"
21+
}
22+
23+
RB3: {
24+
class: rb
25+
label: "RB3"
26+
}
27+
28+
# Endorsement Blocks
29+
EB1: {
30+
class: eb
31+
label: "EB1"
32+
}
33+
34+
EB2: {
35+
class: eb
36+
label: "EB2"
37+
}
38+
39+
# Input Blocks
40+
IB1: {
41+
class: ib
42+
label: "IB1"
43+
}
44+
45+
IB2: {
46+
class: ib
47+
label: "IB2"
48+
}
49+
50+
IB3: {
51+
class: ib
52+
label: "IB3"
53+
}
54+
55+
IB4: {
56+
class: ib
57+
label: "IB4"
58+
}
59+
60+
# Links
61+
62+
# RB chain connections
63+
RB1 -> RB2: {
64+
class: to_rb_arrow
65+
}
66+
67+
RB2 -> RB3: {
68+
class: to_rb_arrow
69+
}
70+
71+
# EB certificates in RBs
72+
RB2 -> EB1: "Contains\nEB Certificate" {
73+
class: eb_cert
74+
}
75+
76+
RB3 -> EB2: "Contains\nEB Certificate" {
77+
class: eb_cert
78+
}
79+
80+
# EB to IB references
81+
EB1 -> IB1: "Ref" {
82+
class: to_ib_arrow
83+
}
84+
85+
EB1 -> IB2: "Ref" {
86+
class: to_ib_arrow
87+
}
88+
89+
EB2 -> IB3: "Ref" {
90+
class: to_ib_arrow
91+
}
92+
93+
EB2 -> IB4: "Ref" {
94+
class: to_ib_arrow
95+
}
96+
97+
direction: left

0 commit comments

Comments
 (0)