Improve the quality of the rendered diagrams

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