Add support for Graphviz diagrams (#2052)

dscho · web-flow · commit 992366e18fc1 · 2025-09-13T12:10:09.000Z
## Changes - This adds support for Graphviz diagrams and replaces the `.png`s in https://git-scm.com/about/distributed with scalable versions. ## Context Over in #2049, we discussed various options how to add elegant diagrams, and settled on Graphviz ones. I broke this out so that I don't have to derail the discussion about the cheat sheet anymore. The solution presented here uses [`viz.js`](https://viz-js.com/), a WebAssembly version of Graphviz. Since it weighs a bit much (1.4MB), this is used client-side only when developing the page locally; When the site gets deployed, the SVGs are "pre-rendered", i.e. generated and inserted in place of the `<pre class="graphviz">` blocks. To demonstrate this new feature, I replaced the diagrams in https://git-scm.com/about/distributed with Graphviz ones: | before | after | | - | - | | ![workflow-a as PNG](https://github.com/git/git-scm.com/blob/802cbb4d3b71960972e9a09a78bab439eb303c29/static/images/about/workflow-a@2x.png?raw=true) | ![workflow-A](https://github.com/user-attachments/assets/c6f28d06-b64d-46f7-b220-dcb241e818f0) | | ![workflow-b as PNG](https://github.com/git/git-scm.com/blob/802cbb4d3b71960972e9a09a78bab439eb303c29/static/images/about/workflow-b@2x.png?raw=true) | ![workflow-B](https://github.com/user-attachments/assets/6de3510d-818a-4118-96cf-043ba3bf3ab8) | | ![workflow-c as PNG](https://github.com/git/git-scm.com/blob/802cbb4d3b71960972e9a09a78bab439eb303c29/static/images/about/workflow-c@2x.png?raw=true) | ![workflow-C](https://github.com/user-attachments/assets/89fc9699-6374-497f-bef6-aea715f0bb4f) | The changes of this PR can also be seen in action in my fork: https://dscho.github.io/git-scm.com/about/distributed
diff --git a/.github/actions/deploy-to-github-pages/action.yml b/.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
diff --git a/.github/workflows/ci.yml b/.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
 
diff --git a/assets/js/application.js b/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() {
diff --git a/content/about/distributed.html b/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>
diff --git a/content/diagram-list.html b/content/diagram-list.html
@@ -0,0 +1,4 @@
+---
+outputs:
+  - json
+---
diff --git a/hugo.yml b/hugo.yml
@@ -12,6 +12,10 @@ markup:
   goldmark:
     renderer:
       unsafe: true
+mediaTypes:
+  application/json:
+    suffixes:
+    - json
 module:
   mounts:
   - source: content
diff --git a/layouts/_default/baseof.html b/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 }}
diff --git a/layouts/_default/single.json.json b/layouts/_default/single.json.json
@@ -0,0 +1,2 @@
+{{- $diagram_list := where .Site.Pages "RawContent" "like" "{{< graphviz" -}}
+{{- $diagram_list | jsonify -}}
diff --git a/layouts/shortcodes/graphviz.html b/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 }}
diff --git a/package.json b/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"
   }
 }
diff --git a/script/graphviz-ssr.js b/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
+})
diff --git a/static/js/viz-global.js b/static/js/viz-global.js

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +outputs:
 +  - json
 +---
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+{{- $diagram_list := where .Site.Pages "RawContent" "like" "{{< graphviz" -}}`
	`2`	`+{{- $diagram_list \| jsonify -}}`
Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"devDependencies": {`
`7`	`7`	`"@playwright/test": "^1.47.2",`
`8`		`- "@types/node": "^22.5.4"`
	`8`	`+ "@types/node": "^22.5.4",`
	`9`	`+ "node-html-parser": "^7.0.1"`
`9`	`10`	`}`
`10`	`11`	`}`