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>

assets/diagrams/README.md

@@ -7,11 +7,17 @@ https://www.diagrams.net/ is a great ([open source](https://github.com/jgraph/dr
 tool for these sorts of things - include your `.drawio` file next to your diagram.
 
 Suggested settings for diagrams.net:
-* Export as PNG.
-* 100% size.
+* Export as WebP.
+* 200% size.
 * `20` for a border width.
-* No transparent background, shadow, or grid.
-* Include a copy of the diagram.
+* Light appearance.
+* No shadow, or grid.
 
-To reference a diagram, use the absolute path when compiled. For example,
-`![membership-flow-diagram](/diagrams/membership.png)`
+To reference a diagram, use the `diagram` shortcode. For example:
+
+```
+{{% diagram name="membership" alt="Diagram presenting the possible membership state transitions" %}}
+```
+
+Where `name` is the file name without extension, and `alt` is a textual
+replacement for the image, useful for accessibility.

changelogs/internal/newsfragments/1999.clarification

@@ -0,0 +1 @@
+Improve the quality of the rendered diagrams

content/client-server-api/_index.md

@@ -2572,7 +2572,7 @@ Note that this rule is only expected to work in room versions
 
 The allowable state transitions of membership are:
 
-![membership-flow-diagram](/diagrams/membership.png)
+{{% diagram name="membership" alt="Diagram presenting the possible membership state transitions" %}}
 
 {{% http-api spec="client-server" api="list_joined_rooms" %}}
 

content/client-server-api/modules/receipts.md

@@ -155,12 +155,12 @@ related to a thread root via non-thread relations.
 The following is an example DAG for a room, with dotted lines showing event
 relationships and solid lines showing topological ordering.
 
-![threaded-dag](/diagrams/threaded-dag.png)
+{{% diagram name="threaded-dag" alt="Diagram presenting a DAG with thread relationships as a single timeline" %}}
 
 This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread
 roots:
 
-![threaded-dag-threads](/diagrams/threaded-dag-threads.png)
+{{% diagram name="threaded-dag-threads" alt="Diagram presenting a DAG with thread relationships as 3 related timelines" %}}
 
 With this, we can demonstrate that:
 * A threaded read receipt on `I` would mark `A`, `B`, and `I` as read.

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 -}}