graphviz: optionally pre-generate the SVGs

The WebAssembly version of Graphviz is not exactly light (1.4 megabytes
at the time of writing). And it wasteful to let everybody re-render the
SVG client-side over and over again even though the diagram's definition
hasn't changed. So let's add a script that performs that rendering "on
the server side" (more precisely: during deployment).

This script takes no arguments and post-processes the output of Hugo
in `public/`.

For performance reasons, it requires the list of files that contain
Graphviz diagrams. With other sites, it might not matter much because
there might only be a handful pages. However, on git-scm.com there _are_
thousands of files that do not contain any Graphviz diagrams, and
therefore it is a necessary optimization to process only the files that
_do_ contain Graphviz diagrams.

To get that list, a new layout and page are added that Hugo processes,
identifying said list of files and writing the result to
`public/diagram-list.html`.

Since this script runs via Node.JS and therefore lacks the convenient
built-in HTML parser of browser-based JavaScript engines, a prerequisite
is to run `npm install` so that the `node-html-parser` package is
available.

A note about the slightly inelegant way the `graphviz` class is added to
the generated SVGs: Sadly, `node-html-parser` is not smart enough to
handle `element.classList.add(...)` followed by `element.toString()`
correctly, and as a result the output would _not_ have the added class.
But there's always crude string processing to save the day.

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

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/single.json.json

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

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,43 @@
+#!/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 dataURL = `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`
+      pre.replaceWith(`<img src="${dataURL}" />`)
+    }
+    console.log(`Rewriting ${path}`)
+    writeFileSync(`${path}`, html.toString())
+  }
+})().catch((e) => {
+  console.error(e)
+  process.exitCode = 1
+})