chore(build): improve Mermaid integration and CI infrastructure

- Remove mkdocs-mermaid2-plugin from dependencies (conflicts with Material's native support)
- Add Mermaid.js configuration file with EKGF brand colors
- Enhance CSS selectors for comprehensive Mermaid diagram styling (indigo blue boxes, orange links)
- Switch GitHub Actions runner from macOS to Ubuntu (faster, more cost-effective)
- Update Python version to 3.14 in CI workflow
- Fix Makefile to properly skip Homebrew on Linux
- Update lockfile after dependency changes

Author: jgeluk

.github/workflows/docs.yml

@@ -7,30 +7,37 @@ on:
   pull_request:
   workflow_dispatch:
 
-env:
-  HOMEBREW_NO_INSTALL_CLEANUP: 1
-
 jobs:
   build:
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     steps:
-#      -
-#        name: Install some tools
-#        run: sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
-#      -
-#        name: Set up Homebrew
-#        id: set-up-homebrew
-#        uses: Homebrew/actions/setup-homebrew@master
-      -
-        name: Install Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.13'
       -
         name: Set up Git repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      -
+        name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libcairo2-dev \
+            libpango1.0-dev \
+            libfreetype6-dev \
+            libffi-dev \
+            libjpeg-dev \
+            libpng-dev \
+            zlib1g-dev \
+            graphviz \
+            libgraphviz-dev
+      -
+        name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      -
+        name: Install uv
+        run: pip install uv
       -
         name: Cache uv dependencies
         uses: actions/cache@v4
@@ -43,9 +50,7 @@ jobs:
             ${{ runner.os }}-uv-
       -
         name: Install all MkDocs dependencies
-        run: |
-          # echo "/home/linuxbrew/.linuxbrew/bin/brew" >> $GITHUB_PATH
-          make --environment-overrides docs-install-github-actions
+        run: make --environment-overrides docs-install-github-actions
       -
         name: Build Site
         # Build runs on all branches and PRs to validate changes

Makefile

@@ -68,6 +68,10 @@ docs-install: docs-install-brew docs-install-brew-packages docs-install-python-p
 docs-install-github-actions: docs-install-brew-packages docs-install-python-packages info
 
 .PHONY: docs-install-brew-packages
+ifeq ($(YOUR_OS), Linux)
+docs-install-brew-packages:
+	@echo "Skip Homebrew packages on Linux (installed via apt-get in CI)"
+else
 docs-install-brew-packages:
 	@echo "Install packages via HomeBrew:"
 	@brew upgrade cairo 2>/dev/null || brew install cairo
@@ -79,6 +83,7 @@ docs-install-brew-packages:
 	@brew upgrade zlib 2>/dev/null || brew install zlib
 	@brew upgrade graphviz 2>/dev/null || brew install graphviz
 	@brew upgrade uv 2>/dev/null || brew install uv
+endif
 
 .PHONY: docs-install-brew
 ifeq ($(YOUR_OS), Linux)

docs/stylesheets/extra.css

@@ -19,63 +19,70 @@
 }
 
 /* Force Mermaid diagram elements to use EKGF colors */
-/* Node backgrounds - indigo blue */
+/* Apply to all possible rect elements - node backgrounds - indigo blue */
+.mermaid rect,
 .mermaid .node rect,
 .mermaid .node circle,
 .mermaid .node ellipse,
 .mermaid .node polygon,
 .mermaid .cluster rect,
-.mermaid g.classGroup rect {
+.mermaid g.classGroup rect,
+.mermaid g rect.divider,
+.mermaid g.classGroup > rect:first-child,
+.mermaid svg g rect {
   fill: #4051b5 !important;
-}
-
-/* Node borders - orange */
-.mermaid .node rect,
-.mermaid .node circle,
-.mermaid .node ellipse,
-.mermaid .node polygon,
-.mermaid .cluster rect,
-.mermaid g.classGroup rect {
   stroke: #ff6f00 !important;
   stroke-width: 2px !important;
 }
 
-/* Connector lines and arrows - orange */
+/* Connector lines, relations, and arrows - orange */
+.mermaid path,
+.mermaid line,
 .mermaid .edgePath path,
 .mermaid .flowchart-link,
 .mermaid line.relation,
 .mermaid path.relation,
 .mermaid line[class*="messageLine"],
-.mermaid path[class*="messageLine"] {
+.mermaid path[class*="messageLine"],
+.mermaid .relationshipLine {
   stroke: #ff6f00 !important;
   stroke-width: 2px !important;
 }
 
 /* Arrow markers - orange */
 .mermaid marker path,
-.mermaid defs marker path {
+.mermaid defs marker path,
+.mermaid marker polygon {
   fill: #ff6f00 !important;
   stroke: #ff6f00 !important;
 }
 
 /* Text labels on nodes - white */
+.mermaid text,
 .mermaid .nodeLabel,
 .mermaid text.nodeLabel,
 .mermaid .node text,
 .mermaid .classLabel .label,
-.mermaid tspan {
+.mermaid tspan,
+.mermaid g.classGroup text,
+.mermaid .classLabel text {
   fill: #ffffff !important;
   color: #ffffff !important;
 }
 
-/* Edge labels - keep dark for readability */
+/* Edge labels - keep dark for readability on light background */
 .mermaid .edgeLabel,
 .mermaid .edgeLabel text,
-.mermaid .edgeLabel tspan {
+.mermaid .edgeLabel tspan,
+.mermaid .edgeLabel rect {
   fill: #333333 !important;
   color: #333333 !important;
 }
 
+.mermaid .edgeLabel rect {
+  fill: #ffffff !important;
+}
+
 /* Dark mode edge label adjustments */
 [data-md-color-scheme="slate"] .mermaid .edgeLabel,
 [data-md-color-scheme="slate"] .mermaid .edgeLabel text,
@@ -84,6 +91,10 @@
   color: #ffffff !important;
 }
 
+[data-md-color-scheme="slate"] .mermaid .edgeLabel rect {
+  fill: #1e1e1e !important;
+}
+
 /* Card Design Enhancements */
 
 /* Grid cards container - improved spacing */

mkdocs.yml

@@ -69,7 +69,8 @@ extra:
   analytics:
     provider: google
     property: G-9LCW4TSSRP
-extra_javascript: []
+extra_javascript:
+  - javascripts/mermaid.js
 plugins:
   - include-markdown
   - git-revision-date-localized:
@@ -150,6 +151,13 @@ markdown_extensions:
       options:
         custom_icons:
           - docs-overrides/.icons
+  # Mermaid diagram support - using Material for MkDocs native integration
+  # NOTE: Do NOT use mkdocs-mermaid2-plugin - it conflicts with Material's native support
+  # Material for MkDocs has built-in Mermaid.js support that works better with instant loading
+  # Custom colors are configured using:
+  #   1. Theme palette set to 'custom' (primary/accent colors)
+  #   2. CSS variables in docs/stylesheets/extra.css
+  #   3. Inline %%{init}%% directives in individual diagrams (docs/fragment/uctm-diagram-*.md)
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid

pyproject.toml

@@ -21,7 +21,6 @@ dependencies = [
   "mkdocs-include-markdown-plugin",
   "mkdocs-localsearch",
   "mkdocs-macros-plugin",
-  "mkdocs-mermaid2-plugin",
   "mkdocs-minify-plugin",
   "mkdocs-redirects",
   "mkdocs-kroki-plugin",