What's the best approach to customize styles in Docusaurus?

[sivaraam]

We are trying to setup a doc site using Docusaurus. One part of it was customizing the styling of the website to suit our needs. We're using the default classic theme and decided to go by writing custom CSS.

While doing so, we found it a little hard to identify which elements/classes we should/could customize so that we could expect it to not break when upgrading. For instance, is it fine to "Inspect" the site that loads when running yarn start and customize them? I guess not but I could find little about the elements/classes that could be customized in the docs. While writing this, I stumbled across the recently to "Global styles" section in "Styling and Layout" doc page which seems helpful to an extent. But I do wonder, is that all that's available for now? Or are is there information about elements/classes that could be reliably customized which I have missed?

I did read the beta goals in the latest announcement blog which states improvements to the theming system are on its way. That's nice. I just wanted to know if we're on the right track or if we should instead be relying alternative options like swizzling etc. Any help would be very much appreciated.

Thanks for the all the great work that goes into Docusaurus!

[slorber]

Hi,

Unfortunately, the goal of the beta is to improve the theming system, and this requires refactoring the theme to define a more explicit API surface for style-related components (also separating technical components from style-related components).

This means that your customizations will likely break a bit in the future. I'd recommend to wait for more heavy customizations, or it's at your own risks. You can also stick to a given stable version and do the customizations on it, and then try to backport those customizations later once we have refactored the theme properly.

To make the theming system more robust in the future, we have to break things now unfortunately. I can't tell exactly how much yet, but will try to maintain backward compatibility whenever possible

[sivaraam]

I could understand. Thanks for the information!