Improve the quality of the rendered diagrams (#1999)

The first commit allows to lazy-load the diagrams, which should improve the loading time of the CS API on mobile. In the process it also improves the alt text of the images.

The second commit serves the diagrams as high-resolution WebPs. Encoding a high resolution diagram as WebP gives a file of approximately the same size as the lower resolution PNG. For maximum compatibility we also serve them as a lower resolution WebP and a fallback PNG. WebP was chosen because it is one of the export formats of draw.io/diagrams.net, and it is widely available in modern browsers.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

layouts/shortcodes/diagram.html

@@ -0,0 +1,53 @@
+{{- /*
+
+    This template is used to render an image representing a diagram.
+
+    It takes the following parameters:
+
+    * `name` (required): the file name without extension.
+    * `alt` (required): a textual replacement for the image, useful for
+      accessibility.
+    
+    Other requirements for diagrams:
+
+    * They must be located in `/assets/diagrams`.
+    * They must be WebP images, with a `.webp` file extension.
+    * They must be rendered at a 200% scale. 
+
+    Differences with loading a diagram as a regular markdown image:
+
+    * The diagram is lazy-loaded, which should speed up the loading of the spec.
+    * The dimensions of the diagram are added to the HTML, allowing the browser
+      to pre-allocate space before it is loaded.
+    * The diagram supports devices with high pixel density screens and a WebP
+      image is generated for the default resolution.
+    * A PNG fallback image is generated, for maximum browser compatibility.
+
+*/ -}}
+
+{{- $name := .Params.name -}}
+{{- $alt := .Params.alt -}}
+
+{{- $path := printf "/diagrams/%s.webp" $name -}}
+
+{{- with resources.Get $path -}}
+    {{- $highRes := . -}}
+
+    {{- /*
+        The high resolution image has a scale of 200% so we need to divide the
+        dimensions by 2 to get the real one.
+    */ -}}
+    {{- $width := div $highRes.Width 2 | string -}}
+    {{- $height := div $highRes.Width 2 | string -}}
+
+    {{- /* Generate a low resolution WebP and a fallback PNG. */ -}}
+    {{- $lowRes := $highRes.Resize (printf "%sx webp drawing" $width) -}}
+    {{- $fallback := $highRes.Resize (printf "%sx png" $width) -}}
+
+<picture>
+    <source srcset="{{ $lowRes.RelPermalink }}, {{ $highRes.RelPermalink }} 2x" type="image/webp" />
+    <img src="{{ $fallback.RelPermalink }}" alt="{{ $alt }}" width="{{ $width }}" height="{{ $height }}" loading="lazy" />
+</picture>
+{{- else -}}
+    {{- errorf "diagram %s not found" $path -}}
+{{- end -}}