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 🤔