Rework admin panel customization

docusaurus/docs/cms/admin-panel-customization.md

@@ -7,24 +7,207 @@ tags:
 - admin panel customization
 ---
 
+import HotReloading from '/docs/snippets/hot-reloading-admin-panel.md'
+
 # Admin panel customization
 
-The front-end part of Strapi is called the admin panel. The admin panel presents a graphical user interface to help you structure and manage the content that will be accessible through the Content API. The admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application.
+The **front-end part of Strapi** <Annotation>For a clarification on the distinction between:<ul><li>the Strapi admin panel (front end of Strapi),</li><li>the Strapi server (back end of Strapi),</li><li>and the end-user-facing front end of a Strapi-powered application,</li></ul> refer to the [development introduction](/cms/customization).</Annotation> is called the admin panel. The admin panel presents a graphical user interface to help you structure and manage the content that will be accessible through the Content API. To get an overview of the admin panel, please refer to the [Getting Started > Admin panel](/cms/features/admin-panel) page.
+
+From a developer point of view, Strapi's admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application.
+
+Admin panel customization is done by tweaking the code of the `src/admin/app` fileor other files included in the `src/admin` folder (see [project structure](/cms/project-structure)). By doing so, you can:
+
+- Customize some parts of the admin panel to better reflect your brand identity (logos, favicon) or your language,
+- Replace some other parts of the admin panel, such as the Rich text editor and the bundler,
+- Extend the theme or the admin panel to add new features or customize the existing user interface.
+
+## General considerations
+
+:::prerequisites
+Before updating code to customize the admin panel:
+
+- Rename the default `app.example.tsx|js` file into `app.ts|js`.
+- Create a new `extensions` folder in `/src/admin/`.
+- If you want to see your changes applied live while developing, ensure the admin panel server is running (it's usually done with the `yarn develop` or `npm run develop` command if you have not changed the default [host, port, and path](/cms/configurations/admin-panel#admin-panel-server) of the admin panel).
+:::
+
+Most basic admin panel customizations will be done in the `/src/admin/app` file, which includes a `config` object.
+
+Any file used by the `config` object (e.g., a custom logo) should be placed in a `/src/admin/extensions/` folder and imported inside `/src/admin/app.js`.
+
+:::note Note: Admin panel extensions vs. plugins extensions
+By default, Strapi projects already contain another `extensions` folder in `/src` but it is for plugins extensions only (see [Plugins extension](/cms/plugins-development/plugins-extension)).
+:::
+
+<HotReloading />
+
+## Available customizations
+
+The `config` object of `/src/admin/app` accepts the following parameters:
+
+| Parameter                      | Type             | Description                                                                                                           |
+| ------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `auth`                         | Object           | Accepts a `logo` key to replace the default Strapi logo on login screen                                     |
+| `head`                         | Object           | Accepts a `favicon` key to replace the default Strapi favicon                                             |
+| `locales`                      | Array of Strings | Defines availables locales |
+| `translations`                 | Object           | Extends the translations                                                                   |
+| `menu`                         | Object           | Accepts the `logo` key to change the logo in the main navigation                                            |
+| `theme.light` and `theme.dark` | Object           | Overwrite theme properties for light and dark modes                                               |
+| `tutorials`                    | Boolean          | Toggles displaying the video tutorials
+| `notifications`                | Object           | Accepts the `releases` key (Boolean) to toggle displaying notifications about new releases |
+
+Click on any of the following cards to get more details about a specific topic:
+
+<CustomDocCardsWrapper>
+<CustomDocCard icon="image" title="Logos" description="Update the logos displayed in the admin panel to match your own brand." link="/cms/admin-panel-customization/logos" />
+<CustomDocCard icon="image" title="Favicon" description="Update the favicon to match your own brand." link="/cms/admin-panel-customization/favicon" />
+<CustomDocCard icon="globe" title="Locales & translations" description="Define locales and extend translations available in the admin panel." link="/cms/admin-panel-customization/locales-translations" />
+<CustomDocCard icon="swap" title="Rich text editor" description="Learn more about the possible strategies to replace the built-in Rich text editor." link="/cms/admin-panel-customization/wysiwyg-editor" />
+<CustomDocCard icon="package" title="Bundlers" description="Choose between the Vite and webpack bundlers and configure them." link="/cms/admin-panel-customization/bundlers" />
+<CustomDocCard icon="palette" title="Theme extension" description="Learn the basics of extending the built-in theme of the admin panel." link="/cms/admin-panel-customization/theme-extension" />
+<CustomDocCard icon="paint-bucket" title="Admin panel extension" description="Learn the basics of extending the admin panel." link="/cms/admin-panel-customization/extension" />
+</CustomDocCardsWrapper>
+
+## Basic example
+
+The following is an example of a basic customization of the admin panel:
+
+<Tabs groupId="js-ts">
+<TabItem value="js" label="JavaScript">
+
+```jsx title="/src/admin/app.js"
+import AuthLogo from "./extensions/my-logo.png";
+import MenuLogo from "./extensions/logo.png";
+import favicon from "./extensions/favicon.png";
+
+export default {
+  config: {
+    // Replace the Strapi logo in auth (login) views
+    auth: {
+      logo: AuthLogo,
+    },
+    // Replace the favicon
+    head: {
+      favicon: favicon,
+    },
+    // Add a new locale, other than 'en'
+    locales: ["fr", "de"],
+    // Replace the Strapi logo in the main navigation
+    menu: {
+      logo: MenuLogo,
+    },
+    // Override or extend the theme
+    theme: {
+      // overwrite light theme properties
+      light: {
+        colors: {
+          primary100: "#f6ecfc",
+          primary200: "#e0c1f4",
+          primary500: "#ac73e6",
+          primary600: "#9736e8",
+          primary700: "#8312d1",
+          danger700: "#b72b1a",
+        },
+      },
+
+      // overwrite dark theme properties
+      dark: {
+        // ...
+      },
+    },
+    // Extend the translations
+    translations: {
+      fr: {
+        "Auth.form.email.label": "test",
+        Users: "Utilisateurs",
+        City: "CITY (FRENCH)",
+        // Customize the label of the Content Manager table.
+        Id: "ID french",
+      },
+    },
+    // Disable video tutorials
+    tutorials: false,
+    // Disable notifications about new Strapi releases
+    notifications: { releases: false },
+  },
+
+  bootstrap() {},
+};
+```
+
+</TabItem>
+
+<TabItem value="ts" label="TypeScript">
+
+```jsx title="/src/admin/app.ts"
+// Note: you may see some ts errors, don't worry about them
+import AuthLogo from "./extensions/my-logo.png";
+import MenuLogo from "./extensions/logo.png";
+import favicon from "./extensions/favicon.png";
+
+export default {
+  config: {
+    // Replace the Strapi logo in auth (login) views
+    auth: {
+      logo: AuthLogo,
+    },
+    // Replace the favicon
+    head: {
+      // Try to change the origin favicon.png file in the
+      // root of strapi project if this config don't work.
+      favicon: favicon, 
+    },
+    // Add a new locale, other than 'en'
+    locales: ["fr", "de"],
+    // Replace the Strapi logo in the main navigation
+    menu: {
+      logo: MenuLogo,
+    },
+    // Override or extend the theme
+    theme: {
+	    dark:{
+	      colors: {
+			  alternative100: '#f6ecfc',
+			  alternative200: '#e0c1f4',
+			  alternative500: '#ac73e6',
+			  alternative600: '#9736e8',
+			  alternative700: '#8312d1',
+			  buttonNeutral0: '#ffffff',
+			  buttonPrimary500: '#7b79ff',
+			  // you can see other colors in the link below
+			  },
+		},
+		light:{
+			// you can see the light color here just like dark colors https://github.com/strapi/design-system/blob/main/packages/design-system/src/themes/lightTheme/light-colors.ts
+		},
+  },
+    },
+    // Extend the translations
+    // you can see the traslations keys here https://github.com/strapi/strapi/blob/develop/packages/core/admin/admin/src/translations
+    translations: {
+      fr: {
+        "Auth.form.email.label": "test",
+        Users: "Utilisateurs",
+        City: "CITY (FRENCH)",
+        // Customize the label of the Content Manager table.
+        Id: "ID french",
+      },
+    },
+    // Disable video tutorials
+    tutorials: false,
+    // Disable notifications about new Strapi releases
+    notifications: { releases: false },
+  },
 
-Admin panel customization is a broad topic in Strapi and covers the following aspects:
+  bootstrap() {},
+};
+```
 
-- Some parts of the admin panel can be customized to better reflect your brand identity or to modify some default Strapi behaviors.
-- Some other parts of the admin panel, such as the WYSIWYG editor and the bundler, can be replaced.
-- The admin panel can also be extended to add new features or customize the existing user interface.
+</TabItem>
+</Tabs>
 
-Depending on what you want to achieve, you might need to update different parts of Strapi, as summarized in the following table:
+:::strapi Detailed examples in the codebase
 
-| Customization use case | How to customize it | Related documentation |
-|---------------------------|-----------------------|-----------------------|
-| Update the admin panel's host, port, and path  | By updating the code of the <code>config/admin.ts&#124;js</code> file | [ Host, port, and path configuration](/cms/admin-panel-customization/host-port-path) |
-| <ul><li>Replace the logos and favicon</li><li>Disable video tutorials or notifications about new Strapi releases</li><li>Define locales and extend translations</li><li>Extend the theme</li></ul> | By updating the code of the <code>src/admin/app.ts&#124;js</code> file | [Customization options](/cms/admin-panel-customization/options) |
-| Choose and configure a bundler | By writing some code in dedicated configuration files found in the `src/admin` folder | [Bundlers](/cms/admin-panel-customization/bundlers) |
-| Replace or customize the WYSIWYG editor | _(Various strategies available, see related documentation)_ | [WYSIWYG editor](/cms/admin-panel-customization/wysiwyg-editor) |
-| Extend the admin panel | _(Various strategies available, see related documentation)_ | [Extension](/cms/admin-panel-customization/extension) |
-| Deploy the admin panel | _(Various strategies available, see related documentation)_ | [Deployment](/cms/admin-panel-customization/deployment) |
-| Customize the email templates | Directly from the admin panel through the settings for the Users & Permissions plugin | [User Guide for the Users&nbsp;&&nbsp;Permissions plugin](/cms/features/users-permissions#templating-emails) |
+* You can see the full translation keys, for instance to change the welcome message, [on GitHub](https://github.com/strapi/strapi/blob/develop/packages/core/admin/admin/src/translations).
+* Light and dark colors are also found [on GitHub](https://github.com/strapi/design-system/tree/main/packages/design-system/src/themes).
+:::

docusaurus/docs/cms/admin-panel-customization/bundlers.md

@@ -23,7 +23,7 @@ For simplification, the following documentation mentions the `strapi develop` co
 
 In Strapi 5, <ExternalLink to="https://vitejs.dev/" text="Vite"/> is the default bundler that Strapi uses to build the admin panel. Vite will therefore be used by default when you run the `strapi develop` command.
 
-To extend the usage of Vite, define a function that extends its configuration inside `/src/admin/vite.config.[js|ts]`:
+To extend the usage of Vite, define a function that extends its configuration inside `/src/admin/vite.config`:
 
 <Tabs groupId="js-ts">
 <TabItem value="js" label="JavaScript">
@@ -74,10 +74,10 @@ strapi develop --bundler=webpack
 ```
 
 :::prerequisites
-Make sure to rename the default `webpack.config.example.js` file into `webpack.config.[js|ts]` before customizing webpack.
+Make sure to rename the default `webpack.config.example.js` file into `webpack.config.` before customizing webpack.
 :::
 
-In order to extend the usage of webpack v5, define a function that extends its configuration inside `/src/admin/webpack.config.[js|ts]`:
+In order to extend the usage of webpack v5, define a function that extends its configuration inside `/src/admin/webpack.config.`:
 
 <Tabs groupId="js-ts">
 <TabItem value="js" label="JavaScript">

docusaurus/docs/cms/admin-panel-customization/extension.md

@@ -2,7 +2,6 @@
 title: Admin panel extension
 description: Learn more about extending Strapi's admin panel.
 displayed_sidebar: cmsSidebar
-sidebar_label: Extension
 toc_max_heading_level: 4
 tags:
 - admin panel 
@@ -14,7 +13,7 @@ import HotReloading from '/docs/snippets/hot-reloading-admin-panel.md'
 
 # Admin panel extension
 
-Strapi's admin panel is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. If the [customization options](/cms/admin-panel-customization/options) provided by Strapi are not enough for your use case, you will need to extend Strapi's admin panel.
+Strapi's [admin panel](/cms/admin-panel-customization) is a React-based single-page application that encapsulates all the features and installed plugins of a Strapi application. If the [customization options](/cms/admin-panel-customization/options) provided by Strapi are not enough for your use case, you will need to extend Strapi's admin panel.
 
 Extending Strapi's admin panel means leveraging its React foundation to adapt and enhance the interface and features according to the specific needs of your project, which might imply creating new components or adding new types of fields.
 
@@ -26,11 +25,11 @@ There are 2 use cases where you might want to extend the admin panel:
 
 - As a Strapi developer, you want to develop a unique solution for a Strapi user who only needs to extend a specific instance of a Strapi application.
 
-  👉 This can be done by directly updating the `/src/admin/app.[tsx|js]` file, which can import any file located in `/src/admin/extensions`.
+  👉 This can be done by directly updating the `/src/admin/app` file, which can import any file located in `/src/admin/extensions`.
 
 :::strapi Additional resources
-* If you're searching for ways of replacing the default WYSIWYG editor, please refer to the [corresponding page](/cms/admin-panel-customization/wysiwyg-editor).
-* The <ExternalLink to="https://design-system.strapi.io/?path=/docs/getting-started-welcome--docs" text="Strapi Design System documentation"/> will also provide additional information on developing for Strapi's admin panel.
+* If you're searching for ways of replacing the default Rich text editor, please refer to the [corresponding page](/cms/admin-panel-customization/wysiwyg-editor).
+* The <ExternalLink to="https://design-system.strapi.io/?path=/docs/getting-started-welcome--docs" text="Strapi Design System documentation"/> also provide extensive additional information on developing for Strapi's admin panel.
 :::
 
 <HotReloading />