Merge branch 'graphviz-diagrams' into gh-pages

This topic corresponds to git#2052.

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

Author: dscho

.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: offer PDF version of the cheat sheet
       shell: bash
       run: |

.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: Install @playwright/test
       run: npm install @playwright/test
     - name: offer PDF version of the cheat sheet

assets/js/application.js

@@ -783,6 +783,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'
+    });
+  }
+}
+
 var Print = {
   init: function() {
     Print.tagline = $("#tagline");

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/[email protected]" >}}" 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, 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/[email protected]" >}}" 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];
+
+      // 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="gray"];
+      dev_pub2 -> integration_manager [color="gray"];
+      blessed_repo -> dev_priv1 [color="gray"];
+      blessed_repo -> dev_priv2 [color="gray"];
+    }
+    {{< /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/[email protected]" >}}" 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 [fontname="Helvetica", penwidth=3];
+
+      // 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"
   }
 }