[material-ui][docs] Categorize the "How-to guides" pages

.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

@@ -1,6 +1,6 @@
 # Theming
 
-<p class="description">Customize Material UI with your theme. You can change the colors, the typography and much more.</p>
+<p class="description">Customize Material&nbsp;UI with your theme. You can change the colors, the typography and much more.</p>
 
 The theme specifies the color of the components, darkness of the surfaces, level of shadow, appropriate opacity of ink elements, etc.
 
@@ -11,14 +11,14 @@ To promote greater consistency between apps, light and dark theme types are avai
 ## Theme provider
 
 If you wish to customize the theme, you need to use the `ThemeProvider` component in order to inject a theme into your application.
-However, this is optional; Material UI components come with a default theme.
+However, this is optional; Material&nbsp;UI components come with a default theme.
 
 `ThemeProvider` relies on the [context feature of React](https://react.dev/learn/passing-data-deeply-with-context) to pass the theme down to the components, so you need to make sure that `ThemeProvider` is a parent of the components you are trying to customize.
 You can learn more about this in [the API section](#themeprovider).
 
 ## Theme configuration variables
 
-Changing the theme configuration variables is the most effective way to match Material UI to your needs.
+Changing the theme configuration variables is the most effective way to match Material&nbsp;UI to your needs.
 The following sections cover the most important theme variables:
 
 - [`.palette`](/material-ui/customization/palette/)
@@ -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&nbsp;UI's theme with [MUI&nbsp;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
@@ -87,7 +87,7 @@ To add extra variables to the `theme.palette`, see [palette customization](/mate
 
 The community has built great tools to build a theme:
 
-- [mui-theme-creator](https://zenoo.github.io/mui-theme-creator/): A tool to help design and customize themes for the Material UI component library. Includes basic site templates to show various components and how they are affected by the theme
+- [mui-theme-creator](https://zenoo.github.io/mui-theme-creator/): A tool to help design and customize themes for the Material&nbsp;UI component library. Includes basic site templates to show various components and how they are affected by the theme
 - [Material palette generator](https://m2.material.io/inline-tools/color/): The Material palette generator can be used to generate a palette for any color you input.
 
 ## Accessing the theme in a component

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

@@ -10,7 +10,7 @@
 
 - **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**.
@@ -19,14 +19,14 @@
   - Review and comment on existing [pull requests](https://github.com/mui/material-ui/pulls) and [issues](https://github.com/mui/material-ui/issues).
   - [Improve our documentation](https://github.com/mui/material-ui/tree/HEAD/docs), fix bugs, or add features by [submitting a pull request](https://github.com/mui/material-ui/pulls).
 - **Support us financially on [Open Collective](https://opencollective.com/mui-org)**.
-  If you use Material UI in a commercial project and would like to support its continued development by becoming a Sponsor, or in a side or hobby project and would like to become a Backer, you can do so through Open Collective.
+  If you use Material UI in a commercial project and would like to support its continued development by becoming a Sponsor, or in a side or hobby project and would like to become a Backer, you can do so through Open Collective.
   All funds donated are managed transparently, and Sponsors receive recognition in the README and on the homepage.
 
 ## Why do the fixed positioned elements move when a modal is opened?
 
 Scrolling is blocked as soon as a modal is opened.
 This prevents interacting with the background when the modal should be the only interactive content. However, removing the scrollbar can make your **fixed positioned elements** move.
-In this situation, you can apply a global `.mui-fixed` class name to tell Material UI to handle those elements.
+In this situation, you can apply a global `.mui-fixed` class name to tell Material UI to handle those elements.
 
 ## How can I disable the ripple effect globally?
 
@@ -51,15 +51,15 @@
 
 ## How can I disable transitions globally?
 
-Material UI uses the same theme helper for creating all its transitions.
+Material UI uses the same theme helper for creating all its transitions.
 Therefore you can disable all transitions by overriding the helper in your theme:
 
 ```js
 import { createTheme } from '@mui/material';
 
 const theme = createTheme({
   transitions: {
-    // So we have `transition: none;` everywhere
+    // So `transition: none;` gets applied everywhere
     create: () => 'none',
   },
 });
@@ -104,10 +104,9 @@
 No, it's not required.
 But if you are using the default styled engine (`@mui/styled-engine`) the Emotion dependency comes built in, so carries no additional bundle size overhead.
 
-Perhaps, however, you're adding some Material UI components to an app that already uses another styling solution,
+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,13 +120,13 @@
 
 ## 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?
 
-All Material UI components that should render something in the DOM forward their
+All Material UI components that should render something in the DOM forward their
 ref to the underlying DOM component. This means that you can get DOM elements
-by reading the ref attached to Material UI components:
+by reading the ref attached to Material UI components:
 
 ```jsx
 // or a ref setter function
@@ -138,7 +137,7 @@
 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.
@@ -154,13 +153,13 @@
 ## Why are the colors I am seeing different from what I see here?
 
 The documentation site is using a custom theme. Hence, the color palette is
-different from the default theme that Material UI ships. Please refer to [this
+different from the default theme that Material UI ships. Please refer to [this
 page](/material-ui/customization/theming/) to learn about theme customization.
 
 ## Why does component X require a DOM node in a prop instead of a ref object?
 
 Components like the [Portal](/base-ui/react-portal/components-api/) or [Popper](/material-ui/api/popper/#props) require a DOM node in the `container` or `anchorEl` prop respectively.
-It seems convenient to simply pass a ref object in those props and let Material UI access the current value.
+It seems convenient to simply pass a ref object in those props and let Material UI access the current value.
 
 This works in a simple scenario:
 
@@ -204,7 +203,7 @@
 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 @@
 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
 
@@ -324,21 +323,21 @@
 ## [legacy] Why aren't my components rendering correctly in production builds?
 
 The #1 reason this happens is likely due to class name conflicts once your code is in a production bundle.
-For Material UI to work, the `className` values of all components on a page must be generated by a single instance of the [class name generator](/system/styles/advanced/#class-names).
+For Material UI to work, the `className` values of all components on a page must be generated by a single instance of the [class name generator](/system/styles/advanced/#class-names).
 
 To correct this issue, all components on the page need to be initialized such that there is only ever **one class name generator** among them.
 
 You could end up accidentally using two class name generators in a variety of scenarios:
 
-- You accidentally **bundle** two versions of `@mui/styles`. You might have a dependency not correctly setting Material UI as a peer dependency.
+- You accidentally **bundle** two versions of `@mui/styles`. You might have a dependency not correctly setting Material UI as a peer dependency.
 - You are using `StylesProvider` for a **subset** of your React tree.
 - You are using a bundler and it is splitting code in a way that causes multiple class name generator instances to be created.
 
 :::success
 If you are using Webpack with the [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/), try configuring the [`runtimeChunk` setting under `optimizations`](https://webpack.js.org/configuration/optimization/#optimization-runtimechunk).
 :::
 
-Overall, it's simple to recover from this problem by wrapping each Material UI application with [`StylesProvider`](/system/styles/api/#stylesprovider) components at the top of their component trees **and using a single class name generator shared among them**.
+Overall, it's simple to recover from this problem by wrapping each Material UI application with [`StylesProvider`](/system/styles/api/#stylesprovider) components at the top of their component trees **and using a single class name generator shared among them**.
 
 ### [legacy] CSS works only on first load and goes missing
 
@@ -401,11 +400,11 @@
      const html = ReactDOMServer.renderToString(
   ```
 
-- You need to verify that your client and server are running the **exactly the same version** of Material UI.
+- You need to verify that your client and server are running the **exactly the same version** of Material UI.
   It is possible that a mismatch of even minor versions can cause styling problems.
   To check version numbers, run `npm list @mui/styles` in the environment where you build your application and also in your deployment environment.
 
-  You can also ensure the same version in different environments by specifying a specific Material UI version in the dependencies of your package.json.
+  You can also ensure the same version in different environments by specifying a specific Material UI version in the dependencies of your package.json.
 
   _example of fix (package.json):_
 

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.