Skip to content

Commit 689397e

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 6a467ff commit 689397e

File tree

11 files changed

+2444
-0
lines changed

11 files changed

+2444
-0
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
@@ -47,6 +47,8 @@ jobs:
4747
- name: Verify NX_BASE and NX_HEAD are set
4848
run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
4949

50+
- uses: ./.github/actions/setup-d2
51+
5052
- name: Quality gate (lint + typecheck + test)
5153
run: pnpm nx affected -t lint typecheck test --parallel --configuration=production --base="$NX_BASE" --head="$NX_HEAD"
5254

@@ -119,6 +121,8 @@ jobs:
119121
- name: Verify NX_BASE and NX_HEAD are set
120122
run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
121123

124+
- uses: ./.github/actions/setup-d2
125+
122126
- name: Check if website is affected
123127
id: check-affected
124128
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: 2 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

@@ -54,6 +55,7 @@ export default defineConfig({
5455
redirects,
5556

5657
integrations: [
58+
d2(),
5759
react({
5860
include: ['**/components/**/*.tsx'],
5961
exclude: ['**/pages/**/*'],

‎pkgs/website/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
"@types/react-dom": "^19.1.7",
2828
"@vercel/analytics": "^1.5.0",
2929
"astro": "^5.7.14",
30+
"astro-d2": "^0.8.0",
3031
"astro-robots-txt": "^1.0.0",
3132
"react": "^19.1.1",
3233
"react-dom": "^19.1.1",

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
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: "#d97706"
26+
AA4: "#dc2626"
27+
AA5: "#92400e"
28+
AB4: "#059669"
29+
AB5: "#2563eb"
30+
}
31+
}
32+
}

‎pkgs/website/src/components/D2.astro‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
import { execSync } from 'node:child_process';
3+
4+
const {
5+
padding = 100,
6+
sketch = false,
7+
theme = 0,
8+
darkTheme = 200,
9+
code,
10+
layout = 'dagre',
11+
} = Astro.props;
12+
13+
// Theme configuration that will be prepended to all diagrams
14+
const themeConfig = `vars: {
15+
d2-config: {
16+
theme-id: ${theme}
17+
theme-overrides: {
18+
# Neutrals - desaturated grays for default nodes
19+
N1: "#e8eced"
20+
N2: "#c5cacc"
21+
N3: "#95a0a3"
22+
N4: "#4a5759"
23+
N5: "#2d3739"
24+
N6: "#1a2324"
25+
N7: "#ffffff"
26+
27+
# Borders - neutral grays
28+
B1: "#3a4547"
29+
B2: "#4a5759"
30+
B3: "#5a6769"
31+
B4: "#1a2324"
32+
B5: "#2d3739"
33+
B6: "#4a5759"
34+
35+
# Semantic colors - intentional states
36+
AA2: "#d97706"
37+
AA4: "#dc2626"
38+
AA5: "#92400e"
39+
AB4: "#059669"
40+
AB5: "#2563eb"
41+
}
42+
dark-theme-overrides: {
43+
# Neutrals - desaturated grays for default nodes
44+
N1: "#e8eced"
45+
N2: "#c5cacc"
46+
N3: "#95a0a3"
47+
N4: "#4a5759"
48+
N5: "#2d3739"
49+
N6: "#1a2324"
50+
N7: "#121a19"
51+
52+
# Borders - neutral grays
53+
B1: "#3a4547"
54+
B2: "#4a5759"
55+
B3: "#5a6769"
56+
B4: "#1a2324"
57+
B5: "#2d3739"
58+
B6: "#4a5759"
59+
60+
# Semantic colors - intentional states
61+
AA2: "#d97706"
62+
AA4: "#dc2626"
63+
AA5: "#92400e"
64+
AB4: "#059669"
65+
AB5: "#2563eb"
66+
}
67+
}
68+
}
69+
70+
`;
71+
72+
// Prepend theme config to the user's diagram code
73+
const fullCode = themeConfig + code;
74+
75+
// Generate the diagram SVG
76+
const output = execSync(
77+
`d2 --layout=${layout} --theme=${theme} --sketch=${sketch} --pad=${padding} --dark-theme=${darkTheme} - -`,
78+
{
79+
input: fullCode,
80+
encoding: 'utf8',
81+
}
82+
);
83+
---
84+
85+
<Fragment set:html={output} />

0 commit comments

Comments
 (0)