`float`ing images overlap background of boxes (code boxes, admonitions, etc.)

[yolpsoftware]

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.
• [ ] I have read the console error message carefully (if applicable).

Description

First of all, thanks for Docusaurus. I tried it out for documentation, but maybe I will use it for many other things as well.

I know that float: left is not widely regarded as the latest cutting-edge technology in CSS and web design.

However, for our use case we need to place images (or videos) side-by-side with documentation text, and it would be nice if that could happen in a floating way.

Please have a look at the reproducible demo. When you have started the preview, go to "Tutorial", "Tutorial - Basics" and then "Create a document". There, I have inserted an image, and applied the float: left CSS property.

As you can see, the background of the following code box overlaps the image's frame. The same is true for admonitions, and possibly other widgets.

Reproducible demo

Code Sandbox

Steps to reproduce

In the demo:

go to Tutorial --> Tutorial Basics --> Create a Document.

Generally:

1. Add an image to a Docusaurus markdown page (e.g. docs). It also works with other things than images.
2. Add the CSS float:left to that image.
3. Make sure the image does not occupy the whole width.
4. Add an admonition or a code box after the image, such that the image gets rendered side-by-side with the box.

==> The background of the box is overlapped by the image.

Expected behavior

The background of the box should not be overlapped by the image. It should be defined around the contents of the box.

Actual behavior

The background of the box is overlapped by the image.

Your environment

• Docusaurus version used: 3.5.2
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node 18.0, Chrome 128.
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS Sonoma 14.6.1

Self-service

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

[slorber]

Yes, you can break Docusaurus theme by adding your own CSS. If you do, you are responsible 😅

We don't do anything fancy here, it's just how HTML/CSS works with float: left.

Proof:

https://stackblitz.com/edit/vitejs-vite-3zx3xp?file=src%2FApp.jsx,src%2Fmain.jsx&terminal=dev

[yolpsoftware]

@slorber I see, and I understand your point.

Is there any way to render images side-by-side with normal Docusaurus content, by using the Docusaurus theme?

[slorber]

@yolpsoftware you can use CSS. But teaching you CSS is out of the scope of this project and I'm not an expert either.

Using overflow: hidden fixes it. Or you can use something else than float.

Here's a related issue with a related CSS-solution:

https://github.com/facebook/docusaurus/issues/4656

[yolpsoftware]

@slorber well, I was asking how to do what I want with the Docusaurus theme. Seems to me, there must be other people who like to use text wrapping around screenshots in their documentation.

But thanks, your suggestion seems to work. I just put this in my custom.css, and it works like a charm:

.theme-admonition, .theme-code-block {
  overflow: hidden;
}

Wouldn't that be a good addition to the Docusaurus theme? Is there a reason we want things to overflow boxes?

Thanks again!

[slorber]

Our theme doesn't provide that out of the box. If you want that kind of layout you can implement it yourself with MDX, JSX and CSS.

We don't provide a tutorial to help you implement all the layouts that could exist.

---

We don't add overflow by default because that's not how CSS works by default and doing so might produce side effects for users that use different layouts than yours. If you want to add CSS to create a custom layout, you are responsible for doing it correctly.

Remember it's not just those 2 elements, as my demo above shows, <p> also overflows, it's just that you don't see it because it doesn't have a background.

[yolpsoftware]

Right, got it.

Maybe it would make sense to add a section about "Common Layouting Pitfalls" to Styling and Layout. Seems to me, this would greatly enhance the flexibility of the Docusaurus theme.

Thanks again.

[slorber]

@yolpsoftware this is a pitfall for any dev using HTML and CSS, not just Docusaurus users.

Feel free to create a blog and document this for others.

We don't plan to document the thousands of existing pitfalls that exist for web devs doing HTML, JS and CSS.

Similarly we don't plan to teach flexbox or CSS grid on that page. If you want to use CSS with Docusaurus to customize it, there are better resources to learn CSS than our styling page.

[yolpsoftware]

Yeah, I was more thinking of "common pitfalls with common Docusaurus use-cases", but as I'm only the second one to have this issue, this might not even be such a common use-case.