From 85e6cec1dbdd01f0ffdf9d0fee370e2a9d4fa102 Mon Sep 17 00:00:00 2001 From: Karl Stolley Date: Mon, 13 Oct 2025 14:38:34 -0500 Subject: [PATCH] api_docs: Better structure Image previews section. --- api_docs/changelog.md | 8 ++++---- api_docs/message-formatting.md | 16 +++++++++++----- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 3bbffc4e22..62a09ceb24 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -866,7 +866,7 @@ deactivated groups. **Feature level 336** -* [Markdown message formatting](/api/message-formatting#image-previews): Added +* [Markdown message formatting](/api/message-formatting#images): Added `data-original-content-type` attribute to convey the type of the original image, and optional `data-transcoded-image` attribute for images with formats which are not widely supported by browsers. @@ -1435,7 +1435,7 @@ deactivated groups. **Feature level 287** * [Markdown message - formatting](/api/message-formatting#image-previews): Added + formatting](/api/message-formatting#images): Added `data-original-dimensions` attributes to placeholder images (`image-loading-placeholder`), containing the dimensions of the original image. This change was also backported to the Zulip 9.x @@ -1511,7 +1511,7 @@ releases. **Feature level 278** * [Markdown message - formatting](/api/message-formatting#image-previews): Added + formatting](/api/message-formatting#images): Added `data-original-dimensions` attributes to placeholder images (`image-loading-placeholder`), containing the dimensions of the original image. Backported change from feature level 287. @@ -1524,7 +1524,7 @@ No changes; feature level used for Zulip 9.0 release. **Feature level 276** -* [Markdown message formatting](/api/message-formatting#image-previews): +* [Markdown message formatting](/api/message-formatting#images): Image preview elements not contain a `data-original-dimensions` attribute containing the dimensions of the original image. diff --git a/api_docs/message-formatting.md b/api_docs/message-formatting.md index a69c012213..dd7ff7171c 100644 --- a/api_docs/message-formatting.md +++ b/api_docs/message-formatting.md @@ -121,10 +121,10 @@ the href for those is the default behavior of the link that also encodes the channel alongside the data-stream-id field, but clients can override that default based on `web_channel_default_view` setting. -## Image previews +## Images When a Zulip message is sent linking to an uploaded image, Zulip will -generate an image preview element with the following format. +generate an image preview element with the following format: ``` html
@@ -136,6 +136,8 @@ generate an image preview element with the following format.
``` +### Image-loading placeholders + If the server has not yet generated thumbnails for the image yet at the time the message is sent, the `img` element will be a temporary loading indicator image and have the `image-loading-placeholder` @@ -168,6 +170,8 @@ backlogged, an individual message containing multiple image previews may be re-rendered multiple times as each image finishes thumbnailing and triggers a message update. +### Recommended client processing of image previews + Clients are recommended to do the following when processing image previews: @@ -217,16 +221,18 @@ previews: format match what they requested. - No other processing of the URLs is recommended. -**Changes**: In Zulip 10.0 (feature level 336), added +### Changes to image formatting + +**In Zulip 10.0** (feature level 336), added `data-original-content-type` attribute to convey the type of the original image, and optional `data-transcoded-image` attribute for images with formats which are not widely supported by browsers. -**Changes**: In Zulip 9.2 (feature levels 278-279, and 287+), added +**In Zulip 9.2** (feature levels 278-279, and 287+), added `data-original-dimensions` to the `image-loading-placeholder` spinner images, containing the dimensions of the original image. -In Zulip 9.0 (feature level 276), added `data-original-dimensions` +**In Zulip 9.0** (feature level 276), added `data-original-dimensions` attribute to images that have been thumbnailed, containing the dimensions of the full-size version of the image. Thumbnailing itself was reintroduced at feature level 275.