Add support for Graphviz diagrams

.github/actions/deploy-to-github-pages/action.yml

@@ -81,6 +81,13 @@ runs:
         find public/book public/docs -name \*.html -print0 |
         xargs -0r sed -i 's,http://git-scm\.com,https://git-scm.com,g'
 
+    - uses: actions/setup-node@v5
+    - name: pre-render the Graphviz diagrams
+      shell: bash
+      run: |
+        npm install node-html-parser &&
+        node ./script/graphviz-ssr.js
+
     - name: run Pagefind ${{ env.PAGEFIND_VERSION }} to build the search index
       shell: bash
       run: npx -y pagefind@${{ env.PAGEFIND_VERSION }} --site public --write-playground

.github/workflows/ci.yml

@@ -32,6 +32,12 @@ jobs:
           exit 1
         fi
 
+    - uses: actions/setup-node@v5
+    - name: pre-render the Graphviz diagrams
+      run: |
+        npm install node-html-parser &&
+        node ./script/graphviz-ssr.js
+
     - name: run Pagefind ${{ env.PAGEFIND_VERSION }} to build the search index
       run: npx -y pagefind@${{ env.PAGEFIND_VERSION }} --site public --write-playground
 

assets/js/application.js

@@ -782,6 +782,32 @@ var PostelizeAnchor = {
   },
 }
 
