[Doc] Fix <ContainerLayout> is hard to find.

docs/Admin.md

@@ -387,39 +387,49 @@ For more details on predefined themes and custom themes, refer to [the Theming c
 
 If you want to deeply customize the app header, the menu, or the notifications, the best way is to provide a custom layout component. It must contain a `{children}` placeholder, where react-admin will render the resources. 
 
-Use the [default layout](https://github.com/marmelab/react-admin/blob/master/packages/ra-ui-materialui/src/layout/Layout.tsx) as a starting point, and check [the Theming documentation](./Theming.md#using-a-custom-layout) for examples.
+React-admin offers predefined layouts for you to use:
+
+- [`<Layout>`](./Layout.md): The default layout. It renders a top app bar and the navigation menu in a side bar.
+- [`<ContainerLayout>`](./ContainerLayout.md): A centered layout with horizontal navigation.
 
 ```jsx
-// in src/App.js
-import MyLayout from './MyLayout';
+import { Admin } from 'react-admin';
+import { ContainerLayout } from '@react-admin/ra-navigation';
 
-const App = () => (
-    <Admin layout={MyLayout} dataProvider={simpleRestProvider('http://path.to.my.api')}>
+export const App = () => (
+    <Admin dataProvider={dataProvider} layout={ContainerLayout}>
         // ...
     </Admin>
 );
 ```
 
-Your custom layout can simply extend [the default `<Layout>` component](./Layout.md) if you only want to override the appBar, the menu, or the error page. For instance:
+These layouts can be customized by passing props to them. For instance, you can pass a custom `appBar` prop to `<Layout>` to override the default app bar:
 
 ```jsx
 // in src/MyLayout.js
 import { Layout } from 'react-admin';
 import MyAppBar from './MyAppBar';
-import MyMenu from './MyMenu';
-import MyError from './MyError';
 
-const MyLayout = (props) => <Layout
-    {...props}
-    appBar={MyAppBar}
-    menu={MyMenu}
-    error={MyError}
-/>;
+export const MyLayout = (props) => <Layout {...props} appBar={MyAppBar} />;
+```
+
+Then, pass it to the `<Admin>` component as the `layout` prop:
 
-export default MyLayout;
+```jsx
+// in src/App.js
+import { Admin } from 'react-admin';
+import { MyLayout } from './MyLayout';
+
+const App = () => (
+    <Admin dataProvider={dataProvider} layout={MyLayout}>
+        // ...
+    </Admin>
+);
 ```
 
-For more details on custom layouts, check [the Theming documentation](./Theming.md#using-a-custom-layout).
+Refer to each component documentation to understand the props it accepts.
+
+Finally, you can also pass a custom component as the `layout` prop. It must contain a `{children}` placeholder, where react-admin will render the content. Use the [default `<Layout>`](https://github.com/marmelab/react-admin/blob/master/packages/ra-ui-materialui/src/layout/Layout.tsx) as a starting point, and check [the Theming documentation](./Theming.md#using-a-custom-layout) for examples.
 
 ## `loginPage`
 

docs/ContainerLayout.md

@@ -29,13 +29,46 @@ See more details in the [ra-navigation documentation](https://marmelab.com/ra-en
 
 ## Props
 
-`<ContainerLayout>` accepts the following props:
+`<ContainerLayout>` accepts the following props, all optional:
 
--   `menu`: The menu component to use. Defaults to `<HorizontalMenu>`.
 -   `appBar`: The component to use to render the top AppBar. Defaults to `<Header>`
--   `toolbar`: The buttons to render on the top right of the toolbar.
--   `maxWidth`: The maximum width of the content `<Container>`. Defaults to `md`.
 -   `fixed`: Whether the content `<Container>` should be fixed. Defaults to false.
+-   `maxWidth`: The maximum width of the content `<Container>`. Defaults to `md`.
+-   `menu`: The menu component to use. Defaults to `<HorizontalMenu>`.
+-   `sx`: The style of the layout, and the underlying component. 
+-   `toolbar`: The buttons to render on the top right of the toolbar.
+-   `userMenu`: The component to use to render the user menu. Defaults to `<UserMenu>`.
+
+## `appBar`
+
+If you want to use a different color for the AppBar, or to make it sticky, pass a custom `appBar` element based on `<Header>`, which is a simple wrapper around [MUI's `<AppBar>` component](https://mui.com/material-ui/react-app-bar/#main-content).
+
+```jsx
+import { ContainerLayout, Header } from '@react-admin/ra-navigation';
+
+const myAppBar = <Header color="primary" position="sticky" />;
+const MyLayout = props => <ContainerLayout {...props} appBar={myAppBar} />;
+```
+
+## `fixed`
+
+If you prefer to design for a fixed set of sizes instead of trying to accommodate a fully fluid viewport, you can set the `fixed` prop. The max-width matches the min-width of the current breakpoint.
+
+```jsx
+import { ContainerLayout } from '@react-admin/ra-navigation';
+
+const MyLayout = props => <ContainerLayout {...props} fixed />;
+```
+
+## `maxWidth`
+
+This prop allows to set the maximum width of the content [`<Container>`](https://mui.com/material-ui/react-container/#main-content). It accepts a string, one of `xs`, `sm`, `md`, `lg`, `xl`, or `false` to remove side margins and occupy the full width of the screen.
+
+```jsx
+import { ContainerLayout } from '@react-admin/ra-navigation';
+
+const MyLayout = props => <ContainerLayout {...props} maxWidth="md" />;
+```
 
 ## `menu`
 
@@ -86,16 +119,24 @@ export const App = () => (
 );
 ```
 
-## `appBar`
+## `sx`
 
-If you want to use a different color for the AppBar, or to make it sticky, pass a custom `appBar` element based on `<Header>`, which is a simple wrapper around [MUI's `<AppBar>` component](https://mui.com/material-ui/react-app-bar/#main-content).
+The `sx` prop allows to customize the style of the layout, and the underlying component. It accepts a [MUI `sx` prop](https://mui.com/system/the-sx-prop/#main-content).
 
+{% raw %}
 ```jsx
-import { ContainerLayout, Header } from '@react-admin/ra-navigation';
+import { ContainerLayout } from '@react-admin/ra-navigation';
 
-const myAppBar = <Header color="primary" position="sticky" />;
-const MyLayout = props => <ContainerLayout {...props} appBar={myAppBar} />;
+const MyLayout = props => (
+    <ContainerLayout
+        {...props}
+        sx={{
+            '& .MuiToolbar-root': { padding: 0 },
+        }}
+    />
+);
 ```
+{% endraw %}
 
 ## `toolbar`
 
@@ -114,22 +155,46 @@ const toolbar = (
 const MyLayout = props => <ContainerLayout {...props} toolbar={toolbar} />;
 ```
 
-## `maxWidth`
+## `userMenu`
 
-This prop allows to set the maximum width of the content [`<Container>`](https://mui.com/material-ui/react-container/#main-content). It accepts a string, one of `xs`, `sm`, `md`, `lg`, `xl`, or `false` to remove side margins and occupy the full width of the screen.
+By default, the `<ContainerLayout>` shows a user menu with a single item (logout) when the application has an `authProvider`. You can customize the user menu by passing a custom element to the `userMenu` prop.
 
+{% raw %}
 ```jsx
+import { Logout, UserMenu, useUserMenu } from 'react-admin';
+import { MenuList, MenuItem, ListItemIcon, ListItemText } from '@mui/material';
+import SettingsIcon from '@mui/icons-material/Settings';
 import { ContainerLayout } from '@react-admin/ra-navigation';
 
-const MyLayout = props => <ContainerLayout {...props} maxWidth="md" />;
-```
-
-## `fixed`
-
-If you prefer to design for a fixed set of sizes instead of trying to accommodate a fully fluid viewport, you can set the `fixed` prop. The max-width matches the min-width of the current breakpoint.
-
-```jsx
-import { ContainerLayout } from '@react-admin/ra-navigation';
+const ConfigurationMenu = React.forwardRef((props, ref) => {
+    const { onClose } = useUserMenu();
+    return (
+        <MenuItem
+            ref={ref}
+            {...props}
+            to="/configuration"
+            onClick={onClose}
+            sx={{ color: 'text.secondary' }}
+        >
+            <ListItemIcon>
+                <SettingsIcon />
+            </ListItemIcon>
+            <ListItemText>Configuration</ListItemText>
+        </MenuItem>
+    );
+});
+
+const CustomUserMenu = () => (
+    <UserMenu>
+        <MenuList>
+            <ConfigurationMenu />
+            <Logout />
+        </MenuList>
+    </UserMenu>
+);
 
-const MyLayout = props => <ContainerLayout {...props} fixed />;
+export const MyLayout = props => (
+    <ContainerLayout {...props} userMenu={<CustomUserMenu />} />
+);
 ```
+{% endraw %}

docs/Layout.md

@@ -320,3 +320,11 @@ export const MyLayout = (props) => (
 ```
 
 ![React-Query DevTools](./img/react-query-devtools.png)
+
+## Alternative Layouts
+
+If you can't configure `<Layout>` to render the layout you want, you can use an alternative layout component, such as [`<ContainerLayout>`](./ContainerLayout.md): A centered layout with horizontal navigation.
+
+![Container layout](https://marmelab.com/ra-enterprise/modules/assets/ra-navigation/latest/container-layout.png)
+
+You can also write your own layout component from scratch. Check [the Theming documentation](./Theming.md#using-a-custom-layout) for examples