diff --git a/assets/diagrams/README.md b/assets/diagrams/README.md index 0b74734c..85e4d295 100644 --- a/assets/diagrams/README.md +++ b/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. diff --git a/assets/diagrams/membership.png b/assets/diagrams/membership.png deleted file mode 100644 index 76198015..00000000 Binary files a/assets/diagrams/membership.png and /dev/null differ diff --git a/assets/diagrams/membership.webp b/assets/diagrams/membership.webp new file mode 100644 index 00000000..08404d1a Binary files /dev/null and b/assets/diagrams/membership.webp differ diff --git a/assets/diagrams/threaded-dag-threads.png b/assets/diagrams/threaded-dag-threads.png deleted file mode 100644 index 4cf865ed..00000000 Binary files a/assets/diagrams/threaded-dag-threads.png and /dev/null differ diff --git a/assets/diagrams/threaded-dag-threads.webp b/assets/diagrams/threaded-dag-threads.webp new file mode 100644 index 00000000..304ba9b7 Binary files /dev/null and b/assets/diagrams/threaded-dag-threads.webp differ diff --git a/assets/diagrams/threaded-dag.png b/assets/diagrams/threaded-dag.png deleted file mode 100644 index 085d0f09..00000000 Binary files a/assets/diagrams/threaded-dag.png and /dev/null differ diff --git a/assets/diagrams/threaded-dag.webp b/assets/diagrams/threaded-dag.webp new file mode 100644 index 00000000..c62873a5 Binary files /dev/null and b/assets/diagrams/threaded-dag.webp differ diff --git a/changelogs/internal/newsfragments/1999.clarification b/changelogs/internal/newsfragments/1999.clarification new file mode 100644 index 00000000..94017535 --- /dev/null +++ b/changelogs/internal/newsfragments/1999.clarification @@ -0,0 +1 @@ +Improve the quality of the rendered diagrams diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 66ca6316..bfcbd031 100644 --- a/content/client-server-api/_index.md +++ b/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" %}} diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index f4d87f25..877103fe 100644 --- a/content/client-server-api/modules/receipts.md +++ b/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. diff --git a/layouts/shortcodes/diagram.html b/layouts/shortcodes/diagram.html new file mode 100644 index 00000000..035dbdf1 --- /dev/null +++ b/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) -}} + + + + {{ $alt }} + +{{- else -}} + {{- errorf "diagram %s not found" $path -}} +{{- end -}}