css style isolation

[tobemaster56]

docusaurus is a very useful tool, I love it, we are creating our own component library, the demo of the component library, and eventually rendering in docusaurus, but I found a problem, some of the global styles of docusaurus's own themes affect the React components in the demo. Is there any good advice or elegant way to solve this problem?

[Josh-Cena]

We've heard this request multiple times recently. You can find a response here: #6032 and in this canny post .

Have you tried all: revert or other CSS tricks?

[tobemaster56]

According to your suggestion, I wrote a demo, this is easy for a single element. In my real case, I defined a demo root component, and the components that need to be rended will be wrapped in the demo. I added a class' demo revert 'to the root element of the demo. The corresponding style is that

.demo-revert * {
 all: revert;
}

,but the actual results are not ok. before i apply the class .demo-revert,

the left arrow is higher than the others. why? because the other li is affected by global styles

after i used .demo-revert,

so, in my case , The situation is complicated

[Josh-Cena]

Ah, I see. It's still related to our CSS insertion order. You may have to override specific CSS rules.

[tobemaster56]

yes, It's still related to our CSS insertion order, and adjusting the order is not easy

[tobemaster56]

Anyway, thank you for your reply

[tobemaster56]

Ah, I see. It's still related to our CSS insertion order. You may have to override specific CSS rules.

As discussed earlier, because I developed the pagination component, I quickly discovered the problem, and of course I could override this global style, and another colleague of mine wrote a demo about the calendar, but because the calendar component was not developed by him, it took him some time to figure out that it was the global style of docusaurus that affected it. If you find a problem, write a corresponding overprint style, which is only a temporary solution. We sincerely hope that there are areas in the docusaurus documentation that are free from global styles.

[gpbl]

I have the same problem with https://react-day-picker.js.org and other projects where we use Docusaurus.

The question is why is Docusaurus overriding the style of HTML elements? Or is it Infima? The CSS cascading issues have been solved since years, why aren't these practices being followed here? Is there anything we can do?

Here is what i've tried so far:

The "revert: all" workaround

The trick with revert: all doesn't works well, as there are many edge-cases like hovers, odd-even rules, and other selectors where the workaround is difficult to implement. Carefully "undoing" the style is not a solution, as you can't tell – without looking at the source – what's being overridden. Would a future update to docusaurus break the style again? etc.

The "iframe" workaround

I've tried to use an iframe to render the components in a new /render route – in the hope at least I could switch to a "bare-bone theme" for that route. However there's no way to tell Docusaurus to not load any global stylesheet for that route.

https://react-day-picker.js.org/render?example=start

As you can see it stills inherit style from tables:

Sandpack

I could finally rely on Sandpack as it is a good way to isolate the components, as it recreates a new app without the Docusaurus's chrome. Yet it is slow, the viewport is constrained, requires extra work.

I really hope for some inputs! Thanks.

[slorber]

Understand this problem and would also like to get it fixed so that you don't have to use an Iframe

Unfortunately, I don't have a good solution to solve it today with Docusaurus/classic theme/Infima

Reopened #6032

[Deykun]

I just want to say that it melts my brain to read threads here from 2021 and 2022 about this obvious issue with style isolation in a library whose sole purpose is generating documentation and showcasing components in isolation.

And expecting end users of such a library to simply write their own styles to cancel out the styles applied by the library is just ludicrous — clear proof that someone doesn’t understand the problem. Ignoring the fact that it’s a ridiculous amount of work to fix this obvious issue in a framework we are using. It will not work, because when we attempt it, we risk contaminating components with those cancellation styles ourselves — especially because Docusaurus uses some tag + tag { rules. Try to override that with cancelation and apply a style to the second tag - it will not work and you end up writing some ridicules styles inside the component you want to demo to cancel a rule from documentation tool.

What Docusaurus should do is wrap dynamically styled content with some .docs-markdown-styling class, limiting the styling scope to where it’s actually needed, rather than applying it globally. Leaving it global is an architectural mistake.

The fact that the community constantly complains about this and still hasn’t come up with a good solution should be a clear indication that this is a real issue for anyone considering Docusaurus. I don't even want to think about how many developer hours Docusaurus has wasted, because I’m sure a significant number of projects have had to deal with this issue and all of them spend time debugging it.

The problem itself wasn’t the biggest concern - the attitude toward it and the lack of a proper solution are. This issue is exactly why I’ll avoid this framework next time. Writing a SPA application from scratch will take less time than dealing with this.

#6032

[gpbl]

I understand your frustration, @Deykun. Due to this issue, I’ve evaluated Nextra, which had a similar yet more subtle problem. Creating a new app was a longer task. Creating a new Docusaurus theme from scratch didn’t end well (I believe the "then" idea failed).

Docusaurus is paying the price of choosing Infima as its CSS framework, which appears to be abandoned. I hope they will move away from it in version 4!

[slorber]

I'm not a fan of Infima but it's what we historically use. It would be difficult to abandon Infima without breaking many sites now.

The plan is rather to merge Infima back into Docusaurus classic theme, and make it an implementation detail of it, and stop not encouraging users to use Infima classes in their own code. Once it's there, it will be much easier to refactor things to remove global CSS pollution or introduce novel techniques to scope it (@scope (.start) to (.stop) for example), or create a brand new theme that has style isolation by default.

A related issue to track: #6032

Also somehow related to the community reqoest of a Tailwind theme: #2961