From a7ee643d3ec3ef1fc6eb69d169ef86c8f75d787a Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 27 May 2025 16:17:14 +0200 Subject: [PATCH] Add introductions for logos and locales customization --- .../docs/cms/admin-panel-customization.md | 2 +- .../admin-panel-customization/deployment.md | 118 -------- .../cms/admin-panel-customization/favicon.md | 43 +++ .../host-port-path.md | 4 +- .../locales-translations.md | 153 ++++++++++ .../cms/admin-panel-customization/logos.md | 95 ++++++ .../cms/admin-panel-customization/options.md | 281 +----------------- .../theme-extension.md | 23 ++ .../docs/cms/configurations/admin-panel.md | 109 ++++++- docusaurus/docs/cms/deployment.md | 2 +- docusaurus/sidebars.js | 7 +- 11 files changed, 439 insertions(+), 398 deletions(-) delete mode 100644 docusaurus/docs/cms/admin-panel-customization/deployment.md create mode 100644 docusaurus/docs/cms/admin-panel-customization/favicon.md create mode 100644 docusaurus/docs/cms/admin-panel-customization/locales-translations.md create mode 100644 docusaurus/docs/cms/admin-panel-customization/logos.md create mode 100644 docusaurus/docs/cms/admin-panel-customization/theme-extension.md diff --git a/docusaurus/docs/cms/admin-panel-customization.md b/docusaurus/docs/cms/admin-panel-customization.md index a21e72e0f5..ea96562e32 100644 --- a/docusaurus/docs/cms/admin-panel-customization.md +++ b/docusaurus/docs/cms/admin-panel-customization.md @@ -26,5 +26,5 @@ Depending on what you want to achieve, you might need to update different parts | 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) | +| Deploy the admin panel | _(Various strategies available, see related documentation)_ | [Deployment](/cms/configurations/admin-panel#deployment) | | Customize the email templates | Directly from the admin panel through the settings for the Users & Permissions plugin | [User Guide for the Users & Permissions plugin](/cms/features/users-permissions#templating-emails) | diff --git a/docusaurus/docs/cms/admin-panel-customization/deployment.md b/docusaurus/docs/cms/admin-panel-customization/deployment.md deleted file mode 100644 index 9273e07d6d..0000000000 --- a/docusaurus/docs/cms/admin-panel-customization/deployment.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Admin panel deployment -description: Learn more about deploying Strapi's admin panel in various scenarios. -displayed_sidebar: cmsSidebar -sidebar_label: Deployment -toc_max_heading_level: 4 -tags: -- admin panel -- admin panel customization -- deployment ---- - -# Admin panel deployment - -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 to your application's own front-end through Strapi's 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 [back-end server](/cms/backend-customization) of Strapi serves the Content API which provides endpoints to your content. - -By default, the back-end server and the admin panel server are deployed on the same server. But the admin panel and the back-end server are independent and can be deployed on different servers, which brings us to different scenarios: - -- Deploy the entire project on the same server. -- Deploy the administration panel on a server (AWS S3, Azure, etc) different from the API server. - -Build configurations differ for each case. - -Before deployment, the admin panel needs to be built, by running the following command from the project's root directory: - - - - - -```sh -yarn build -``` - - - - - -```sh -npm run build -``` - - - - - -This will replace the folder's content located at `./build`. Visit to make sure customizations have been taken into account. - -## Same server - -Deploying the admin panel and the back end (API) of Strapi on the same server is the default behavior. The build configuration will be automatically set. The server will start on the defined port and the administration panel will be accessible through `http://yourdomain.com:1337/admin`. - -:::tip -You might want to [change the path to access the administration panel](/cms/admin-panel-customization/host-port-path). -::: - -## Different servers - -To deploy the admin panel and the back end (API) of Strapi on different servers, use the following configuration: - - - - -```js title="./config/server.js" -module.exports = ({ env }) => ({ - host: env("HOST", "0.0.0.0"), - port: env.int("PORT", 1337), - url: "http://yourbackend.com", -}); -``` - -```js title="./config/admin.js" -module.exports = ({ env }) => ({ - /** - * Note: The administration will be accessible from the root of the domain - * (ex: http://yourfrontend.com/) - */ - url: "/", - serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files -}); -``` - - - - - -```js title="./config/server.ts" -export default ({ env }) => ({ - host: env("HOST", "0.0.0.0"), - port: env.int("PORT", 1337), - url: "http://yourbackend.com", -}); -``` - -```js title="./config/admin.ts" -export default ({ env }) => ({ - /** - * Note: The administration will be accessible from the root of the domain - * (ex: http://yourfrontend.com/) - */ - url: "/", - serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files -}); -``` - - - - -After running `yarn build` with this configuration, the `build` folder will be created/overwritten. Use this folder to serve it from another server with the domain of your choice (e.g. `http://yourfrontend.com`). - -The administration URL will then be `http://yourfrontend.com` and every request from the panel will hit the backend at `http://yourbackend.com`. - -:::note -If you add a path to the `url` option, it won't prefix your application. To do so, use a proxy server like Nginx (see [optional software deployment guides](/cms/deployment#additional-resources)). -::: diff --git a/docusaurus/docs/cms/admin-panel-customization/favicon.md b/docusaurus/docs/cms/admin-panel-customization/favicon.md new file mode 100644 index 0000000000..6203bd81ad --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/favicon.md @@ -0,0 +1,43 @@ +--- +title: Favicon +description: Replace the favicon displayed in Strapi's admin panel. +displayed_sidebar: cmsSidebar +sidebar_label: Favicon +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Favicon + +To replace the favicon: + +1. Create a `/src/admin/extensions/` folder if the folder does not already exist. +2. Upload your favicon into `/src/admin/extensions/`. +3. Replace the existing **favicon.png|ico** file at the Strapi application root with a custom `favicon.png|ico` file. +4. Update `/src/admin/app.[tsx|js]` with the following: + + ```js title="./src/admin/app.js" + import favicon from "./extensions/favicon.png"; + + export default { + config: { + // replace favicon with a custom icon + head: { + favicon: favicon, + }, + }, + }; + ``` + +5. Rebuild, launch and revisit your Strapi app by running `yarn build && yarn develop` in the terminal. + +:::tip +This same process may be used to replace the login logo (i.e. `AuthLogo`) and menu logo (i.e. `MenuLogo`) (see [logos customization documentation](#logos)). +::: + +:::caution +Make sure that the cached favicon is cleared. It can be cached in your web browser and also with your domain management tool like Cloudflare's CDN. +::: + diff --git a/docusaurus/docs/cms/admin-panel-customization/host-port-path.md b/docusaurus/docs/cms/admin-panel-customization/host-port-path.md index d9c20aa383..1fb98cb887 100644 --- a/docusaurus/docs/cms/admin-panel-customization/host-port-path.md +++ b/docusaurus/docs/cms/admin-panel-customization/host-port-path.md @@ -16,7 +16,7 @@ By default, Strapi's [admin panel](/cms/admin-panel-customization) is exposed vi ## Update the admin panel's path only -Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/admin-panel-customization/deployment)), by default: +Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/configurations/admin-panel#deployment)), by default: - The back-end server and the admin panel server of Strapi both run on the same host and port, which is `http://localhost:1337/`. - The admin panel is accessible at the `/admin` path while the back-end server is accessible at the `/api` path. @@ -58,7 +58,7 @@ export default ({ env }) => ({ ## Update the admin panel's host and port -If the admin panel and the back-end server of Strapi are not hosted on the same server (see [deployment](/cms/admin-panel-customization/deployment)), you will need to update the host and port of the admin panel. +If the admin panel and the back-end server of Strapi are not hosted on the same server (see [deployment](/cms/configurations/admin-panel#deployment)), you will need to update the host and port of the admin panel. This is done in the admin panel configuration file, for example to host the admin panel on `my-host.com:3000` properties should be updated follows: diff --git a/docusaurus/docs/cms/admin-panel-customization/locales-translations.md b/docusaurus/docs/cms/admin-panel-customization/locales-translations.md new file mode 100644 index 0000000000..7e0fa19ded --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/locales-translations.md @@ -0,0 +1,153 @@ +--- +title: Locales & translations +description: Learn how to update locales and extend translations in the Strapi admin panel. +displayed_sidebar: cmsSidebar +sidebar_label: Locales & translations +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Locales & translations + +The admin panel always ships with English translations but can display additional languages. You can also override any text that appears in the interface. +This page shows how to define your own locales and extend Strapi or plugin translations from the project codebase. For a broader view of branding options, see [Admin panel customization](/cms/admin-panel-customization). + +## Locales + +To update the list of available locales in the admin panel, use the `config.locales` array: + + + + +```jsx title="./my-app/src/admin/app.js" +export default { + config: { + locales: ["ru", "zh"], + }, + bootstrap() {}, +}; +``` + + + + + +```jsx title="./my-app/src/admin/app.ts" +export default { + config: { + locales: ["ru", "zh"], + }, + bootstrap() {}, +}; +``` + + + + +:::note NOTES + +- The `en` locale cannot be removed from the build as it is both the fallback (i.e. if a translation is not found in a locale, the `en` will be used) and the default locale (i.e. used when a user opens the administration panel for the first time). +- The full list of available locales is accessible on . + +::: + +### Extending translations + +Translation key/value pairs are declared in `@strapi/admin/admin/src/translations/[language-name].json` files. These keys can be extended through the `config.translations` key: + + + + +```js title="./my-app/src/admin/app.js" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + Users: "Utilisateurs", + City: "CITY (FRENCH)", + // Customize the label of the Content Manager table. + Id: "ID french", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + + +```js title="./my-app/src/admin/app.ts" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + Users: "Utilisateurs", + City: "CITY (FRENCH)", + // Customize the label of the Content Manager table. + Id: "ID french", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + +A plugin's key/value pairs are declared independently in the plugin's files at `./admin/src/translations/[language-name].json`. These key/value pairs can similarly be extended in the `config.translations` key by prefixing the key with the plugin's name (i.e. `[plugin name].[key]: 'value'`) as in the following example: + + + + +```js title="./my-app/src/admin/app.js" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + // Translate a plugin's key/value pair by adding the plugin's name as a prefix + // In this case, we translate the "plugin.name" key of plugin "content-type-builder" + "content-type-builder.plugin.name": "Constructeur de Type-Contenu", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + + +```js title="./my-app/src/admin/app.ts" +export default { + config: { + locales: ["fr"], + translations: { + fr: { + "Auth.form.email.label": "test", + // Translate a plugin's key/value pair by adding the plugin's name as a prefix + // In this case, we translate the "plugin.name" key of plugin "content-type-builder" + "content-type-builder.plugin.name": "Constructeur de Type-Contenu", + }, + }, + }, + bootstrap() {}, +}; +``` + + + + +If more translations files should be added, place them in `./src/admin/extensions/translations` folder. + diff --git a/docusaurus/docs/cms/admin-panel-customization/logos.md b/docusaurus/docs/cms/admin-panel-customization/logos.md new file mode 100644 index 0000000000..c69f5cd044 --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/logos.md @@ -0,0 +1,95 @@ +--- +title: Logos +description: Customize the logos displayed in Strapi's admin panel. +displayed_sidebar: cmsSidebar +sidebar_label: Logos +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Logos + +Strapi's admin panel displays its branding on both the login screen and in the main navigation. Replacing these images allows you to match the interface to your identity. This page shows how to override the two logo files via the admin panel configuration. If you prefer uploading them directly in the UI, see [Customizing the logo](/cms/features/admin-panel#customizing-the-logo). + +The Strapi admin panel displays a logo in 2 different locations, represented by 2 different keys in the admin panel configuration: + +| Location in the UI | Configuration key to update | +| ---------------------- | --------------------------- | +| On the login page | `config.auth.logo` | +| In the main navigation | `config.menu.logo` | + +:::note +Both logos can also be customized directly via the admin panel (see [Customizing the logo](/cms/features/admin-panel)). +Logos uploaded via the admin panel supersede any logo set through the configuration files. +::: + +### Logos location in the admin panel + + + +The logo handled by `config.auth.logo` logo is only shown on the login screen: + +![Location of the auth logo](/img/assets/development/config-auth-logo.png) + +The logo handled by `config.menu.logo` logo is located in the main navigation at the top left corner of the admin panel: + +![Location of Menu logo](/img/assets/development/config-menu-logo.png) + +### Updating logos + +To update the logos, put image files in the `/src/admin/extensions` folder, import these files in `src/admin/app.[tsx|js]` and update the corresponding keys as in the following example: + + + + +```jsx title="/src/admin/app.js" +import AuthLogo from "./extensions/my-auth-logo.png"; +import MenuLogo from "./extensions/my-menu-logo.png"; + +export default { + config: { + // … other configuration properties + auth: { // Replace the Strapi logo in auth (login) views + logo: AuthLogo, + }, + menu: { // Replace the Strapi logo in the main navigation + logo: MenuLogo, + }, + // … other configuration properties + + bootstrap() {}, +}; +``` + + + + + +```jsx title="/src/admin/app.ts" +import AuthLogo from "./extensions/my-auth-logo.png"; +import MenuLogo from "./extensions/my-menu-logo.png"; + +export default { + config: { + // … other configuration properties + auth: { // Replace the Strapi logo in auth (login) views + logo: AuthLogo, + }, + menu: { // Replace the Strapi logo in the main navigation + logo: MenuLogo, + }, + // … other configuration properties + + bootstrap() {}, +}; +``` + + + + +:::note +There is no size limit for image files set through the configuration files. +::: + diff --git a/docusaurus/docs/cms/admin-panel-customization/options.md b/docusaurus/docs/cms/admin-panel-customization/options.md index 5bcbf6e53f..bbb1de316f 100644 --- a/docusaurus/docs/cms/admin-panel-customization/options.md +++ b/docusaurus/docs/cms/admin-panel-customization/options.md @@ -38,14 +38,14 @@ The `config` object of `/src/admin/app.[tsx|js]` accepts the following parameter | Parameter | Type | Description | | ------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------- | -| `auth` | Object | Accepts a `logo` key to replace the default Strapi [logo](#logos) on login screen | -| `head` | Object | Accepts a `favicon` key to replace the default Strapi [favicon](#favicon) | -| `locales` | Array of Strings | Defines availables locales (see [updating locales](#locales)) | -| `translations` | Object | [Extends the translations](#extending-translations) | -| `menu` | Object | Accepts the `logo` key to change the [logo](#logos) in the main navigation | -| `theme.light` and `theme.dark` | Object | [Overwrite theme properties](#theme-extension) for Light and Dark modes | -| `tutorials` | Boolean | Toggles [displaying the video tutorials](#tutorial-videos) | -| `notifications` | Object | Accepts the `releases` key (Boolean) to toggle [displaying notifications about new releases](#releases-notifications) | +| `auth` | Object | Accepts a `logo` key to replace the default Strapi [logo](/cms/admin-panel-customization/logos) on login screen | +| `head` | Object | Accepts a `favicon` key to replace the default Strapi [favicon](/cms/admin-panel-customization/favicon) | +| `locales` | Array of Strings | Defines availables locales (see [updating locales](/cms/admin-panel-customization/locales-translations)) | +| `translations` | Object | [Extends the translations](/cms/admin-panel-customization/locales-translations#extending-translations) | +| `menu` | Object | Accepts the `logo` key to change the [logo](/cms/admin-panel-customization/logos) in the main navigation | +| `theme.light` and `theme.dark` | Object | [Overwrite theme properties](/cms/admin-panel-customization/theme-extension) for Light and Dark modes | +| `tutorials` | Boolean | Toggles [displaying the video tutorials](/cms/configurations/admin-panel) | +| `notifications` | Object | Accepts the `releases` key (Boolean) to toggle [displaying notifications about new releases](/cms/configurations/admin-panel) |
Example of a custom configuration for the admin panel: @@ -189,268 +189,5 @@ Light and dark colors are also found [on GitHub](https://github.com/strapi/desig -
- -## Locales - -To update the list of available locales in the admin panel, use the `config.locales` array: - - - - -```jsx title="./my-app/src/admin/app.js" -export default { - config: { - locales: ["ru", "zh"], - }, - bootstrap() {}, -}; -``` - - - - - -```jsx title="./my-app/src/admin/app.ts" -export default { - config: { - locales: ["ru", "zh"], - }, - bootstrap() {}, -}; -``` - - - - -:::note NOTES - -- The `en` locale cannot be removed from the build as it is both the fallback (i.e. if a translation is not found in a locale, the `en` will be used) and the default locale (i.e. used when a user opens the administration panel for the first time). -- The full list of available locales is accessible on . - -::: - -### Extending translations - -Translation key/value pairs are declared in `@strapi/admin/admin/src/translations/[language-name].json` files. These keys can be extended through the `config.translations` key: - - - - -```js title="./my-app/src/admin/app.js" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - Users: "Utilisateurs", - City: "CITY (FRENCH)", - // Customize the label of the Content Manager table. - Id: "ID french", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - - -```js title="./my-app/src/admin/app.ts" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - Users: "Utilisateurs", - City: "CITY (FRENCH)", - // Customize the label of the Content Manager table. - Id: "ID french", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - -A plugin's key/value pairs are declared independently in the plugin's files at `./admin/src/translations/[language-name].json`. These key/value pairs can similarly be extended in the `config.translations` key by prefixing the key with the plugin's name (i.e. `[plugin name].[key]: 'value'`) as in the following example: - - - - -```js title="./my-app/src/admin/app.js" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - // Translate a plugin's key/value pair by adding the plugin's name as a prefix - // In this case, we translate the "plugin.name" key of plugin "content-type-builder" - "content-type-builder.plugin.name": "Constructeur de Type-Contenu", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - - -```js title="./my-app/src/admin/app.ts" -export default { - config: { - locales: ["fr"], - translations: { - fr: { - "Auth.form.email.label": "test", - // Translate a plugin's key/value pair by adding the plugin's name as a prefix - // In this case, we translate the "plugin.name" key of plugin "content-type-builder" - "content-type-builder.plugin.name": "Constructeur de Type-Contenu", - }, - }, - }, - bootstrap() {}, -}; -``` - - - - -If more translations files should be added, place them in `./src/admin/extensions/translations` folder. - -## Logos - -The Strapi admin panel displays a logo in 2 different locations, represented by 2 different keys in the admin panel configuration: - -| Location in the UI | Configuration key to update | -| ---------------------- | --------------------------- | -| On the login page | `config.auth.logo` | -| In the main navigation | `config.menu.logo` | - -:::note -Both logos can also be customized directly via the admin panel (see [Customizing the logo](/cms/features/admin-panel)). -Logos uploaded via the admin panel supersede any logo set through the configuration files. -::: - -### Logos location in the admin panel - - - -The logo handled by `config.auth.logo` logo is only shown on the login screen: - -![Location of the auth logo](/img/assets/development/config-auth-logo.png) - -The logo handled by `config.menu.logo` logo is located in the main navigation at the top left corner of the admin panel: - -![Location of Menu logo](/img/assets/development/config-menu-logo.png) - -### Updating logos - -To update the logos, put image files in the `/src/admin/extensions` folder, import these files in `src/admin/app.[tsx|js]` and update the corresponding keys as in the following example: - - - - -```jsx title="/src/admin/app.js" -import AuthLogo from "./extensions/my-auth-logo.png"; -import MenuLogo from "./extensions/my-menu-logo.png"; - -export default { - config: { - // … other configuration properties - auth: { // Replace the Strapi logo in auth (login) views - logo: AuthLogo, - }, - menu: { // Replace the Strapi logo in the main navigation - logo: MenuLogo, - }, - // … other configuration properties - - bootstrap() {}, -}; -``` - - - - - -```jsx title="/src/admin/app.ts" -import AuthLogo from "./extensions/my-auth-logo.png"; -import MenuLogo from "./extensions/my-menu-logo.png"; - -export default { - config: { - // … other configuration properties - auth: { // Replace the Strapi logo in auth (login) views - logo: AuthLogo, - }, - menu: { // Replace the Strapi logo in the main navigation - logo: MenuLogo, - }, - // … other configuration properties - - bootstrap() {}, -}; -``` - - - -:::note -There is no size limit for image files set through the configuration files. -::: - -## Favicon - -To replace the favicon: - -1. Create a `/src/admin/extensions/` folder if the folder does not already exist. -2. Upload your favicon into `/src/admin/extensions/`. -3. Replace the existing **favicon.png|ico** file at the Strapi application root with a custom `favicon.png|ico` file. -4. Update `/src/admin/app.[tsx|js]` with the following: - - ```js title="./src/admin/app.js" - import favicon from "./extensions/favicon.png"; - - export default { - config: { - // replace favicon with a custom icon - head: { - favicon: favicon, - }, - }, - }; - ``` - -5. Rebuild, launch and revisit your Strapi app by running `yarn build && yarn develop` in the terminal. - -:::tip -This same process may be used to replace the login logo (i.e. `AuthLogo`) and menu logo (i.e. `MenuLogo`) (see [logos customization documentation](#logos)). -::: - -:::caution -Make sure that the cached favicon is cleared. It can be cached in your web browser and also with your domain management tool like Cloudflare's CDN. -::: - -## Theme extension - -Strapi applications can be displayed either in Light or Dark mode (see [administrator profile setup in the User Guide](/cms/getting-started/setting-up-admin-panel#setting-up-your-administrator-profile)), and both can be extended through custom theme settings. - -To extend the theme, use either: - -- the `config.theme.light` key for the Light mode -- the `config.theme.dark` key for the Dark mode - -:::strapi Strapi Design System -The default defines various theme-related keys (shadows, colors…) that can be updated through the `config.theme.light` and `config.theme.dark` keys in `./admin/src/app.js`. The is fully customizable and has a dedicated documentation. -::: + diff --git a/docusaurus/docs/cms/admin-panel-customization/theme-extension.md b/docusaurus/docs/cms/admin-panel-customization/theme-extension.md new file mode 100644 index 0000000000..3fa4d06d37 --- /dev/null +++ b/docusaurus/docs/cms/admin-panel-customization/theme-extension.md @@ -0,0 +1,23 @@ +--- +title: Theme extension +description: Extend Strapi's admin panel theme. +displayed_sidebar: cmsSidebar +sidebar_label: Theme extension +toc_max_heading_level: 4 +tags: +- admin panel +- admin panel customization +--- + +# Theme extension + +Strapi applications can be displayed either in Light or Dark mode (see [administrator profile setup in the User Guide](/cms/getting-started/setting-up-admin-panel#setting-up-your-administrator-profile)), and both can be extended through custom theme settings. + +To extend the theme, use either: + +- the `config.theme.light` key for the Light mode +- the `config.theme.dark` key for the Dark mode + +:::strapi Strapi Design System +The default defines various theme-related keys (shadows, colors…) that can be updated through the `config.theme.light` and `config.theme.dark` keys in `./admin/src/app.js`. The is fully customizable and has a dedicated documentation. +::: diff --git a/docusaurus/docs/cms/configurations/admin-panel.md b/docusaurus/docs/cms/configurations/admin-panel.md index 912009b22d..a84205ca63 100644 --- a/docusaurus/docs/cms/configurations/admin-panel.md +++ b/docusaurus/docs/cms/configurations/admin-panel.md @@ -81,7 +81,7 @@ The authentication system, including [SSO configuration](/cms/configurations/gui By default, Strapi's admin panel is exposed via `http://localhost:1337/admin`. For security reasons, the host, port, and path can be updated. -Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/admin-panel-customization/deployment)), by default: +Unless you chose to deploy Strapi's back-end server and admin panel server on different servers (see [deployment](/cms/configurations/admin-panel#deployment)), by default: - The back-end server and the admin panel server both run on the same host and port (`http://localhost:1337/`) - The admin panel is accessible at the `/admin` path while the back-end server is accessible at the `/api` path @@ -137,6 +137,113 @@ export default ({ env }) => ({ +## Deployment + +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 to your application's own front-end through Strapi's 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 [back-end server](/cms/backend-customization) of Strapi serves the Content API which provides endpoints to your content. + +By default, the back-end server and the admin panel server are deployed on the same server. But the admin panel and the back-end server are independent and can be deployed on different servers, which brings us to different scenarios: + +- Deploy the entire project on the same server. +- Deploy the administration panel on a server (AWS S3, Azure, etc) different from the API server. + +Build configurations differ for each case. + +Before deployment, the admin panel needs to be built, by running the following command from the project's root directory: + + + + + +```sh +yarn build +``` + + + + + +```sh +npm run build +``` + + + + + +This will replace the folder's content located at `./build`. Visit to make sure customizations have been taken into account. + +### Same server + +Deploying the admin panel and the back end (API) of Strapi on the same server is the default behavior. The build configuration will be automatically set. The server will start on the defined port and the administration panel will be accessible through `http://yourdomain.com:1337/admin`. + +:::tip +You might want to [change the path to access the administration panel](#server-configuration). +::: + +### Different servers + +To deploy the admin panel and the back end (API) of Strapi on different servers, use the following configuration: + + + + +```js title="./config/server.js" +module.exports = ({ env }) => ({ + host: env("HOST", "0.0.0.0"), + port: env.int("PORT", 1337), + url: "http://yourbackend.com", +}); +``` + +```js title="./config/admin.js" +module.exports = ({ env }) => ({ + /** + * Note: The administration will be accessible from the root of the domain + * (ex: http://yourfrontend.com/) + */ + url: "/", + serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files +}); +``` + + + + + +```js title="./config/server.ts" +export default ({ env }) => ({ + host: env("HOST", "0.0.0.0"), + port: env.int("PORT", 1337), + url: "http://yourbackend.com", +}); +``` + +```js title="./config/admin.ts" +export default ({ env }) => ({ + /** + * Note: The administration will be accessible from the root of the domain + * (ex: http://yourfrontend.com/) + */ + url: "/", + serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files +}); +``` + + + + +After running `yarn build` with this configuration, the `build` folder will be created/overwritten. Use this folder to serve it from another server with the domain of your choice (e.g. `http://yourfrontend.com`). + +The administration URL will then be `http://yourfrontend.com` and every request from the panel will hit the backend at `http://yourbackend.com`. + +:::note +If you add a path to the `url` option, it won't prefix your application. To do so, use a proxy server like Nginx (see [optional software deployment guides](/cms/deployment#additional-resources)). +::: + ## Feature flags The feature flags can be configured with the following parameters: diff --git a/docusaurus/docs/cms/deployment.md b/docusaurus/docs/cms/deployment.md index bd2468d749..8bf28aa6ef 100644 --- a/docusaurus/docs/cms/deployment.md +++ b/docusaurus/docs/cms/deployment.md @@ -187,7 +187,7 @@ For more information, consult the [TypeScript documentation](/cms/typescript/dev ### Advanced configurations -If you want to host the administration on another server than the API, [please take a look at this dedicated section](/cms/admin-panel-customization/deployment). +If you want to host the administration on another server than the API, [please take a look at this dedicated section](/cms/configurations/admin-panel#deployment). ## Additional resources diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 0cfd8e7ffb..29eb5a27d9 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -307,9 +307,10 @@ const sidebars = { id: 'cms/admin-panel-customization', label: 'What\'s possible' // TODO check if we can keep the page as-is or if we need to create a new "Introdution" page }, - // 'cms/admin-panel-customization/logos', // TODO actual page to create - // 'cms/admin-panel-customization/favicon', // TODO actual page to create - // 'cms/admin-panel-customization/locales-translations', // TODO actual page to create + 'cms/admin-panel-customization/logos', + 'cms/admin-panel-customization/favicon', + 'cms/admin-panel-customization/locales-translations', + 'cms/admin-panel-customization/theme-extension', { type: 'doc', id: 'cms/admin-panel-customization/wysiwyg-editor',