Image distortion (stretching vertically)

[DanRoscigno]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Prerequisites

• [X] I'm using the latest version of Docusaurus.
• [X] I have tried the npm run clear or yarn clear command.
• [X] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• [X] I have tried creating a repro with https://new.docusaurus.io.
• [X] I have read the console error message carefully (if applicable).

Description

I am migrating from Gatsby to Docusaurus 3 (I am running rc-1). I am seeing distortion in images. The example shown in the links below is added to the doc with ![alter](../assets/6.1.2-2.png)

Images are distorted, stretched vertically.

I am running a basic Docusaurus v3 install (rc 1 from yesterday), I did not add change any settings, just enabled i18n, versioning, and auto-collapse on sidebar categories.

example in Docusaurus v3 (1/3 down the page)

original image

example in Gatsby

Reproducible demo

[email protected]:DanRoscigno/docusaurus-image-stretch.git

Steps to reproduce

I can't reproduce this in a small site. My docs have 7,000 pages, and I suspect that this may have something to do with it. I am going to try some experiments (only build one locale, and if necessary only one version in one locale) to see if I can see when the images get distorted.

I will add a comment when I try the above experiment.

1. clone the above repo
2. yarn install
3. yarn build
4. yarn serve
5. open http://localhost:3001/docs/tutorial-basics/create-a-document

Expected behavior

I would like the images to appear as if width and height were not set, removing these from the generated HTML gives the proper dimensions.

Actual behavior

The same image when added to a small site looks great, but in my 7,000 page site the height is stretched.

Your environment

• Builds were tested in GitHub actions and on macOS 14 (arm). On macOS I have started running the builds in Docker so that I can reduce the number of cores as I run out of heap if all 12 cores are used by node)
• latest Chrome and latest Firefox
• NODE_OPTIONS="--max-old-space-size=8192"

Self-service

• [ ] I'd be willing to fix this bug myself.

[DanRoscigno]

Update: Images are still stretched with both locales and one version

[DanRoscigno]

Update 2: Images are still stretched with one locale and one version.

[DanRoscigno]

Note: Smaller images are not impacted, for example this page looks fine.

[Josh-Cena]

Thanks for the issue! The problem is we set explicit width and height, but we don't set the CSS appropriately so that the image scales with fixed aspect ratio. Adding something like

img {
  width: auto;
  height: auto;
}

should fix it.

[DanRoscigno]

Thanks Josh! testing now.

BTW, v3 is rocking!

[DanRoscigno]

img {
  width: auto;
  height: auto;
}

Did fix it:

Thanks so much! Should I close this issue? I could not figure out where the custom.css file comes from to submit a PR.

[Josh-Cena]

We should probably include it in our CSS, but no worries—you needn't feel pressured about sending a PR yourself. I'm also not sure if this is a good fix for every site.

[cdemi]

Thanks for the issue! The problem is we set explicit width and height, but we don't set the CSS appropriately so that the image scales with fixed aspect ratio. Adding something like

img {
  width: auto;
  height: auto;
}

should fix it.

Had this issue and adding this in custom.css fixes it

[SubJunk]

I had a look at submitting a PR for a fix but it's hard to see where that would happen without spending a ton of time on it. I can see a plugin called IdealImage that sets image widths so it might be there, I'm just not that familiar with the Docusaurus codebase.

Why would exact image widths ever need to be set in Docusaurus? Isn't it better to just remove the code that is setting the exact widths? It could at least be a config option

[Josh-Cena]

Why would exact image widths ever need to be set in Docusaurus? Isn't it better to just remove the code that is setting the exact widths? It could at least be a config option

HTML images should always have explicit widths. This width does not represent the actual rendered width (which is why it's safe to override via CSS, and does not make it useless); it represents the intrinsic size of the image and helps the browser calculate the space to reserve. Otherwise, before the image loads, the browser doesn't know how much space the image would take, so there would be a layout shift. We are picking a better default for you.

It seems all sites that got into this problem found auto-width/height a good solution, so maybe we can implement it as a default in our theme.

[SubJunk]

Yeah that would be a good solution. If I ranked the severity of the two problems - problem 1 being the page content changes positions as images initially load, problem 2 being large images are always skewed - the skewing is a more serious one, so that wouldn't be the default for me, especially since I think users are used to the image peakaboos during initial page loads.

But your solution will fix the skewing

[Josh-Cena]

The first one is a subtle UX problem that most sites would neither actively fix nor effectively fix (because standard Markdown syntax does not allow you to inject the width/height attributes), so we have to take it up. The second one is a conspicuous problem that developers can instantly recognize and can easily fix in userland, so we consider it lower-priority in general, though indeed more severe if left unrecognized/unfixed.