[material-ui][docs] Redo integration docs pages

[oliviertassinari]

Problems 💡

I think we must rework the whole section of https://mui.com/material-ui/getting-started/example-projects/. It's not great:

1. "Example projects" as a header doesn't make sense to me. These are more specific
2. We are missing integration examples
3. We don't have a detailed guide on how to integrate with each. If you have an existing project, you have to go to the examples to figure it out by yourself, this sucks.
4. https://mui.com/material-ui/getting-started/usage/#globals this is mostly about "Installation". You have to pick how you want to install the library, but overall, it feels backward.

Proposal

1. Create a new Integration page alongside https://mui.com/material-ui/getting-started/example-projects/ under the getting started area of the docs. Cover all the integrations with the framework that are relevant. We have another Integration section in https://mui.com/material-ui/integrations/routing/ but are a bit different, you don't need those to get started.

2. Have an example and a step-by-step guide on how to configure each integration. Mantine is one that embodies the best proposal, e.g. https://mantine.dev/guides/remix/. https://tailwindcss.com/docs/installation/framework-guides is nice but is missing examples. This is also great when you start and need to rely on two integrations, e.g. Next.js + Tailwind CSS.

3. Move https://mui.com/material-ui/integrations/nextjs/ to be hosted under 1. since it's required to get started. Same for https://mui.com/joy-ui/integrations/next-js-app-router/.

4. Add the missing framework integration

   • Astro
   • Laravel
   • Django
   • etc.

5. In https://mui.com/material-ui/getting-started/example-projects/, I think we should:

   i. link the showcase too. The whole point of this page is to give people examples they can get inspiration from.
   ii. update "Official examples" to remove this section or point to page 1, since people might land on this page without having seen the integration yets.
   iv. add cool project examples that we can find, assuming that 6.i. isn't enough. Like I could see how having a link to the showcase with open-source project would do the job well.

6. the React-admin and Refine examples should be moved under a general integration docs area https://mui.com/material-ui/integrations/routing/ since they are not needed to get started, it feels more common to add them to an existing project.

7. That general integration docs area should also reference the framework integration so they can be seen as a catalog of all the integrations available, useful as a marketing asset to convince developers.

Motivation 🔦

Improve the onboarding experience, which is critical in the journey of developers.

[alelthomas]

It's 3 pages that we need to re-structure:

• Example projects: Currently living in the Overview section, mixing Integrations, Templates, and Community Projects which include ScaffoldHub and Divjoy.
• Related projects: Currently living in the Discover More section of the docs, with tools that "expand" on top of Material UI: design resources, themes, components, and frameworks.
• Showcase: Currently living in the Discover More section, and being reworked

Following up on @oliviertassinari proposal, here's what I suggest we do:

Example projects

• Rename to Integrations. Remove Official themes and templates + Community project sections.
• Create the step-by-step for each of the integrations.

Related projects

• Rename to Community projects and add section under that name that currently lives in Example projects.
• I don't know how to best go about cleaning up this page, as it'll be a long list of URLs. Interested in your thoughts.

Showcase

• Move to Overview section, preferably somewhere between the Templates and Learn pages.
• Replace content as intended with vetted projects. Define vetting process (what should be our criteria to add projects here?)

[oliviertassinari]

@alelthomas Thought on this:

Example projects

"Integrations" might not be clear enough about what this is about. There could be different types of integrations. Since it's more about frameworks and installation, maybe "Framework setup" would be clearer?

Related projects

We created this section for things that we want people to be able to find with a search (Google, Algolia). It's about supplementary content that we can't quite add anywhere else. So for this reason, I think it should be located under "Discover more", far in the side nav, hard to find (so other stuff are easy to find).

On renaming the page "Community projects", we could have our own stuff in there too, e.g. Toolpad and will have other community project on other pages, where relevant, so the title feels more about "Supplementary projects".

For example, this move https://github.com/mui/material-ui/pull/44191/files#diff-be4ae77f71d791c8d765b321ebe72e65f4fe7893fea1fad0f46985e2fe25dfddR30 looks backward, I think we should move this to be under "Getting started", not under "Discover more".

Showcase.

It feels like this can be perfect linked in the header navigation, and not in the side nav (we did that back then as we didn't have time), it's not really about the docs. Tweaking Next.js, TypeScript, Bootstrap, Tailwind CSS, Radix it feels like this would be right:

---

So overall, it could look like this (notice the pages deleted or moved):

• https://mui.com/material-ui/getting-started/usage/#globals moves under https://mui.com/material-ui/getting-started/installation/ because it's about installation.
• https://mui.com/material-ui/getting-started/supported-components/ moves under discover more. It feels roadmap-related. Nothing needed to get started. "Supported platforms" could move to under this logic.
• https://mui.com/material-ui/integrations/nextjs/ moves under "Framework setup" it's the same thing
• https://mui.com/material-ui/integrations/styled-components/, https://mui.com/material-ui/integrations/interoperability/, https://mui.com/material-ui/integrations/theme-scoping/ moves under MUI System, this shouldn't be in the Material UI docs in the first place. https://www.chakra-ui.com/docs/styling/overview is equivalent to MUI System. It's in a tab, so different section area, and shared with all the components.

[samuelsycamore]

For example, this move https://github.com/mui/material-ui/pull/44191/files#diff-be4ae77f71d791c8d765b321ebe72e65f4fe7893fea1fad0f46985e2fe25dfddR30 looks backward, I think we should move this to be under "Getting started", not under "Discover more".

I don't think it makes much sense to list third-party projects in our Getting Started sequence—do we really want to redirect users outside of our product suite while reading the first few pages in the docs? This section of the docs should be super tight and focused solely on the new user's immediate needs. I think any resources we link at this stage in the user journey should come from our own docs. We just have no control over the experience or the quality of those projects (aside from vetting them before linking, of course), and I think they're tangential to the needs of most users.

[oliviertassinari]

This section of the docs should be super tight and focused solely on the new user's immediate needs.

@samuelsycamore Agree.

The way I see this, it's equivalent to https://react.dev/learn/start-a-new-react-project#production-grade-react-frameworks. A developer should have all he needs to be successful in using the project. I think success is about having the time from "I have a pain" -> "I have something that seems to be set up and work I can work with" that is lower than all the competing UI libraries or that is as low as physically possible.
I don't see a lot of differences between teaching people how to set up Material UI with Remix and with Refine, it feels close to being the same thing.