Add D2 diagram support to documentation

 (#241)

Integrates D2 diagramming tool into the website build pipeline, enabling architecture diagrams directly in MDX files.

## Changes

- **Added** **`astro-d2`** **integration** with pgflow brand colors for light/dark themes
- **Created** **`.github/actions/setup-d2`** - reusable action to install D2 CLI with retry logic
- **Updated CI workflow** to install D2 before building website
- **Added** **`public/d2/`** **to gitignore** - SVGs are generated at build time

## How it works

Write D2 diagrams in MDX files using ````d2` code blocks:

```
direction: down
worker: "Edge Worker" {
  shape: cloud
}
```

At build time:

1. `astro-d2` renders diagrams to SVG in `public/d2/`
2. Code blocks are replaced with `<img>` tags
3. Static assets deploy to Cloudflare Pages

## Example

See `/concepts/how-pgflow-works/` for live diagrams showing the three-layer architecture.

Author: jumski

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

@@ -0,0 +1,23 @@
+name: 'Setup D2'
+description: 'Install D2 diagramming tool with retry logic'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install D2
+      shell: bash
+      run: |
+        for i in 1 2 3 4 5; do
+          echo "Attempt $i to install D2..."
+          if curl -fsSL https://d2lang.com/install.sh | sh -s --; then
+            echo "D2 installed successfully"
+            break
+          else
+            if [ $i -eq 5 ]; then
+              echo "Failed to install D2 after 5 attempts"
+              exit 1
+            fi
+            echo "Install failed, retrying in 5 seconds..."
+            sleep 5
+          fi
+        done

.github/workflows/ci.yml

@@ -94,8 +94,8 @@ jobs:
       - name: Quality gate (lint + typecheck + test)
         run: pnpm nx affected -t lint typecheck test --parallel --configuration=production --base="$NX_BASE" --head="$NX_HEAD"
 
-      - name: Build all affected projects
-        run: pnpm nx affected -t build --configuration=production --parallel --base="$NX_BASE" --head="$NX_HEAD"
+      - name: Build all affected packages (excludes website and demo - they build during deploy)
+        run: pnpm nx affected -t build --configuration=production --parallel --exclude=website,demo --base="$NX_BASE" --head="$NX_HEAD"
 
       - name: Verify exports for built packages
         run: pnpm nx affected -t verify-exports --base="$NX_BASE" --head="$NX_HEAD"
@@ -306,6 +306,8 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           atlas-cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
 
+      - uses: ./.github/actions/setup-d2
+
       - name: Check if website is affected
         id: check-affected
         run: |

pkgs/website/.gitignore

@@ -19,4 +19,7 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+
+# generated files
 public/edge-worker/
+public/d2/

pkgs/website/astro.config.mjs

@@ -8,6 +8,7 @@ import robotsTxt from 'astro-robots-txt';
 import starlightLlmsTxt from 'starlight-llms-txt';
 import starlightContextualMenu from 'starlight-contextual-menu';
 import starlightImageZoom from 'starlight-image-zoom';
+import d2 from 'astro-d2';
 import { fileURLToPath } from 'url';
 import path from 'path';
 
@@ -70,6 +71,7 @@ export default defineConfig({
   redirects,
 
   integrations: [
+    d2(),
     react({
       include: ['**/components/**/*.tsx'],
       exclude: ['**/pages/**/*'],
@@ -433,6 +435,7 @@ export default defineConfig({
               '/author',
               '/demos',
               '/demo-colors',
+              '/d2-guide',
               '/news',
               '/news/**',
               '/edge-worker',

pkgs/website/package.json

@@ -22,6 +22,7 @@
     "@types/react-dom": "^19.1.7",
     "@vercel/analytics": "^1.5.0",
     "astro": "^5.7.14",
+    "astro-d2": "^0.8.0",
     "astro-robots-txt": "^1.0.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",

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

@@ -0,0 +1,103 @@
+vars: {
+  d2-config: {
+    theme-id: 0
+    dark-theme-overrides: {
+      # Canvas background
+      N7: "#121a19"
+
+      # Neutrals - desaturated grays for default nodes
+      N1: "#e8eced"
+      N2: "#c5cacc"
+      N3: "#95a0a3"
+      N4: "#4a5759"
+      N5: "#2d3739"
+      N6: "#1a2324"
+
+      # Borders - neutral grays
+      B1: "#3a4547"
+      B2: "#4a5759"
+      B3: "#5a6769"
+      B4: "#1a2324"
+      B5: "#2d3739"
+      B6: "#4a5759"
+
+      # Semantic colors - intentional states
+      AA2: "#a87c45"
+      AA4: "#a33636"
+      AA5: "#4d3d2b"
+      AB4: "#247056"
+      AB5: "#34578f"
+    }
+  }
+}
+
+# Semantic color classes for workflow states
+classes: {
+  # Generic semantic classes (for general use)
+  neutral: {
+    style.fill: "#95a0a3"
+    style.stroke: "#4a5759"
+  }
+  info: {
+    style.fill: "#34578f"
+    style.stroke: "#5c8dd6"
+  }
+  warning: {
+    style.fill: "#a87c45"
+    style.stroke: "#d9a66e"
+  }
+  error: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+  success: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+
+  # Run state classes (started, completed, failed)
+  run_started: {
+    style.fill: "#34578f"
+    style.stroke: "#5c8dd6"
+  }
+  run_completed: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+  run_failed: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+
+  # Step state classes (created, started, completed, failed)
+  step_created: {
+    style.fill: "#95a0a3"
+    style.stroke: "#4a5759"
+  }
+  step_started: {
+    style.fill: "#34578f"
+    style.stroke: "#5c8dd6"
+  }
+  step_completed: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+  step_failed: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+
+  # Task state classes (queued, completed, failed)
+  task_queued: {
+    style.fill: "#95a0a3"
+    style.stroke: "#4a5759"
+  }
+  task_completed: {
+    style.fill: "#247056"
+    style.stroke: "#33cc7f"
+  }
+  task_failed: {
+    style.fill: "#a33636"
+    style.stroke: "#e85c5c"
+  }
+}