Add per-image transparency checkerboard toggle for markdown content

Vanessa Ottorequested to merge
22133-better-preview-of-transparent-graphics into master

What does this MR do and why?

Add per-image transparency checkerboard toggle for markdown content

Images with transparency can be invisible when their content matches the page background color. This adds a toggle button (visible on hover) to each image in rendered markdown that enables a checkerboard background pattern, making transparent areas visible in any theme.

It does not show the button when the image either can't be transparent (e.g. JPEG file), or the PNG file has no transparent pixel at all.

Changelog: added

  • Tested in Chrome
  • Tested in Safari
  • Tested in Firefox
  • Tested on mobile (will verify a real mobile device once the change is on staging)

Screenshots or screen recordings

Text editor

Before After

When using keyboard instead of mouse/touchpad:

Diff View

Before After
Screenshot_2026-03-03_at_11.16.08 Screenshot_2026-03-03_at_11.14.28
Screenshot_2026-03-03_at_11.30.27 Screenshot_2026-03-03_at_11.31.55

How to set up and validate locally

Prerequisites

Prepare a transparent image. You can create them using the tool Transparent PNG Creator or download the following examples

PNGs with transparent backgrounds

test_image

transparent-test__2_

transparent-test__3_

transparent-test__4_

transparent-test

Text editors

  1. Go to any page with a comment box, e.g. http://gdk.test:3000/flightjs/Flight/-/issues/9
  2. Add a comment / note / description including a transparent image
  3. Click on preview and hover over the image to see the button. Toggle transparency button
  4. Save the comment / note / description and hover over the image to see the button. Toggle transparency button
  5. Repeat steps 2-4 in dark mode
  6. Upload another image, e.g. a JPG, and repeat the previous steps. There should be no button on hover.
  7. Upload a PNG, but without any transparency, and repeat the previous steps. There should be no button on hover.

Diff CSS View

To check the changes related to the diff.scss file, check any MR or commit which adds a transparent image. If you do not have one, execute the following steps:

  1. Go to any project's repository, e.g. http://gdk.test:3000/flightjs/Flight/-/tree/master
  2. Click on the plus button and 'Upload file'
  3. In the modal, drag drop a transparent image.
  4. Set branch to 'Commit to a new branch'
  5. Hit 'Commit changes'
  6. Create the merge request to have it available also in future
  7. Go to the changes / diff view
  8. If you want to check for the code, highlight the image and check for the img tag in the HTML

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #22133 (closed)

Edited by Vanessa Otto

Merge request reports