Repository navigation
Image distortion (stretching vertically) #9462
Description
Have you read the Contributing Guidelines on issues?
- I have read the Contributing Guidelines on issues.
Prerequisites
- I'm using the latest version of Docusaurus.
- I have tried the
npm run clearoryarn clearcommand. - I have tried
rm -rf node_modules yarn.lock package-lock.jsonand re-installing packages. - I have tried creating a repro with https://new.docusaurus.io.
- 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 
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)
Reproducible demo
git@github.com: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.
- clone the above repo
- yarn install
- yarn build
- yarn serve
- 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.
Activity
DanRoscigno commentedon Oct 27, 2023
Update: Images are still stretched with both locales and one version
DanRoscigno commentedon Oct 27, 2023
Update 2: Images are still stretched with one locale and one version.
DanRoscigno commentedon Oct 27, 2023
Note: Smaller images are not impacted, for example this page looks fine.
Josh-Cena commentedon Oct 27, 2023
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
should fix it.
DanRoscigno commentedon Oct 27, 2023
Thanks Josh! testing now.
BTW, v3 is rocking!
DanRoscigno commentedon Oct 27, 2023
Did fix it:
Thanks so much! Should I close this issue? I could not figure out where the
custom.cssfile comes from to submit a PR.Josh-Cena commentedon Oct 27, 2023
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 commentedon Jul 10, 2024
Had this issue and adding this in
custom.cssfixes itSubJunk commentedon Aug 11, 2024
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
Fix image distortion when width exceeds content pane width
Josh-Cena commentedon Aug 11, 2024
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 commentedon Aug 11, 2024
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 commentedon Aug 11, 2024
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/heightattributes), 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.