💅🚧 [WIP] Docusaurus Theming

[albinotonnina]

Motivation

I found the current style configuration lacking just a bit of love 💅❤️
At the moment it is super easy to bootstrap Docusaurus.
Less straightforward/clean is to do deeper customizations. Eg.: to change a 9px padding value hardcoded in main.css we need to override that value.
It would be nice to give users much more control over the styling of Docusaurus, keeping the 'zero configuration' paradigm intact.

Test Plan

Add/Fix tests TBD

Related PRs

#389

Plan

We start by implementing processing with postcss and precss

PreCSS combines Sass-like syntactical sugar — like variables, conditionals, and iterators — with emerging CSS features — like color functions, logical and custom properties, media query ranges, and image sets.

• Move styles route logic in separate file
• Add postcss + precss + autoprefixer as a basic configuration
• Move color variables (or font variables, or any variable for the css) in a stylesConfig.pcss file
• Split the current main.css file in modules
• Expose more css code to the users
• Many other postcss optimizations (rg. cssnano to compress output)
• Manage magic css values (margin or padding px values etc) in the stylesConfig file
• Give more control over the react component (Default component + extends? )
• Add more to options to configure the react components, eg. transitions, block visibility, block order

What do you think?

Extra: the Docusaurus default mascotte

What do you think about this illustration I put together?

Docusaurus

Docusaurus icon

They would replace:

[facebook-github-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need the corporate CLA signed.

If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[JoelMarcey]

@albinotonnina Hi. This is a big undertaking :) Adding multiple, out-of-the-box themes is a big feature that we wanted to add as part of a major upgrade to Docusaurus. I would be very happy and grateful if you wanted to help in this quest.

A couple of things:

1. What you have now - is it a breaking change? Particularly, removing color {...} from siteConfig.js? Would that break all our existing sites?
2. At the end of this, would your goal be to have a choice of a couple of ready-to-go themes for Docusaurus?
3. Re: your cute logo. I like it :) However, we cannot get rid of our original dinosaur -- we named Frank. That was the first logo we created in early development. That said, I imagine we can get your logo integrated somewhere given how cool it looks. Maybe they can co-exist together.

[albinotonnina]

Warning to inform the user about the deprecated config

[albinotonnina]

Hello @JoelMarcey
I'd be happy to help, sure!

About your questions:

1. Will it break with the current sites? At the moment yes, kind of. User with colors (or fonts) settings in their site config will get a warning, suggesting them to move those colors in this new .pcss configuration file which will be used by precss, a postcss plugin with SASS like features, such as variables, conditionals and iterators. This means that then the possibilities to configure Docusaurus are much much more.
   It won't break though, it will fallback to the default .pcss file, basically setting the default values (just colors at the moment)
2. My goal with this. I'm not sure my goal is to have just some ready themes to apply on Docusaurus. It could definitely be like this at the beginning but I see in the future the chance to go much deeper with customization. Like you already do for the Footer component in the UI lib; maybe the user could be able to override/extends the other components as well, such as the sidebar, or even better the layout of the main documentation pages, a bit like we can do already with the homepage. I think Docusaurus could be an engine to manipulate the data (and translations, and versioning and publishing etc etc) with on top a styling/markup/react layer, more isolated than now, overridable, customizable. Themes for example could be in different repositories, that would be easy for the user to install, switch to or create their own. I imagine some userland themes maybe?
3. I didn't know about Frank so now I'll back-down immediately :) Although I wouldn't use him like it is used now: when you launch Docusaurus for the first time you see him everywhere in the homepage, in all sizes. It hurts a bit my eyes, with all the due respect. I don't dislike the idea of Frank being designed so raw, a bit childish if you want, but I would show him just once, as the main logo and rewrite a bit the other sections, to be more 'template like', meaning more descriptive of what you can do with Docusaurus. I'm glad you like Larry (I just named the other I proposed 😅) and if you see some use for him I would be definitely glad.

I hope you like what I have in mind and I'll be waiting for your opinions on this.

PS. My first real world project with Docusaurus is a rewrite of the new blazing fast 🚀 web application bundler Parcel 📦.
This is what looks like right now with Docusaurus: http://parcel-website.now.sh/

Goal was to have it looks pretty much like the original one.
I think we will make a decision this with the creator of Parcel next week.
There is an issue with crowdin, docusaurus and icons I need to have a look at (the quotes on the sidebar of the documentation pages should not be there) but nothing that cannot be solved.

[neilsutcliffe]

The way to probably do it with the custom colours is to create a default sass variable file using them, which can be supplied to the compiler and rolled into the output CSS. Not sure how to preCSS/postCss that though.

I'm really not up to speed on PreCSS and PostCSS, but there have been very few times that Sass has been unable to do what I need.

To make themes using these technologies, does it require any previous knowledge, or will copy and pasted CSS work fine?

I'm not a big fan of Frank either, but ultimately a replacement would have to fit what exists already, I would have to say it doesn't really match the branding imagery, which is pastel colored rounded rectangles. Whilst this isn't exactly a fancy SaaS startup, I still feel that consistent imagery is important.

[albinotonnina]

I'm here people. I'm gonna continue this at some point 😃

[yangshun]

@albinotonnina I added cssnano in #569. It's a bit of a hack now so feel free to move it to somewhere more appropriate.

Also, it would be better to break up the PR into smaller ones so that progress can be tracked in smaller milestones (also easier to review).

[ahmadalfy]

@albinotonnina hello, I would love to lend a hand. I can split main.css into a module that follows a methodology like ITSCSS and or BEM ... etc

[JoelMarcey]

@yangshun @ahmadalfy Should this PR be closed in favor of smaller bite-sized ones? Or will we just use this PR as a starting point for some changes?

[yangshun]

I think it will be good to close this and have smaller ones. This PR is too large to review and merge as it stands now.

[albinotonnina]

Let’s make an action plan and do more manageable PRs, shall we? Do we all agree we will start implementing theming? Also, speaking of styling, this is the year of CSS-in-JS. I’m more and more fond of it, what do you think? Wirk with styled components, emotion, or glamorous?

[yangshun]

I don't think the current code base is ready for theming. There's quite a bit of cleaning up to do in terms of the assets pipeline and CSS structure. I'm afraid we'll have to hold off till then. Let's revisit this in future. Apologies!