Add zoomable images feature by GuillaumeGomez · Pull Request #3127 · rust-lang/mdBook

GuillaumeGomez · 2026-05-26T16:14:23Z

Fixes #2075.

The "zoomed-in" image looks like this:

The JS is only used to "zoom out" images with the "escape key", otherwise the feature works entirely without JS.

It works as follows: there is a (hidden) checkbox right before the image. The image itself is inside the label associated to the checkbox, meaning that when you click on the image, you switch the value of the checkbox. And thanks to :checked CSS selector, it changes the display of the zoomed out image.

To make it obvious that you can "zoom in"/"zoom out" on an image, I changed the cursor to look like a loop using the CSS cursor: zoom-in|zoom-out property.

I also realized that images had the alt attribute, but not the title one, so I added it while I was at it.

GuillaumeGomez · 2026-05-26T17:06:24Z

Updated failing tests as well, ready for review. :)

GuillaumeGomez · 2026-06-08T16:13:10Z

ping @ehuss

ehuss · 2026-06-08T16:15:35Z

Won't this break images that are links?

GuillaumeGomez · 2026-06-08T16:22:19Z

I think it would yes. Didn't think about that. If I only allow to zoom on non-link images, does it sound good to you?

shenef · 2026-06-08T17:47:59Z

The description mentions the escape key for zooming back out, how would that work on a mobile device? Or does tapping it again toggle off the invisible checkbox?
I have a case where i currently use an image with a link to open a separate full-size version of the image. (740x638 -> 3712x3200)
So with this feature there would be no more need to do that.

GuillaumeGomez · 2026-06-08T17:56:41Z

The description mentions the escape key for zooming back out, how would that work on a mobile device? Or does tapping it again toggle off the invisible checkbox?

Tapping again will zoom-out.

GuillaumeGomez · 2026-06-08T19:47:27Z

@ehuss Disabled the feature on images inside links and extended test to check it as well.

ehuss

Thanks!

I'm not going to block on it, but this doesn't seem to support the ability to trigger with the keyboard. Generally we try to ensure to follow accessibility guidelines as much as we can.

