[material-ui][docs] Categorize the "How-to guides" pages (#40403)

Co-authored-by: alexandre <[email protected]>
Co-authored-by: Olivier Tassinari <[email protected]>

.github/workflows/vale-action.yml

@@ -14,6 +14,7 @@ jobs:
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - uses: errata-ai/vale-action@c4213d4de3d5f718b8497bd86161531c78992084 # v2.0.1
+        continue-on-error: true
         with:
           reporter: github-pr-review
           files: docs/data

CHANGELOG.md

@@ -11939,7 +11939,7 @@ A big thanks to the 18 contributors who made this release possible. Here are som
   );
   ```
 
-  This enforces emotion being injected first. [More details](https://mui.com/material-ui/guides/interoperability/#css-injection-order) in the documentation.
+  This enforces emotion being injected first. [More details](https://mui.com/material-ui/integrations/interoperability/#css-injection-order) in the documentation.
 
 - [Autocomplete] Rename `closeIcon` prop with `clearIcon` to avoid confusion (#23617) @akhilmhdh.
 

docs/data/material/components/bottom-navigation/bottom-navigation.md

@@ -36,4 +36,4 @@ This demo keeps bottom navigation fixed to the bottom, no matter the amount of c
 
 One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server.
 The `BottomNavigationAction` component provides the `component` prop to handle this use case.
-Here is a [more detailed guide](/material-ui/guides/routing/).
+Here is a [more detailed guide](/material-ui/integrations/routing/).

docs/data/material/components/buttons/buttons.md

@@ -138,7 +138,7 @@ You can take advantage of this lower-level component to build custom interaction
 
 One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server.
 The `ButtonBase` component provides the `component` prop to handle this use case.
-Here is a [more detailed guide](/material-ui/guides/routing/#button).
+Here is a [more detailed guide](/material-ui/integrations/routing/#button).
 
 ## Limitations
 

docs/data/material/components/links/links.md

@@ -41,7 +41,7 @@ When you use `target="_blank"` with Links, it is [recommended](https://developer
 
 One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server.
 The `Link` component provides the `component` prop to handle this use case.
-Here is a [more detailed guide](/material-ui/guides/routing/#link).
+Here is a [more detailed guide](/material-ui/integrations/routing/#link).
 
 ## Accessibility
 

docs/data/material/components/lists/lists.md

@@ -26,7 +26,7 @@ The last item of the previous demo shows how you can render a link:
 </ListItemButton>
 ```
 
