From abc8535970fdf77b2a5d3510b24233b4734e9e8a Mon Sep 17 00:00:00 2001 From: Andrei L <1881266+unrevised6419@users.noreply.github.com> Date: Tue, 26 May 2026 01:41:23 +0300 Subject: [PATCH 1/4] Update admin navigation & settings doc for unified addSettingsLink - Promote unified `addSettingsLink(sectionId | section, link | links)` as primary API. - Mark `createSettingSection()` and `addSettingsLinks()` as deprecated; add dedicated "Deprecated methods" section with migration examples. - Fix required-column drift against StrapiApp/Router source: `permissions` is required (pass `[]` for none); `Component` is optional (omitting registers no route). Correct `icon` type to `React.ElementType`. - Add missing optional params: `target`, `notificationsCount`, `exact` for menu links; `position`, `exact` for settings links. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../admin-navigation-settings.md | 93 +++++++++++++++---- 1 file changed, 76 insertions(+), 17 deletions(-) diff --git a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md index 38fa3dfcde..84f119c288 100644 --- a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md +++ b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md @@ -20,7 +20,7 @@ import Prerequisite from '/docs/snippets/plugins-development-create-plugin-prere -Use `addMenuLink` in `register` to add sidebar links, `createSettingSection` in `register` to create settings groups, and `addSettingsLink`/`addSettingsLinks` in `bootstrap` to extend existing settings sections. +Use `addMenuLink` in `register` to add sidebar links. Use `addSettingsLink` to both create new settings sections (pass a section object as the first argument) and extend existing ones (pass a section id string). The legacy `createSettingSection` and `addSettingsLinks` methods are deprecated. @@ -43,12 +43,15 @@ A menu link accepts the following parameters: | Parameter | Type | Required | Description | |---|---|---|---| | `to` | `string` | ✅ | Path the link should point to (relative to the admin panel root) (see [additional information](#path-conventions-for-to)) | -| `icon` | `React.Component` | ✅ | React component for the icon to display in the navigation | +| `icon` | `React.ElementType` | ✅ | React component for the icon to display in the navigation | | `intlLabel` | `object` | ✅ | Label for the link, following the convention, with: | -| `Component` | `function` | ✅ | Function that returns a dynamic `import()` of the plugin's main page component. The page module must export the component as `default`. | -| `permissions` | `Array` | ❌ | Array of permission objects that control access to the link | +| `permissions` | `Array` | ✅ | Array of permission objects that control link visibility. Pass `[]` for no restrictions. | +| `Component` | `function` | ❌ | Function that returns a dynamic `import()` of the plugin's main page component. The page module must export the component as `default`. If omitted, no route is registered (label-only entry). | | `position` | `number` | ❌ | Numeric position in the menu (lower numbers appear first) | | `licenseOnly` | `boolean` | ❌ | If `true`, displays a ⚡ icon to indicate the feature requires a paid license (default: `false`) | +| `target` | `string` | ❌ | Standard anchor `target` attribute (e.g. `_blank` for external links) | +| `notificationsCount` | `number` | ❌ | Badge count shown next to the menu label | +| `exact` | `boolean` | ❌ | Whether the active-link match should be exact | :::note The `intlLabel.id` values should correspond to keys in your translation files located at `admin/src/translations/[locale].json`. See [Admin localization](/cms/plugins-development/admin-localization) for details. @@ -136,7 +139,7 @@ The Settings API allows plugins to create new settings sections or add links to ### Creating a new settings section -Use `createSettingSection()` in the `register` lifecycle function: +To create a new settings section, call `addSettingsLink()` with a **section object** (`{ id, intlLabel }`) as the first argument and an array of link objects as the second argument. This can be done in either the `register` or `bootstrap` lifecycle function: @@ -145,7 +148,7 @@ Use `createSettingSection()` in the `register` lifecycle function: export default { register(app) { // highlight-start - app.createSettingSection( + app.addSettingsLink( { id: 'my-plugin', intlLabel: { @@ -193,7 +196,7 @@ import type { StrapiApp } from '@strapi/admin/strapi-admin'; export default { register(app: StrapiApp) { // highlight-start - app.createSettingSection( + app.addSettingsLink( { id: 'my-plugin', intlLabel: { @@ -235,7 +238,7 @@ export default { -The `createSettingSection()` function accepts the following parameters: +When used to create a new section, `addSettingsLink()` accepts the following parameters: * the first argument is the section configuration: @@ -251,13 +254,19 @@ The `createSettingSection()` function accepts the following parameters: | `id` | `string` | ✅ | Unique identifier for the settings link | | `to` | `string` | ✅ | Path relative to the settings route (do not include `settings/` prefix) (see [additional information](#path-conventions-for-to)) | | `intlLabel` | `object` | ✅ | Localized label object with `id` and `defaultMessage` | - | `Component` | `function` | ✅ | Function that returns a dynamic `import()` of the settings page component. The page module must export the component as `default`. | - | `permissions` | `Array` | ❌ | Array of permission objects that control access to the link | + | `permissions` | `Array` | ✅ | Array of permission objects that control link visibility. Pass `[]` for no restrictions. | + | `Component` | `function` | ❌ | Function that returns a dynamic `import()` of the settings page component. The page module must export the component as `default`. If omitted, no route is registered (label-only entry). | + | `position` | `number` | ❌ | Numeric position within the section (lower numbers appear first) | | `licenseOnly` | `boolean` | ❌ | If `true`, displays a ⚡ icon (default: `false`) | + | `exact` | `boolean` | ❌ | Whether the active-link match should be exact | + +:::caution Deprecated: `createSettingSection()` +The dedicated `app.createSettingSection(section, links)` method is deprecated. It still works (it delegates to `addSettingsLink` internally) but new code should call `addSettingsLink(section, links)` directly. See [Deprecated methods](#deprecated-methods). +::: ### Adding links to existing settings sections -To add a single link to an existing settings section, use `addSettingsLink()` in the `bootstrap()` lifecycle function. To add multiple links at once, use `addSettingsLinks()`. +To add links to an existing settings section, use `addSettingsLink()` in the `bootstrap()` lifecycle function with a **section id string** as the first argument. The second argument can be either a single link object or an array of link objects — both forms are supported by the same method. @@ -288,7 +297,7 @@ export default { // Add multiple links at once to the global settings section // highlight-start - app.addSettingsLinks('global', [ + app.addSettingsLink('global', [ { intlLabel: { id: 'my-plugin.settings.general', @@ -344,7 +353,7 @@ export default { // Add multiple links at once to the global settings section // highlight-start - app.addSettingsLinks('global', [ + app.addSettingsLink('global', [ { intlLabel: { id: 'my-plugin.settings.general', @@ -372,7 +381,11 @@ export default { -`addSettingsLink` and `addSettingsLinks` both take a `sectionId` string as the first argument (e.g., `'global'` or `'permissions'`). The second argument is a single link object for `addSettingsLink` or an array of link objects for `addSettingsLinks`, using the same properties as the `links` array in [`createSettingSection()` (see table above)](#creating-a-new-settings-section). +`addSettingsLink` takes a `sectionId` string as the first argument (e.g., `'global'` or `'permissions'`). The second argument is either a single link object or an array of link objects, using the same properties as the `links` array in [Creating a new settings section](#creating-a-new-settings-section). + +:::caution Deprecated: `addSettingsLinks()` +The plural `app.addSettingsLinks(sectionId, links)` method is deprecated. Call `addSettingsLink(sectionId, links)` (singular) with an array instead — it accepts both single links and arrays. See [Deprecated methods](#deprecated-methods). +::: ### Available settings sections @@ -382,7 +395,7 @@ Strapi provides built-in settings sections that plugins can extend: - `permissions`: Administration panel settings :::note -Creating a new settings section must be done in the `register` lifecycle function. Adding links to existing settings sections must be done in the `bootstrap` lifecycle function. +Creating a new settings section is typically done in the `register` lifecycle function, while adding links to existing settings sections is done in `bootstrap` (because the target section may be registered by another plugin). Both forms call the same `addSettingsLink()` method, which is exposed on the `app` argument of `register` and as `addSettingsLink` in the `bootstrap` argument bag. ::: ### Path conventions for `to` @@ -392,11 +405,57 @@ The `to` parameter behaves differently depending on the context: | Context | `to` value | Final URL | |---|---|---| | `addMenuLink` | `/plugins/my-plugin` | `http://localhost:1337/admin/plugins/my-plugin` | -| `createSettingSection` link | `my-plugin/general` | `http://localhost:1337/admin/settings/my-plugin/general` | -| `addSettingsLink` | `my-plugin/documentation` | `http://localhost:1337/admin/settings/my-plugin/documentation` | +| `addSettingsLink` (with section object) | `my-plugin/general` | `http://localhost:1337/admin/settings/my-plugin/general` | +| `addSettingsLink` (with section id) | `my-plugin/documentation` | `http://localhost:1337/admin/settings/my-plugin/documentation` | For menu links, the path is relative to the admin panel root (`/admin`). For settings links, the path is relative to the settings route (`/admin/settings`). Do not include the `settings/` prefix in settings link paths. :::strapi Securing plugin routes The `permissions` parameter on links only controls visibility in the navigation. To fully protect your plugin pages and register RBAC actions, see the [Admin permissions for plugins](/cms/plugins-development/guides/admin-permissions-for-plugins) guide. +::: + +## Deprecated methods + +The following methods on the `StrapiApp` instance are deprecated. They still work for backwards compatibility — both delegate to `addSettingsLink()` internally — but new code should use `addSettingsLink()` directly. + +### `createSettingSection(section, links)` + +Previously used to register a new settings section and its initial links in one call. + +```js +// ❌ Deprecated +app.createSettingSection( + { id: 'my-plugin', intlLabel: { id: 'my-plugin.settings.section-label', defaultMessage: 'My Plugin Settings' } }, + [{ id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') }], +); + +// ✅ Replacement: pass the section object as the first argument to addSettingsLink +app.addSettingsLink( + { id: 'my-plugin', intlLabel: { id: 'my-plugin.settings.section-label', defaultMessage: 'My Plugin Settings' } }, + [{ id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') }], +); +``` + +### `addSettingsLinks(sectionId, links)` + +Previously used to add multiple links to an existing section in one call. The singular `addSettingsLink()` now accepts either a single link object or an array. + +```js +// ❌ Deprecated +app.addSettingsLinks('global', [ + { id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') }, + { id: 'advanced', to: 'my-plugin/advanced', intlLabel: { id: 'my-plugin.settings.advanced', defaultMessage: 'Advanced' }, Component: () => import('./pages/Settings/Advanced') }, +]); + +// ✅ Replacement: pass the array to addSettingsLink (singular) +app.addSettingsLink('global', [ + { id: 'general', to: 'my-plugin/general', intlLabel: { id: 'my-plugin.settings.general', defaultMessage: 'General' }, Component: () => import('./pages/Settings/General') }, + { id: 'advanced', to: 'my-plugin/advanced', intlLabel: { id: 'my-plugin.settings.advanced', defaultMessage: 'Advanced' }, Component: () => import('./pages/Settings/Advanced') }, +]); +``` + +:::note +- `addSettingsLinks` is still exposed on the `bootstrap` argument bag (alongside `addSettingsLink`, `getPlugin`, and `registerHook`) for backwards compatibility. +- `createSettingSection` is only reachable via the full `app` instance passed to `register(app)` — it is not part of the `bootstrap` argument bag. +- Both delegate to `addSettingsLink()` internally and may be removed in a future major version. Migrate when convenient. ::: \ No newline at end of file From 36122d40ad34c6c231f4ea203aef9a83181adc5d Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 1 Jun 2026 15:48:00 +0200 Subject: [PATCH 2/4] Never use bold (except for button names) --- .../docs/cms/plugins-development/admin-navigation-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md index 84f119c288..256009e2c8 100644 --- a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md +++ b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md @@ -139,7 +139,7 @@ The Settings API allows plugins to create new settings sections or add links to ### Creating a new settings section -To create a new settings section, call `addSettingsLink()` with a **section object** (`{ id, intlLabel }`) as the first argument and an array of link objects as the second argument. This can be done in either the `register` or `bootstrap` lifecycle function: +To create a new settings section, call `addSettingsLink()` with a section object (`{ id, intlLabel }`) as the first argument and an array of link objects as the second argument. This can be done in either the `register` or `bootstrap` lifecycle function: From 4a42e1136bacbc8987a5f243d8b6c6157374a1b6 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 1 Jun 2026 15:48:28 +0200 Subject: [PATCH 3/4] Never use bold (except for button names) --- .../docs/cms/plugins-development/admin-navigation-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md index 256009e2c8..226f373dc9 100644 --- a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md +++ b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md @@ -266,7 +266,7 @@ The dedicated `app.createSettingSection(section, links)` method is deprecated. I ### Adding links to existing settings sections -To add links to an existing settings section, use `addSettingsLink()` in the `bootstrap()` lifecycle function with a **section id string** as the first argument. The second argument can be either a single link object or an array of link objects — both forms are supported by the same method. +To add links to an existing settings section, use `addSettingsLink()` in the `bootstrap()` lifecycle function with a section id string as the first argument. The second argument can be either a single link object or an array of link objects — both forms are supported by the same method. From e7d2591f52d7a1a66d9ce445c2169defe411bdf1 Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:03:20 +0200 Subject: [PATCH 4/4] Remove em dashes and add trailing newline in admin-navigation-settings --- .../plugins-development/admin-navigation-settings.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md index 226f373dc9..f58f2ba1cf 100644 --- a/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md +++ b/docusaurus/docs/cms/plugins-development/admin-navigation-settings.md @@ -266,7 +266,7 @@ The dedicated `app.createSettingSection(section, links)` method is deprecated. I ### Adding links to existing settings sections -To add links to an existing settings section, use `addSettingsLink()` in the `bootstrap()` lifecycle function with a section id string as the first argument. The second argument can be either a single link object or an array of link objects — both forms are supported by the same method. +To add links to an existing settings section, use `addSettingsLink()` in the `bootstrap()` lifecycle function with a section id string as the first argument. The second argument can be either a single link object or an array of link objects. Both forms are supported by the same method. @@ -384,7 +384,7 @@ export default { `addSettingsLink` takes a `sectionId` string as the first argument (e.g., `'global'` or `'permissions'`). The second argument is either a single link object or an array of link objects, using the same properties as the `links` array in [Creating a new settings section](#creating-a-new-settings-section). :::caution Deprecated: `addSettingsLinks()` -The plural `app.addSettingsLinks(sectionId, links)` method is deprecated. Call `addSettingsLink(sectionId, links)` (singular) with an array instead — it accepts both single links and arrays. See [Deprecated methods](#deprecated-methods). +The plural `app.addSettingsLinks(sectionId, links)` method is deprecated. Call `addSettingsLink(sectionId, links)` (singular) with an array instead; it accepts both single links and arrays. See [Deprecated methods](#deprecated-methods). ::: ### Available settings sections @@ -416,7 +416,7 @@ The `permissions` parameter on links only controls visibility in the navigation. ## Deprecated methods -The following methods on the `StrapiApp` instance are deprecated. They still work for backwards compatibility — both delegate to `addSettingsLink()` internally — but new code should use `addSettingsLink()` directly. +The following methods on the `StrapiApp` instance are deprecated. They still work for backwards compatibility (both delegate to `addSettingsLink()` internally), but new code should use `addSettingsLink()` directly. ### `createSettingSection(section, links)` @@ -456,6 +456,6 @@ app.addSettingsLink('global', [ :::note - `addSettingsLinks` is still exposed on the `bootstrap` argument bag (alongside `addSettingsLink`, `getPlugin`, and `registerHook`) for backwards compatibility. -- `createSettingSection` is only reachable via the full `app` instance passed to `register(app)` — it is not part of the `bootstrap` argument bag. +- `createSettingSection` is only reachable via the full `app` instance passed to `register(app)`; it is not part of the `bootstrap` argument bag. - Both delegate to `addSettingsLink()` internally and may be removed in a future major version. Migrate when convenient. -::: \ No newline at end of file +:::