Just curious, was it intentional that you can still scroll when the image is zoomed in? (I'm not sure if I have a preference, just checking.)

I'm slightly uneasy not having a way to turn this off. I'm fine with starting without it, but if people have issues, we may need to add something. In particular, small images like icons probably don't need or want to be zoomed in this way.

View changes since this review

ehuss · 2026-06-19T15:20:09Z

+                } else {
+                    img.insert_attr("title", alt.into());


Why was this fallback to add the alt as the title added?

I mentioned it in my first comment:

I also realized that images had the alt attribute, but not the title one, so I added it while I was at it.

It's better for accessibility, and for other users, to have text when they hover an image without moving for a while.

I think I would prefer to not do that. For example, MDN explicitly says:

avoid duplicating the alt attribute's value in a title attribute declared on the same image. Doing so may cause some screen readers to announce the same text twice, creating a confusing experience.

I also haven't seen other markdown renderers do something like this.

ehuss · 2026-06-20T21:00:36Z

+                    label.insert_attr("for", img_input_id.to_tendril());
+                    self.push(Node::Element(label));
+
+                    self.append(Node::Element(img.clone()));


I'm a little concerned about this approach of using a duplicated <img> tag. Screen readers may have difficulty handling this. I think at a minimum it should have aria-hidden="true". I'm a bit uncomfortable with this approach in general, though I'm willing to give it a try.

I think screen readers all handle display: none, so I think we're fine (although if we could test it, would be even better). However, won't aria-hidden=true be an issue when the image is zoomed-in?

I tried with my screen reader. It does seem to ignore the "display: none".

It's a little awkward now since the screen reader navigates to the checkbox (and says you are on a checkbox, and tells you the image alt), and then the image (and the alt and title). But I suppose it should be fine. We can adjust it if we get further feedback.

ehuss · 2026-06-20T21:36:42Z

+call-function: ("check-image-zoomed-in", {})
+
+// We click on the wrapper to "zoom out".
+click: ".checkbox-label > img"


Is it intentional that this clicks on the image underneath the wrapper? That is, should this be something like ".image-wrapper > img" or ".image-wrapper" to simulate what the user would actually click on?

Well, they click on the image, but the image being part of the label, since there is no preventDefault() on the image, the event is propagated to the parent until the parent is the label which then handles the click event and stops its propagation. So it is how users will interact with it.

ehuss · 2026-06-20T21:46:14Z

Also, it's probably a good idea to include at least some note in the documentation that this exists. Perhaps on the Images section?

GuillaumeGomez · 2026-06-22T13:39:07Z

I'm not going to block on it, but this doesn't seem to support the ability to trigger with the keyboard. Generally we try to ensure to follow accessibility guidelines as much as we can.

I was sure I tested that, I'll double-check and add a regression test to ensure it works.

Just curious, was it intentional that you can still scroll when the image is zoomed in? (I'm not sure if I have a preference, just checking.)

I didn't consider it an issue but I can do it if you want as even with JS (it's required for that as I need to change a parent's style, so cannot be done with only CSS).

I'm slightly uneasy not having a way to turn this off. I'm fine with starting without it, but if people have issues, we may need to add something. In particular, small images like icons probably don't need or want to be zoomed in this way.

I can add a CLI option for that if you want? As for small images, if I want to know their size, I would need another dependency for that. Not sure it's worth it but again, your call.

GuillaumeGomez · 2026-06-22T16:35:59Z

I simplified the DOM generation: no need for an ID anymore. We can now make the zoom in feature work with the keyboard (still no JS, works with spacebar). Added a GUI test for it as well. And mentioned it in the mdbook guide.

I didn't add a new CLI option to disable it yet. Waiting for you to confirm if you want it or not.

GuillaumeGomez · 2026-06-22T19:26:15Z

Updated tests with HTML comparisons. :)

GuillaumeGomez · 2026-06-29T20:29:39Z

Fixed merge conflict.

ehuss · 2026-07-02T00:01:42Z

I can add a CLI option for that if you want?

No, I don't think it's necessary for now. Also, all of the options for rendering go in the config, not the CLI. So, for example, this would probably go in the [output.html] section.

GuillaumeGomez · 2026-07-02T10:49:55Z

Removed the title attribute.

ehuss · 2026-07-02T17:26:02Z

-                if !title.is_empty() {
-                    img.insert_attr("title", title.into_tendril());
-                }


Looks like this deleted the title attribute entirely. It should probably just keep the original code here.

View changes since the review

Arf. I think I messed up when fixing the merge conflict when I removed the commit. Fixing that.

Ok it's back as it should. Sorry for the mess.

rustbot · 2026-07-02T21:05:05Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

GuillaumeGomez · 2026-07-02T21:16:18Z

Finally fixed my merge conflicts mess. ^^'

ehuss

Great, thanks!

View changes since this review

GuillaumeGomez requested a review from ehuss May 26, 2026 16:14

GuillaumeGomez mentioned this pull request May 26, 2026

Zoomable Images #2075

Closed

GuillaumeGomez force-pushed the zoom-in branch 2 times, most recently from e172cff to 4d67425 Compare May 26, 2026 16:19

rustbot added the S-waiting-on-review Status: waiting on a review label May 26, 2026

GuillaumeGomez force-pushed the zoom-in branch from 4d67425 to 3615043 Compare June 8, 2026 19:29

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the zoom-in branch 2 times, most recently from bb61242 to 83f42f9 Compare June 8, 2026 19:40

ehuss reviewed Jun 20, 2026

View reviewed changes

GuillaumeGomez force-pushed the zoom-in branch from ae1f95b to 1c226f2 Compare June 22, 2026 16:35

GuillaumeGomez mentioned this pull request Jun 22, 2026

Fix weird layout bug with images in links #3142

Merged

GuillaumeGomez force-pushed the zoom-in branch from 1c226f2 to 17d0639 Compare June 22, 2026 16:42

GuillaumeGomez force-pushed the zoom-in branch from 17d0639 to 03dd19a Compare June 23, 2026 16:13

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the zoom-in branch from 03dd19a to a3f31cf Compare June 29, 2026 20:29

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the zoom-in branch from a3f31cf to c551c43 Compare July 2, 2026 10:49

ehuss reviewed Jul 2, 2026

View reviewed changes

GuillaumeGomez force-pushed the zoom-in branch 2 times, most recently from 41c5578 to 5413eb8 Compare July 2, 2026 20:56

This comment has been minimized.

Sign in to view

GuillaumeGomez added 5 commits July 2, 2026 22:58

Add "zoom-in" feature on images

71fb5a8

Add title attribute on images

9de2755

Add regression test for the "zoom-in" feature

6a7ef4d

Add possibility to "zoom out" using the escape key

73d6edf

Only enable "zoom-in" feature on images not inside links

f526b18

GuillaumeGomez force-pushed the zoom-in branch from 5413eb8 to 946e2ae Compare July 2, 2026 21:05

GuillaumeGomez added 2 commits July 2, 2026 23:09

Make the "zoom in" feature work with keyboard and simplify DOM

588066c

Mention zoom-in feature in mdbook guide

beab2fa

GuillaumeGomez force-pushed the zoom-in branch from 946e2ae to beab2fa Compare July 2, 2026 21:09

ehuss approved these changes Jul 3, 2026

View reviewed changes

ehuss added this pull request to the merge queue Jul 3, 2026

Merged via the queue into rust-lang:master with commit 8b53f1b Jul 3, 2026
15 checks passed

rustbot removed the S-waiting-on-review Status: waiting on a review label Jul 3, 2026

GuillaumeGomez deleted the zoom-in branch July 3, 2026 15:13

Uh oh!

Conversation

GuillaumeGomez commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GuillaumeGomez commented May 26, 2026

Uh oh!

GuillaumeGomez commented Jun 8, 2026

Uh oh!

ehuss commented Jun 8, 2026

Uh oh!

GuillaumeGomez commented Jun 8, 2026

Uh oh!

shenef commented Jun 8, 2026

Uh oh!

GuillaumeGomez commented Jun 8, 2026

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 8, 2026

Uh oh!

ehuss left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ehuss commented Jun 20, 2026

Uh oh!

GuillaumeGomez commented Jun 22, 2026

Uh oh!

GuillaumeGomez commented Jun 22, 2026

Uh oh!

GuillaumeGomez commented Jun 22, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Jun 29, 2026

Uh oh!

ehuss commented Jul 2, 2026

Uh oh!

GuillaumeGomez commented Jul 2, 2026

Uh oh!

ehuss Jul 2, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

rustbot commented Jul 2, 2026

Uh oh!

GuillaumeGomez commented Jul 2, 2026

Uh oh!

ehuss left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GuillaumeGomez commented May 26, 2026 •

edited

Loading

ehuss left a comment •

edited by rustbot

Loading

ehuss Jul 2, 2026 •

edited by rustbot

Loading

ehuss left a comment •

edited by rustbot

Loading