-You can find a [demo with React Router following this section](/material-ui/guides/routing/#list) of the documentation.
+You can find a [demo with React Router following this section](/material-ui/integrations/routing/#list) of the documentation.
 
 ## Nested List
 

docs/data/material/components/tabs/tabs.md

@@ -135,7 +135,7 @@ By default, tabs use a `button` element, but you can provide your custom tag or
 
 One frequent use case is to perform navigation on the client only, without an HTTP round-trip to the server.
 The `Tab` component provides the `component` prop to handle this use case.
-Here is a [more detailed guide](/material-ui/guides/routing/#tabs).
+Here is a [more detailed guide](/material-ui/integrations/routing/#tabs).
 
 ## Icon tabs
 

docs/data/material/customization/how-to-customize/how-to-customize.md

@@ -49,7 +49,7 @@ These class names can't be used as CSS selectors because they are unstable.
 If you want to override a component's styles using custom classes, you can use the `className` prop, available on each component.
 To override the styles of a specific part of the component, use the global classes provided by Material UI, as described in the previous section **"Overriding nested component styles"** under the [`sx` prop section](#the-sx-prop).
 
-Visit the [Style library interoperability](/material-ui/guides/interoperability/) guide to find examples of this approach using different styling libraries.
+Visit the [Style library interoperability](/material-ui/integrations/interoperability/) guide to find examples of this approach using different styling libraries.
 
 ### State classes
 

docs/data/material/customization/theming/theming.md

@@ -33,7 +33,7 @@ You can check out the [default theme section](/material-ui/customization/default
 
 ### Custom variables
 
-When using Material UI's theme with [MUI System](/system/getting-started/) or [any other styling solution](/material-ui/guides/interoperability/), it can be convenient to add additional variables to the theme so you can use them everywhere.
+When using Material UI's theme with [MUI System](/system/getting-started/) or [any other styling solution](/material-ui/integrations/interoperability/), it can be convenient to add additional variables to the theme so you can use them everywhere.
 For instance:
 
 ```jsx

docs/data/material/getting-started/faq/faq.md

@@ -10,7 +10,7 @@ There are many ways to support us:
 
 - **Spread the word**. Evangelize MUI's products by [linking to mui.com](https://mui.com/) on your website—every backlink matters.
   Follow us on [X](https://twitter.com/MUI_hq), like and retweet the important news. Or just talk about us with your friends.
-- **Give us feedback**. Tell us what we're doing well or where we can improve. Please upvote (👍) the issues that you are the most interested in seeing solved.
+- **Give us feedback**. Tell us what is going well or where there is improvement opportunities. Please upvote (👍) the issues that you are the most interested in seeing solved.
 - **Help new users**. You can answer questions on
   [Stack Overflow](https://stackoverflow.com/questions/tagged/material-ui).
 - **Make changes happen**.
@@ -59,7 +59,7 @@ import { createTheme } from '@mui/material';
 
 const theme = createTheme({
   transitions: {
-    // So we have `transition: none;` everywhere
+    // So `transition: none;` gets applied everywhere
     create: () => 'none',
   },
 });
@@ -106,8 +106,7 @@ But if you are using the default styled engine (`@mui/styled-engine`) the Emotio
 
 Perhaps, however, you're adding some Material UI components to an app that already uses another styling solution,
 or are already familiar with a different API, and don't want to learn a new one? In that case, head over to the
-[Style library interoperability](/material-ui/guides/interoperability/) section,
-where we show how simple it is to restyle Material UI components with alternative style libraries.
+[Style library interoperability](/material-ui/integrations/interoperability/) section to learn how to restyle Material UI components with alternative style libraries.
 
 ## When should I use inline-style vs. CSS?
 
@@ -121,7 +120,7 @@ The CSS alternative provides more advantages, such as:
 
 ## How do I use react-router?
 
-We detail the [integration with third-party routing libraries](/material-ui/guides/routing/) like react-router or Next.js in our guide.
+Visit the guide about [integration with third-party routing libraries](/material-ui/integrations/routing/), like react-router or Next.js, for more details.
 
 ## How can I access the DOM element?
 
@@ -138,7 +137,7 @@ const ref = React.createRef();
 const element = ref.current;
 ```
 
-If you're not sure if the Material UI component in question forwards its ref you can check the API documentation under "Props".
+If you're not sure if the Material UI component in question forwards its ref you can check the API documentation under "Props."
 You should find the message below, like in the [Button API](/material-ui/api/button/#props), [Button API](/material-ui/api/button/#props)
 
 > The ref is forwarded to the root element.
@@ -204,7 +203,7 @@ In the example above, the `Portal` would run an effect once, but might not re-re
 This is especially apparent for React.lazy components in Suspense.
 The above implementation could also not account for a change in the DOM node.
 
-This is why we require a prop with the actual DOM node so that React can take care of determining when the `Portal` should re-render:
+This is why a prop is required to the actual DOM node so that React can take care of determining when the `Portal` should re-render:
 
 ```jsx
 function App() {
@@ -276,8 +275,8 @@ This may cause theme propagation issues, broken class names, specificity issues,
 There are several common reasons for this to happen:
 
 - You have another `@mui/styles` library somewhere in your dependencies.
-- You have a monorepo structure for your project (e.g, lerna, yarn workspaces) and `@mui/styles` module is a dependency in more than one package (this one is more or less the same as the previous one).
-- You have several applications that are using `@mui/styles` running on the same page (e.g., several entry points in Webpack are loaded on the same page).
+- You have a monorepo structure for your project (for example, lerna or yarn workspaces) and `@mui/styles` module is a dependency in more than one package (this one is more or less the same as the previous one).
+- You have several applications that are using `@mui/styles` running on the same page (for example, several entry points in Webpack are loaded on the same page).
 
 ### Duplicated module in node_modules
 

docs/data/material/getting-started/installation/installation.md

@@ -56,7 +56,7 @@ pnpm add @mui/material @mui/styled-engine-sc styled-components
 
 </codeblock>
 
-Next, follow the [styled-components how-to guide](/material-ui/guides/styled-components/) to properly configure your bundler to support `@mui/styled-engine-sc`.
+Next, follow the [styled-components how-to guide](/material-ui/integrations/styled-components/) to properly configure your bundler to support `@mui/styled-engine-sc`.
 
 :::error
 As of late 2021, [styled-components](https://github.com/styled-components/styled-components) is **not compatible** with server-rendered Material UI projects.

docs/data/material/guides/composition/composition.md

@@ -147,7 +147,7 @@ Now the `CustomComponent` can be used with a `component` prop which should be se
 In addition, the `CustomComponent` will have all props of a `<a>` HTML element.
 The other props of the `Typography` component will also be present in props of the `CustomComponent`.
 
-You can find a code example with the Button and react-router-dom in [these demos](/material-ui/guides/routing/#component-prop).
+You can find a code example with the Button and react-router-dom in [these demos](/material-ui/integrations/routing/#component-prop).
 
 #### Generic
 

docs/data/material/guides/localization/localization.md

@@ -107,4 +107,4 @@ However, Material UI aims to support the [100 most common](https://en.wikipedia
 ## RTL Support
 
 Right-to-left languages such as Arabic, Persian, or Hebrew are supported.
-Follow [this guide](/material-ui/guides/right-to-left/) to use them.
+Follow [this guide](/material-ui/customization/right-to-left/) to use them.

docs/data/material/guides/interoperability/interoperability.md → docs/data/material/integrations/interoperability/interoperability.md

@@ -290,7 +290,7 @@ export default function GlobalCssSliderDeep() {
 ### Change the default styled engine
 
 By default, Material UI components come with Emotion as their style engine.
-If, however, you would like to use styled-components, you can configure your app by following the [styled-components guide](/material-ui/guides/styled-components/) or starting with one of the example projects:
+If, however, you would like to use styled-components, you can configure your app by following the [styled-components guide](/material-ui/integrations/styled-components/) or starting with one of the example projects:
 
 <!-- #default-branch-switch -->
 
@@ -593,17 +593,17 @@ export default function CssModulesSliderDeep2() {
 
 ### The `css` prop
 
-Emotion's **css()** method works seamlessly with Material UI.
+Emotion's `css()` method works seamlessly with Material UI.
 
 {{"demo": "EmotionCSS.js", "defaultCodeOpen": true}}
 
 ### Theme
 
-It works exactly like styled components. You can [use the same guide](/material-ui/guides/interoperability/#styled-components).
+It works exactly like styled components. You can [use the same guide](/material-ui/integrations/interoperability/#styled-components).
 
 ### The `styled()` API
 
-It works exactly like styled components. You can [use the same guide](/material-ui/guides/interoperability/#styled-components).
+It works exactly like styled components. You can [use the same guide](/material-ui/integrations/interoperability/#styled-components).
 
 ## Tailwind CSS
 

docs/data/material/migration/migration-v4/migrating-from-jss.md

@@ -191,7 +191,7 @@ This tool is _not_ maintained by MUI.
 ### 2. Use [tss-react](https://github.com/garronej/tss-react)
 
 :::error
-This API will not work if you are [using `styled-components` as the underlying styling engine in place of `@emotion`](/material-ui/guides/interoperability/#styled-components).
+This API will not work if you are [using `styled-components` as the underlying styling engine in place of `@emotion`](/material-ui/integrations/interoperability/#styled-components).
 :::
 
 The API is similar to JSS `makeStyles`, but under the hood, it uses `@emotion/react`.

docs/data/material/migration/migration-v4/v5-style-changes.md

@@ -661,7 +661,7 @@ The GitHub icon was reduced in size from 24px to 22px wide to match the size of
 
 ## @material-ui/pickers
 
-We have a [dedicated page](/material-ui/guides/pickers-migration/) for migrating `@material-ui/pickers` to v5.
+We have a [dedicated page](/material-ui/migration/pickers-migration/) for migrating `@material-ui/pickers` to v5.
 
 ## System
 

docs/data/material/pages.ts

@@ -15,6 +15,10 @@ const pages: MuiPage[] = [
       { pathname: '/material-ui/getting-started/learn' },
       { pathname: '/material-ui/getting-started/design-resources' },
       { pathname: '/material-ui/getting-started/faq', title: 'FAQs' },
+      {
+        pathname: '/material-ui/getting-started/understand-mui-packages',
+        title: 'Understanding MUI packages',
+      },
       { pathname: '/material-ui/getting-started/supported-components' },
       { pathname: '/material-ui/getting-started/supported-platforms' },
       { pathname: '/material-ui/getting-started/support' },
@@ -158,64 +162,81 @@ const pages: MuiPage[] = [
   {
     pathname: '/material-ui/customization',
     children: [
+      { pathname: '/material-ui/customization/how-to-customize' },
+      { pathname: '/material-ui/customization/dark-mode' },
+      { pathname: '/material-ui/customization/color' },
+      { pathname: '/material-ui/customization/right-to-left', title: 'Right-to-left' },
+      { pathname: '/material-ui/customization/shadow-dom', title: 'Shadow DOM' },
       {
         pathname: '/material-ui/customization/theme',
         subheader: '/material-ui/customization/theme',
         children: [
-          { pathname: '/material-ui/customization/theming' },
+          { pathname: '/material-ui/customization/default-theme', title: 'Default theme viewer' },
+          { pathname: '/material-ui/customization/theming', title: 'Customizing the theme' },
+          {
+            pathname: '/material-ui/customization/creating-themed-components',
+            title: 'Creating themed components',
+          },
+          { pathname: '/material-ui/customization/theme-components', title: 'Components' },
+        ],
+      },
+      {
+        pathname: '/material-ui/customization/tokens',
+        subheader: 'tokens',
+        children: [
           { pathname: '/material-ui/customization/palette' },
-          { pathname: '/material-ui/customization/dark-mode' },
           { pathname: '/material-ui/customization/typography' },
           { pathname: '/material-ui/customization/spacing' },
           { pathname: '/material-ui/customization/breakpoints' },
           { pathname: '/material-ui/customization/density' },
           { pathname: '/material-ui/customization/z-index', title: 'z-index' },
           { pathname: '/material-ui/customization/transitions' },
-          { pathname: '/material-ui/customization/theme-components', title: 'Components' },
-          { pathname: '/material-ui/customization/default-theme', title: 'Default theme viewer' },
         ],
       },
-      { pathname: '/material-ui/customization/how-to-customize' },
-      { pathname: '/material-ui/customization/color' },
     ],
   },
   {
     pathname: '/material-ui/guides',
     title: 'How-to guides',
     children: [
-      { pathname: '/material-ui/guides/api', title: 'API design approach' },
       {
-        pathname: '/material-ui/guides/creating-themed-components',
-        title: 'Creating themed components',
+        pathname: '/material-ui/guides/material-3-components',
+        title: 'Material 3 components',
+        newFeature: true,
       },
-      { pathname: '/material-ui/guides/typescript', title: 'TypeScript' },
-      { pathname: '/material-ui/guides/interoperability', title: 'Style library interoperability' },
-      { pathname: '/material-ui/guides/styled-components', title: 'Using styled-components' },
-      { pathname: '/material-ui/guides/theme-scoping' },
       { pathname: '/material-ui/guides/minimizing-bundle-size' },
-      { pathname: '/material-ui/guides/composition' },
-      { pathname: '/material-ui/guides/routing' },
       { pathname: '/material-ui/guides/server-rendering' },
       { pathname: '/material-ui/guides/responsive-ui', title: 'Responsive UI' },
-      {
-        pathname: '/material-ui/guides/pickers-migration',
-        title: 'Migration from @material-ui/pickers',
-      },
       { pathname: '/material-ui/guides/testing' },
       { pathname: '/material-ui/guides/localization' },
-      { pathname: '/material-ui/guides/content-security-policy', title: 'Content Security Policy' },
-      { pathname: '/material-ui/guides/right-to-left', title: 'Right-to-left support' },
-      { pathname: '/material-ui/guides/shadow-dom', title: 'Shadow DOM' },
+      { pathname: '/material-ui/guides/api', title: 'API design approach' },
+      { pathname: '/material-ui/guides/typescript', title: 'TypeScript' },
+      { pathname: '/material-ui/guides/composition' },
+      {
+        pathname: '/material-ui/guides/content-security-policy',
+        title: 'Content Security Policy',
+      },
+    ],
+  },
+  {
+    pathname: '/material-ui/integrations',
+    title: 'Integrations',
+    children: [
       {
-        pathname: '/material-ui/guides/nextjs',
+        pathname: '/material-ui/integrations/nextjs',
         title: 'Next.js integration',
         newFeature: true,
       },
+      { pathname: '/material-ui/integrations/routing', title: 'Routing libraries' },
       {
-        pathname: '/material-ui/guides/material-3-components',
-        title: 'Material 3 components',
-        newFeature: true,
+        pathname: '/material-ui/integrations/styled-components',
+        title: 'Usage with styled-components',
       },
+      {
+        pathname: '/material-ui/integrations/interoperability',
+        title: 'Style library interoperability',
+      },
+      { pathname: '/material-ui/integrations/theme-scoping' },
     ],
   },
   {
@@ -241,18 +262,6 @@ const pages: MuiPage[] = [
       },
     ],
   },
-  {
-    pathname: '/material-ui/discover-more',
-    children: [
-      { pathname: '/material-ui/discover-more/showcase' },
-      { pathname: '/material-ui/discover-more/related-projects' },
-      { pathname: '/material-ui/discover-more/design-kits' },
-      { pathname: '/material-ui/discover-more/roadmap' },
-      { pathname: '/material-ui/discover-more/backers', title: 'Sponsors and Backers' },
-      { pathname: '/material-ui/discover-more/vision' },
-      { pathname: '/material-ui/discover-more/changelog' },
-    ],
-  },
   {
     pathname: '/material-ui/migration',
     title: 'Migration',
@@ -261,6 +270,10 @@ const pages: MuiPage[] = [
         pathname: '/material-ui/migration/migration-grid-v2',
         title: 'Migrating to Grid v2',
       },
+      {
+        pathname: '/material-ui/migration/pickers-migration',
+        title: 'Migration from @material-ui/pickers',
+      },
       {
         pathname: '/material-ui/migration/v5',
         subheader: 'Upgrade to v5',
@@ -297,6 +310,18 @@ const pages: MuiPage[] = [
       },
     ],
   },
+  {
+    pathname: '/material-ui/discover-more',
+    children: [
+      { pathname: '/material-ui/discover-more/showcase' },
+      { pathname: '/material-ui/discover-more/related-projects' },
+      { pathname: '/material-ui/discover-more/design-kits' },
+      { pathname: '/material-ui/discover-more/roadmap' },
+      { pathname: '/material-ui/discover-more/backers', title: 'Sponsors and Backers' },
+      { pathname: '/material-ui/discover-more/vision' },
+      { pathname: '/material-ui/discover-more/changelog' },
+    ],
+  },
   {
     pathname: 'https://mui.com/store/?utm_source=docs&utm_medium=referral&utm_campaign=sidenav',
     title: 'Templates',