Skip to content

Commit 972001f

Browse files
jumskijumski
committed
feat: add D2 theme support and update documentation with architecture diagrams
- Introduced 'astro-d2' package and integrated D2 theme overrides for light and dark modes - Updated documentation to include detailed D2 architecture and task lifecycle diagrams - Modified package.json to include 'astro-d2' dependency - Enhanced Astro configuration with new theme settings and diagrams for better clarity
1 parent 5764ac6 commit 972001f

File tree

9 files changed

+1688
-1348
lines changed

9 files changed

+1688
-1348
lines changed

‎.claude/commands/create-d2-diagram.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Create D2 Diagram with Theme Import
2+
3+
You are helping create D2 diagrams in the pgflow documentation that use the shared pgflow theme.
4+
5+
## Quick Reference
6+
7+
### Basic D2 Code Block with Import
8+
9+
````markdown
10+
```d2
11+
...@../../assets/pgflow-theme.d2
12+
13+
direction: right
14+
15+
nodeA: "Node A"
16+
nodeB: "Node B"
17+
nodeA -> nodeB
18+
```
19+
````
20+
21+
**CRITICAL**: There MUST be a blank line after the code fence and before the import line!
22+
23+
## Theme File Location
24+
25+
The shared theme is at: `pkgs/website/src/assets/pgflow-theme.d2`
26+
27+
## Path Resolution
28+
29+
From content files, use relative path: `...@../../assets/pgflow-theme.d2`
30+
31+
- From `src/content/docs/*.mdx` → `../../assets/pgflow-theme.d2`
32+
- From `src/content/docs/subdir/*.mdx` → `../../../assets/pgflow-theme.d2`
33+
34+
## How It Works
35+
36+
1. The `...@path` syntax tells D2 to import and merge the theme configuration
37+
2. The astro-d2 plugin processes this during build
38+
3. D2 resolves the relative path from the markdown file's location
39+
4. The theme vars are merged with your diagram code
40+
41+
## Common Patterns
42+
43+
### Simple Workflow
44+
````markdown
45+
```d2
46+
...@../../assets/pgflow-theme.d2
47+
48+
direction: right
49+
start -> process -> end
50+
```
51+
````
52+
53+
### With Custom Styling
54+
````markdown
55+
```d2
56+
...@../../assets/pgflow-theme.d2
57+
58+
direction: down
59+
60+
start: "Start" {
61+
style: {
62+
fill: "#003b34"
63+
stroke: "#00574d"
64+
font-color: "#a3d4cb"
65+
}
66+
}
67+
```
68+
````
69+
70+
## Troubleshooting
71+
72+
**Diagram shows code instead of rendering?**
73+
- Ensure blank line after ` ```d2 `
74+
- Check relative path is correct from file location
75+
76+
**Import not found?**
77+
- Verify theme file exists at `src/assets/pgflow-theme.d2`
78+
- Count directory levels correctly (`../` for each parent)

‎.github/actions/setup-d2/action.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: 'Setup D2'
2+
description: 'Install D2 diagramming tool with retry logic'
3+
4+
runs:
5+
using: 'composite'
6+
steps:
7+
- name: Install D2
8+
shell: bash
9+
run: |
10+
for i in 1 2 3 4 5; do
11+
echo "Attempt $i to install D2..."
12+
if curl -fsSL https://d2lang.com/install.sh | sh -s --; then
13+
echo "D2 installed successfully"
14+
break
15+
else
16+
if [ $i -eq 5 ]; then
17+
echo "Failed to install D2 after 5 attempts"
18+
exit 1
19+
fi
20+
echo "Install failed, retrying in 5 seconds..."
21+
sleep 5
22+
fi
23+
done

‎.github/workflows/ci.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ jobs:
5252
- name: Verify NX_BASE and NX_HEAD are set
5353
run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
5454

55+
- uses: ./.github/actions/setup-d2
56+
5557
- name: Quality gate (lint + typecheck + test)
5658
run: pnpm nx affected -t lint typecheck test --parallel --configuration=production --base="$NX_BASE" --head="$NX_HEAD"
5759

@@ -139,6 +141,8 @@ jobs:
139141
- name: Verify NX_BASE and NX_HEAD are set
140142
run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
141143

144+
- uses: ./.github/actions/setup-d2
145+
142146
- name: Check if website is affected
143147
id: check-affected
144148
run: |

‎pkgs/website/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,7 @@ pnpm-debug.log*
1919

2020
# macOS-specific files
2121
.DS_Store
22+
23+
# generated files
2224
public/edge-worker/
25+
public/d2/

‎pkgs/website/astro.config.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import starlightSidebarTopics from 'starlight-sidebar-topics';
77
import robotsTxt from 'astro-robots-txt';
88
import starlightLlmsTxt from 'starlight-llms-txt';
99
import starlightContextualMenu from 'starlight-contextual-menu';
10+
import d2 from 'astro-d2';
1011
import { fileURLToPath } from 'url';
1112
import path from 'path';
1213

@@ -69,6 +70,7 @@ export default defineConfig({
6970
redirects,
7071

7172
integrations: [
73+
d2(),
7274
react({
7375
include: ['**/components/**/*.tsx'],
7476
exclude: ['**/pages/**/*'],
@@ -434,6 +436,7 @@ export default defineConfig({
434436
'/author',
435437
'/demos',
436438
'/demo-colors',
439+
'/d2-guide',
437440
'/news',
438441
'/news/**',
439442
'/edge-worker',

‎pkgs/website/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
"@types/react-dom": "^19.1.7",
2323
"@vercel/analytics": "^1.5.0",
2424
"astro": "^5.7.14",
25+
"astro-d2": "^0.8.0",
2526
"astro-robots-txt": "^1.0.0",
2627
"react": "^19.1.1",
2728
"react-dom": "^19.1.1",

‎pkgs/website/src/assets/pgflow-theme.d2‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
vars: {
2+
d2-config: {
3+
theme-id: 0
4+
dark-theme-overrides: {
5+
# Canvas background
6+
N7: "#121a19"
7+
8+
# Neutrals - desaturated grays for default nodes
9+
N1: "#e8eced"
10+
N2: "#c5cacc"
11+
N3: "#95a0a3"
12+
N4: "#4a5759"
13+
N5: "#2d3739"
14+
N6: "#1a2324"
15+
16+
# Borders - neutral grays
17+
B1: "#3a4547"
18+
B2: "#4a5759"
19+
B3: "#5a6769"
20+
B4: "#1a2324"
21+
B5: "#2d3739"
22+
B6: "#4a5759"
23+
24+
# Semantic colors - intentional states
25+
AA2: "#a87c45"
26+
AA4: "#a33636"
27+
AA5: "#4d3d2b"
28+
AB4: "#247056"
29+
AB5: "#34578f"
30+
}
31+
}
32+
}
33+
34+
# Semantic color classes for workflow states
35+
classes: {
36+
# Generic semantic classes (for general use)
37+
neutral: {
38+
style.fill: "#95a0a3"
39+
style.stroke: "#4a5759"
40+
}
41+
info: {
42+
style.fill: "#34578f"
43+
style.stroke: "#5c8dd6"
44+
}
45+
warning: {
46+
style.fill: "#a87c45"
47+
style.stroke: "#d9a66e"
48+
}
49+
error: {
50+
style.fill: "#a33636"
51+
style.stroke: "#e85c5c"
52+
}
53+
success: {
54+
style.fill: "#247056"
55+
style.stroke: "#33cc7f"
56+
}
57+
58+
# Run state classes (started, completed, failed)
59+
run_started: {
60+
style.fill: "#34578f"
61+
style.stroke: "#5c8dd6"
62+
}
63+
run_completed: {
64+
style.fill: "#247056"
65+
style.stroke: "#33cc7f"
66+
}
67+
run_failed: {
68+
style.fill: "#a33636"
69+
style.stroke: "#e85c5c"
70+
}
71+
72+
# Step state classes (created, started, completed, failed)
73+
step_created: {
74+
style.fill: "#95a0a3"
75+
style.stroke: "#4a5759"
76+
}
77+
step_started: {
78+
style.fill: "#34578f"
79+
style.stroke: "#5c8dd6"
80+
}
81+
step_completed: {
82+
style.fill: "#247056"
83+
style.stroke: "#33cc7f"
84+
}
85+
step_failed: {
86+
style.fill: "#a33636"
87+
style.stroke: "#e85c5c"
88+
}
89+
90+
# Task state classes (queued, completed, failed)
91+
task_queued: {
92+
style.fill: "#95a0a3"
93+
style.stroke: "#4a5759"
94+
}
95+
task_completed: {
96+
style.fill: "#247056"
97+
style.stroke: "#33cc7f"
98+
}
99+
task_failed: {
100+
style.fill: "#a33636"
101+
style.stroke: "#e85c5c"
102+
}
103+
}

0 commit comments

Comments
 (0)