[docs] Add Styled Engine page

[mnajdova]

Preview https://deploy-preview-25911--material-ui.netlify.app/guides/styled-engine/

[mui-pr-bot]

No bundle size changes

Generated by 🚫 dangerJS against c059544

[oliviertassinari]

The topics I can think of when it comes to the documentation of the @material-ui/styled-engine package:

1. How to switch from emotion to styled-components
2. The GlobalStyles API.
3. The styled API
4. The ThemeProvider API
5. The StyledEngineProvider API
6. How to write a custom engine (can be kept short as I'm not sure anyone will really dive into it)
7. How to migrate from @material-ui/styles?
8. How to configure SSR?

It depends on how far we want to go. This is a bit tricky as we have created our own API around emotion and styled-component to bridge the differences.

---

Regarding the "Styling engine" title. We could consider "Styled engine" to make a reference to the API.

---

I think that it would make sense to have a dedicated section, like @material-ui/styled used to have in the side nav.

cc @mbrookes for more feedback

[mnajdova]

The topics I can think of when it comes to the documentation of the @material-ui/styled-engine package:

1. How to switch from emotion to styled-components
2. The GlobalStyles API.
3. The styled API
4. The ThemeProvider API
5. The StyledEngineProvider API
6. How to write a custom engine (can be kept short as I'm not sure anyone will really dive into it)
7. How to migrate from @material-ui/styles?
8. How to configure SSR?
   It depends on how far we want to go. This is a bit tricky as we have created our own API around emotion and styled-component to bridge the differences.

In my opinion How to switch from emotion to styled-components is the most important thing that affects probably 99% of the developers that will ever need to dive into the @material-ui/styled-engine* packages.

The second topic I think it's important is How to configure SSR?. I agree that we should have a page for this, for giving short description and pointing out to the corresponding examples we have. I would probably add this on a separate page, as including it on this one, may be hard to find..

Regarding the API and how to write a custom engine, I would add it as a follow up PR under Advanced section on this page. I don't think the API is that important unless you are not going to be creating your own engine, as I see this more of a internal package (I may be wrong in this assumption).

cc @oliviertassinari

[oliviertassinari]

@mnajdova I have tried to push it forward with new commits, please review. Looks good to me

Regarding the location of this page, is /customization/styled-engine/ the best? Another thought I had was /guides/styled-engine/ as it answers a specific how-to question (https://documentation.divio.com/). But it might not scale well if we add more content into it. It would fail once we had API reference content.

[mnajdova]

Regarding the location of this page, is /customization/styled-engine/ the best? Another thought I had was /guides/styled-engine/ as it answers a specific how-to question (https://documentation.divio.com/). But it might not scale well if we add more content into it. It would fail once we had API reference content.

I was’t sure what is the best position to be honest. I thought it should answer the question how to customize the styled engine 😅 maybe under guides would be better overall..

[mnajdova]

@mnajdova I have tried to push it forward with new commits, please review. Looks good to me

changes look good 👍

[mnajdova]

Regarding the location, maybe we can have a section Styled Engine with few pages, like how to setup styled-components, API, setup custom styled engine etc.. what do you think?

[oliviertassinari]

@mnajdova Yeah, it's another idea. I wonder if we have enough content to make it worthwhile. I don't know either what's the best structure.

[mnajdova]

I will move it to guides tomorrow then, seems like the best option at the moment...

Edit: Done :)

updated

[oliviertassinari]

Off-topic. @mbrookes Should we change the capitalization of the links to:

Suggested change

	"/guides/minimizing-bundle-size": "Minimizing Bundle Size",
	"/guides/minimizing-bundle-size": "Minimizing bundle size",

?