+var Graphviz = {
+  render: function() {
+    let vizInstance
+    [...document.querySelectorAll("pre[class=graphviz]")].forEach(async (x) => {
+      if (!vizInstance) vizInstance = await Viz.instance()
+      const options = {
+        format: "svg",
+        graphAttributes: {
+          bgcolor: "transparent",
+        },
+        engine: x.getAttribute("engine") || "dot",
+      }
+      const svg = vizInstance.renderString(x.innerText, options)
+      const img = document.createElement('img')
+      img.setAttribute(
+        'src',
+        `data:image/svg+xml;utf8,${encodeURIComponent(svg.substring(svg.indexOf('<svg')))}`
+      )
+      const alt = x.getAttribute("alt")
+      if (alt) img.setAttribute("alt", alt)
+      x.parentNode.insertBefore(img, x);
+      x.style.display = 'none'
+    });
+  }
+}
+
 // Scroll to Top
 $('#scrollToTop').removeClass('no-js');
 $(window).on('scroll', function() {

content/about/distributed.html

@@ -27,22 +27,101 @@ <h4>Subversion-Style Workflow</h4>
     A centralized workflow is very common, especially from people transitioning from a centralized system. Git will not allow you to push if someone has pushed since the last time you fetched, so a centralized model where all developers push to the same server works just fine.
     </p>
     <p class="center">
-    <img src="{{< relurl "images/about/workflow-a@2x.png" >}}" width="415" height="209" alt="Workflow A">
+    {{< graphviz alt="workflow A" >}}
+    digraph dev_workflow {
+      layout=neato;
+      overlap=false;
+      sep="+10";
+      node [shape=box, style="filled,rounded", penwidth=0, fontname="Helvetica"];
+      edge [penwidth=3, color="gray", arrowsize=0.5, dir=both];
+
+      shared_repo [label="shared repository", fillcolor=teal, fontcolor=white, pos="2,1.5!"];
+
+      developer1 [label="developer", fillcolor=lightblue, pos="0,0!"];
+      developer2 [label="developer", fillcolor=lightblue, pos="2,0!"];
+      developer3 [label="developer", fillcolor=lightblue, pos="4,0!"];
+
+      developer1 -> shared_repo;
+      developer2 -> shared_repo;
+      developer3 -> shared_repo;
+    }
+    {{< /graphviz >}}
     </p>
     <h4>Integration Manager Workflow</h4>
     <p>
     Another common Git workflow involves an integration manager — a single person who commits to the 'blessed' repository. A number of developers then clone from that repository, push to their own independent repositories, and ask the integrator to pull in their changes. This is the type of development model often seen with open source or GitHub repositories.
     </p>
     <p class="center">
-    <img src="{{< relurl "images/about/workflow-b@2x.png" >}}" width="407" height="164" alt="Workflow B">
+    {{< graphviz alt="workflow B" >}}
+    digraph workflow {
+      layout=neato;
+      overlap=false;
+      node [shape=box, style="filled,rounded", penwidth=0, fontname="Helvetica"];
+      edge [penwidth=3, color="gray", arrowsize=0.5];
+
+      // Nodes
+      blessed_repo [label="blessed\nrepository", fillcolor=teal, fontcolor=white, margin="0.3", pos="0,3!"];
+      integration_manager [label="integration\nmanager", fillcolor=orange, fontcolor=white, pos="0,1!"];
+
+      dev_pub1 [label="developer\npublic", fillcolor="#CCAA00", fontcolor=black, pos="2,3!"];
+      dev_pub2 [label="developer\npublic", fillcolor="#CCAA00", fontcolor=black, pos="4,3!"];
+
+      dev_priv1 [label="developer\nprivate", fillcolor="#CCAA00", fontcolor=black, pos="2,1!"];
+      dev_priv2 [label="developer\nprivate", fillcolor="#CCAA00", fontcolor=black, pos="4,1!"];
+
+      // Edges with labels
+      dev_priv1 -> dev_pub1;
+      dev_priv2 -> dev_pub2;
+      integration_manager -> blessed_repo;
+
+      dev_pub1 -> integration_manager [color="lightgray"];
+      dev_pub2 -> integration_manager [color="lightgray"];
+      blessed_repo -> dev_priv1 [color="lightgray"];
+      blessed_repo -> dev_priv2 [color="lightgray"];
+    }
+    {{< /graphviz >}}
     </p>
     <h4>Dictator and Lieutenants Workflow</h4>
     <p>
     For more massive projects, a development workflow like that of the Linux kernel is often effective.
     In this model, some people ('lieutenants') are in charge of a specific subsystem of the project and they merge in all changes related to that subsystem. Another integrator (the 'dictator') can pull changes from only his/her lieutenants and then push to the 'blessed' repository that everyone then clones from again.
     </p>
     <p class="center">
-    <img src="{{< relurl "images/about/workflow-c@2x.png" >}}" width="562" height="303" alt="Workflow C">
+    {{< graphviz alt="workflow C" >}}
+    digraph workflow {
+      layout=neato;
+      overlap=false;
+      node [shape=box, style="filled,rounded", penwidth=0, fontname="Helvetica"];
+      edge [penwidth=3, color="gray", arrowsize=0.5];
+
+      // Nodes
+      blessed_repo [label="blessed\nrepository", fillcolor=teal, fontcolor=white, margin="0.3", pos="6,4!"];
+      dictator [label="dictator", fillcolor=red, fontcolor=white, pos="0,4!"];
+
+      lieutenant1 [label="lieutenant", fillcolor="#CCAA00", fontcolor=white, pos="0,2.5!"];
+      lieutenant2 [label="lieutenant", fillcolor="#CCAA00", fontcolor=white, pos="2,3!"];
+
+      developer1 [label="developer", fillcolor=lightblue, fontcolor=black, pos="0,1!"];
+      developer2 [label="developer", fillcolor=lightblue, fontcolor=black, pos="2,1!"];
+      developer3 [label="developer", fillcolor=lightblue, fontcolor=black, pos="4,1!"];
+      developer4 [label="developer", fillcolor=lightblue, fontcolor=black, pos="6,1!"];
+
+      // Edges
+      dictator -> blessed_repo;
+      lieutenant1 -> dictator;
+      lieutenant2 -> dictator;
+
+      developer1 -> lieutenant1;
+      developer2 -> lieutenant1;
+      developer3 -> lieutenant2;
+      developer4 -> lieutenant2;
+
+      blessed_repo -> developer1;
+      blessed_repo -> developer2;
+      blessed_repo -> developer3;
+      blessed_repo -> developer4;
+    }
+    {{< /graphviz >}}
     </p>
     <div class="bottom-nav" style="display: block;">
       <a href="{{< relurl "about/small-and-fast" >}}" class="previous" data-section-id="small-and-fast">← Small and Fast</a>

content/diagram-list.html

@@ -0,0 +1,4 @@
+---
+outputs:
+  - json
+---

hugo.yml

@@ -12,6 +12,10 @@ markup:
   goldmark:
     renderer:
       unsafe: true
+mediaTypes:
+  application/json:
+    suffixes:
+    - json
 module:
   mounts:
   - source: content

layouts/_default/baseof.html

@@ -191,5 +191,9 @@ <h1 data-pagefind-meta="title">About{{ if (isset .Params "subtitle") }} - {{ .Pa
   {{ end }}
 
 </body>
+{{ if .Page.Store.Get "hasGraphviz" -}}
+<script src="{{ relURL "js/viz-global.js" }}"> </script>
+<script type="text/javascript">Graphviz.render();</script>
+{{ end -}}
 </html>
 {{ end }}

layouts/_default/single.json.json

@@ -0,0 +1,2 @@
+{{- $diagram_list := where .Site.Pages "RawContent" "like" "{{< graphviz" -}}
+{{- $diagram_list | jsonify -}}

layouts/shortcodes/graphviz.html

@@ -0,0 +1,4 @@
+<pre class="graphviz"{{ if (ne "" (.Get "engine")) }} engine="{{(.Get "engine")}}"{{ end }}{{ if (ne "" (.Get "alt")) }} alt="{{ (.Get "alt") }}"{{ end }}>
+  {{ .Inner | htmlEscape | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasGraphviz" true }}

package.json

@@ -5,6 +5,7 @@
   "license": "MIT",
   "devDependencies": {
     "@playwright/test": "^1.47.2",
-    "@types/node": "^22.5.4"
+    "@types/node": "^22.5.4",
+    "node-html-parser": "^7.0.1"
   }
 }

script/graphviz-ssr.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "node:fs"
+import { parse } from "node-html-parser"
+import Viz from "../static/js/viz-global.js"
+
+/*
+ * This script post-processes the site as generated via Hugo, replacing the
+ * `<pre class="graphviz">` elements with inline `<svg>` ones, pre-rendered
+ * via `viz-js`.
+ */
+;(async () => {
+  for (const { Path: pathInPublic } of JSON.parse(readFileSync("public/diagram-list.json", "utf-8"))) {
+    const path = `public${pathInPublic}.html`
+    const contents = readFileSync(path, "utf-8")
+    const html = parse(contents)
+    const vizImport = html.querySelector('script[src$="viz-global.js"]')
+    if (!vizImport) {
+      console.error(`No 'viz-global.js' import found in ${path}; skipping`)
+      continue
+    }
+    vizImport.nextElementSibling.remove() // remove the inline script
+    vizImport.remove() // remove the import
+
+    for (const pre of html.querySelectorAll("pre.graphviz")) {
+      const engine = pre.getAttribute("engine") || "dot"
+      const svg = (await Viz.instance()).renderString(pre.textContent, {
+        format: "svg",
+        graphAttributes: {
+          bgcolor: "transparent",
+        },
+        engine,
+      })
+      const alt = pre.getAttribute("alt")
+      const altAttr = !alt ? '' : ` alt='${alt.replaceAll("&", "&amp;").replaceAll("'", "&#39;")}'`
+      const dataURL = `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`
+      pre.replaceWith(`<img${altAttr} src="${dataURL}" />`)
+    }
+    console.log(`Rewriting ${path}`)
+    writeFileSync(`${path}`, html.toString())
+  }
+})().catch((e) => {
+  console.error(e)
+  process.exitCode = 1
+})