Ensure proper and stable CSS insertion ordering

[lex111]

Edit: this issue is now about ensuring that we have a properly specified CSS insertion ordering with the ability to prevent regressions.

For Docusaurus 2.0 (#6113), CSS insertion ordering should become stable and documented. Upgrading Docusaurus should not lead to a different CSS ordering in particular for user-provided custom CSS.

See also #5987 (comment)

---

Original bug report below:

🐛 Bug Report

During a little refactoring, I realized that the custom CSS files content is not at the end of final CSS file styles.css (as it expected). This makes it impossible to override the Docusaurus component styles without applying the !important rule (which in turn is bad practice).

@slorber could you please investigate this issue? Can we "force" the custom CSS content to be at the end of all other styles?

By the example of Docusaurus website you can see that custom CSS is somewhere in the middle of bundled CSS file.

[slorber]

I don't find an easy way to do that.

We need client modules to be added in CSS first because Infima is a client module, and the theme css modules should be able to override Infima.

Looks like we need another system to be able to have 3 kind of css:

• client modules (infima, admonition etc...)
• theme imports (ie css modules etc...)
• custom css

I'm not sure how we can make this but it's unlikely we can do that using the clientModules API, otherwise Infima would end up overriding theme css modules

[lex111]

Maybe custom CSS files will include after main CSS file as separate link element? That is, we will exclude custom CSS content from main CSS bundle (styles.css). Can this be done?

[slorber]

this can probably be done but I don't know how yet

[lex111]

Hm.. what about "lazy" load custom CSS, something like as in Algolia's doc search?

[slorber]

this only works if that CSS will only be displayed on HTML that is not immediately visible, otherwise it will produce FOUC.
I'd rather make Webpack output another css file, that seems the proper solution.

[lex111]

I'd rather make Webpack output another css file, that seems the proper solution.

Agree, so we need to create new webpack entry specially for the custom CSS files?

[slorber]

I think yes, and find a good api to express that for users, maybe something like siteConfig.customCSS = string | string[]
Maybe we should even deprecate theme.customCSS as it could be confusing?
We should document the difference in term of CSS ordering between this new API and the clientModules

[lex111]

I'd rather leave the customCSS in the theme config, but just put them at the end of final CSS by default (i.e. after the CSS modules). If this can be achieved, it will be very very good.

[slorber]

I don't think it's a good idea, because the theme would need a new plugin lifecycle to be able to add this css at the bottom of the stylesheet.
I don't think as of now it would be great to introduce a new plugin lifecycle just for this usecase, we'd rather make this a core config feature instead?

[lex111]

All right then, I just wanted to avoid another deprecated filed (and use new filed instead), as this is a manual process by the users.

[slorber]

Yes. I guess we could keep the theme customCss field, but maybe deprecate it in the doc (or at least recommend to use site. customCss field) and add a Joi warning? (afaik it's possible to have Joi validation warnings instead of errors, but I don't think our code can handle warnings already)

[lex111]

Sounds good, but now we need to figure out how to do what we want 🤔

[sebdanielsson]

I don't know why but I added "chokidar": "^3.5.1" to the packages.json and now all entries in my custom.css is loaded.

[lex111]

Clarify the issue: currently, the styles (specified in CSS modules file) of Docusaurus built-in components cannot be overridden, except by applying !important rule, since they are included after the custom CSS file.

[platformlead]

Hello there I think I run into this issue.  I  (as a non developer/devops engineer ) am using the \src\css\custom.css with more than less success to customize few properties of the site. 

My current goal is to change the width of the document - TOC rows (inside the docMainContainer) from the default 75% -25% to 85%-15% using css properties.  I looked at #3955 , #3879 and more but was not able to generate the proper styling because the element has the 75% !important property which overrides anything I set for it. 
 

My workaround for the time is doing a build, then search for the "75% !important" string and replacing the !important part of string with "". That and custom css property at the end of the post solves the issue for me. 
 
Though this works, it is not an elegant solution. Am I missing something? There should be a better way, right? 
 

Thank you for reading this and your efforts for creating this tool. Cheers. 

.row .col.col--3 {
  --ifm-col-width: 15%;
}

[Josh-Cena]

Revisiting this issue. I'm not sure how we are to fix it, and the more I think about it the more I believe we can just put the CSS file in static and then use stylesheets to add them to the HTML head...

I would agree on a siteConfig.customCss field, and minimize and output each file separately as a <link> tag, as opposed to squashing them with the rest of the CSS, to make sure they always come out on top.

[slorber]

I would agree on a siteConfig.customCss field, and minimize and output each file separately as a tag, as opposed to squashing them with the rest of the CSS, to make sure they always come out on top.

That also makes sense to me.

• this API is not very intuitive IMHO. Users do not expect this but you can add a js file or a X.module.css file there even if it doesn't really make sense 🤷‍♂️

But we might still want to have some processing/minification being run on that CSS file

[slorber]

Added this isssue for the 2.0 milestone (see #6113), as it looks important that we commit to maintaining backward compatibility on CSS ordering

[slorber]

The problem is not so easy to solve.
See also: #6227

For v2.0 we'll keep the existing behavior, at least we now have tests to ensure CSS order does not change by mistake.