diff --git a/16/umbraco-cms/.gitbook.yaml b/16/umbraco-cms/.gitbook.yaml
index fbae79d113e..0683e8964e1 100644
--- a/16/umbraco-cms/.gitbook.yaml
+++ b/16/umbraco-cms/.gitbook.yaml
@@ -145,3 +145,4 @@ redirects:
extending/customize-backoffice: customizing/README.md
extending/content-apps: customizing/extending-overview/extension-types/workspaces/workspace-views.md
extending/backoffice-setup/extension-types: customizing/extending-overview/extension-types/README.md
+ customizing/extending-overview/extension-registry/extension-registry: customizing/extending-overview/extension-registry/register-extensions.md
diff --git a/16/umbraco-cms/customizing/extending-overview/extension-registry/README.md b/16/umbraco-cms/customizing/extending-overview/extension-registry/README.md
index 3baa7e8fc05..7b301272765 100644
--- a/16/umbraco-cms/customizing/extending-overview/extension-registry/README.md
+++ b/16/umbraco-cms/customizing/extending-overview/extension-registry/README.md
@@ -1,21 +1,22 @@
---
description: >-
- Almost any UI in the Backoffice is an extension. All managed by the Extension
- Registry on the Client at Runtime. Giving you enormous flexibility.
+ Almost any UI in the Backoffice is an extension managed by the Extension Registry.
---
# Extension Registry
+The Umbraco backoffice is built with extensibility in mind. The backoffice without extensions is more or less a blank canvas that is build out using extensions. These extensions dictate how the backoffice functions and looks. All visual elements in an Umbraco installation, like the sections, menus, trees and buttons, are extensions. But extensions also dictate behaviour and the editing experience. So everything in the backoffice is governed (and extendable) by extensions.
-The Extensions Registry is your entry to extend or customize the Backoffice. Therefore, it is crucial to understand the abilities of the Extension Registry.
+{% hint style="info" %}
+You can see which extensions are registered in the backoffice by going to Settings > Extensions Insights.
+{% endhint %}
-## [Extension Registration](extension-registry.md)
+All extensions are registered in the extension registry. The registry can be manipulated at any time, meaning you can add or remove extensions at runtime. You as a developer have the same possibilities as an Umbraco HQ developer, which means what HQ can do, you can do. This also means that you can change almost everything that is by default present in Umbraco.
-The extension registry is a global registry that can be accessed and changed at any time while Backoffice is running.
+## [Introduction to a Extension Manifest](extension-manifest.md)
+An Extension Manifest is a declaration of what you want to register in the Umbraco backoffice. This articles handles the layout and requirements of an Extension Manifest.
-## [Extension Manifest](extension-manifest.md)
-
-Each Extension Manifest has to declare its type. This is used to determine where it hooks into the system. It also looks at what data is required to declare within it.
-
-## [Replace, Exclude, or Unregister](replace-exclude-or-unregister.md)
+## [Register an extension](extension-registry.md)
+This article handles how to register an extension using an umbraco-package.json file.
+## [Change an existing extension](replace-exclude-or-unregister.md)
Once you understand how to declare your own, you may want to replace or remove existing ones.
diff --git a/16/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md b/16/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md
index e733d0b77cb..9db6641c5e6 100644
--- a/16/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md
+++ b/16/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md
@@ -3,77 +3,42 @@ description: Learn about the different methods for declaring an Extension Manife
---
# Extension Manifest
+This page explains what an Extension Manifest for a Umbraco backoffice extension is. It outlines the manifest structure, required fields, and optional features used across types.
-The Extension Manifest is the first step for any extension. It is the declaration of what you want to register.
-
-In this section, you will find all the Extension Types provided by the Backoffice. [See all Extension Types here.](../extension-types/)
+## What is an Extension Manifest?
+Umbraco reads the extension manifest to register the extension in the Extension Registry.
+Each extension is of a certain type and this determines the required fields of the manifest and its available capabilities.
+An Extension Manifest declares a single backoffice extension along with its configuration.
## Extension Manifest Format
+Some extensions need extra assets, such as a JavaScript file with a Web Component.
-An Extension Manifest can be written as a JavaScript or JSON Object.
-
-The abilities of the extensions rely on the specific extension type. The Type sets the scene for what the extension can do and what it needs to be utilized. Some extension types can be made purely via the manifest. Other types require files, like a JavaScript file containing a Web Component.
+The abilities of the extensions rely on the specific extension type. The type sets the scene for what the extension can do and what it needs to be utilized. Some extension types can be made purely via the manifest, like a section or menu item. Other types require files, like a JavaScript file containing a Web Component, like a custom property editor.
+An Extension Manifest has a strict format where some properties are required and some depend on the Extension Type. An Extension Manifest can be written as a JavaScript or JSON object. You can learn more about this when [registering an extension](register-extensions.md).
+### Required Manifest properties
+A minimal Extension Manifest looks like this:
-```typescript
+```json
{
- type: '...',
- alias: 'my.customization',
- name: 'My customization'
- ...
-};
+ "type": "...",
+ "alias": "my.customization",
+ "name": "My customization"
+}
```
-The required fields of any Extension Manifest are:
-
-* `type` — The type defines the purpose of the extension. It is used to determine where the extension will be used.
-* `alias` — This is a unique identifier for this manifest. Prefix it with something that makes your extension unique. Example: `mfc.Dashboard.Overview` .
-* `name` — This is a representational name of this manifest; It does not need to be unique, but this can be beneficial when debugging extensions. Example: `My Fictive Company Overview Dashboard` .
+These fields are all required and have the following meaning:
-### Additional Manifest features
+* `type` — The type defines the purpose of the extension. Umbraco has many [extension types](../extension-types) available.
+* `alias` — Unique identifier for this manifest. Prefix it with something that makes your extension unique. For example: _FictiveCompany.MyProject.Dashboard.Overview_.
+* `name` — Representational name of this manifest. This name does not need to be unique, but this can be beneficial when debugging extensions. This name also shows up in the Extensions Insights in the backoffice of Umbraco. For example: _My Fictive Company Overview Dashboard_.
+### Additional Manifest properties
Most extension types support the use of the following generic features for their Manifest:
-* `weight` - Define a weight to determine the importance or visual order of this extension. A higher weight gives a more prominent position.
-* `overwrites` - Define one or more Extension Aliases that this extension should replace. Notice it only omits the listed Extensions when this is rendered in the same spot. [Read more in Replace, Exclude or Unregister](replace-exclude-or-unregister.md).
-* `conditions` - Define one or more conditions that must be permitted for the extension to become available. [Extension Conditions](../extension-conditions.md).
-* `kind` - Define a kind-alias of which this manifest should be based upon. Kind acts like a preset for your manifest. [Extension Kinds](../extension-kind.md).
-
-Many of the Extension Types require additional information declared as part of a `meta` field.
-
-## Type intellisense
-
-It is recommended to make use of the Type IntelliSense that we provide.
-
-When writing your Manifest in TypeScript, you should use the Type `UmbExtensionManifest`. See the article on [Development Setup](../../development-flow/) to ensure you have Types correctly configured.
-
-{% code title="manifests.ts" %}
-```typescript
-export const manifests: Array = [
- {
- type: '...',
- alias: 'my.customization',
- name: 'My customization'
- ...
- }
-]
-```
-{% endcode %}
-
-When writing the Umbraco Package Manifest, you can use the JSON Schema located in the root of your Umbraco project called `umbraco-package-schema.json` .
-
-```json
-{
- "$schema": "../../umbraco-package-schema.json",
- "name": "My Customizations",
- "extensions": [
- {
- "type": "...",
- "alias": "my.customization",
- "name": "My customization"
- ...
- },
- ...
- ]
-}
-```
+* `weight` - Define a weight to determine the importance or visual order of this extension. A higher weight gives a more prominent position. For instance, for a dashboard it determines its order between other dashboards.
+* `overwrites` - If you want to omit an existing extension, then define one or more Extension Aliases that this extension should omit when presented. Read more in [Replace, Exclude or Unregister extensions](replace-exclude-or-unregister.md).
+* `conditions` - Define one or more conditions that must pass for the extension to become available. For instance, don't show a section if you don't have the proper rights. Read more in [Extension Conditions](../extension-conditions.md).
+* `kind` - Some extension types can reference a predefined `kind`. By specifying a `kind`, the manifest inherits the `kind`'s properties. This allows for reuse of predefined settings. See [Extension Kind](../extension-kind.md).
+* `meta` - Many Extension Types require additional information declared as part of a `meta` field. It depends on the Extension Type what is required. For instance label and icon of a menu item.
+For more information, see an overview of all possible [Extension Types](../extension-types/) and their requirements.
diff --git a/16/umbraco-cms/customizing/extending-overview/extension-registry/extension-registry.md b/16/umbraco-cms/customizing/extending-overview/extension-registry/extension-registry.md
deleted file mode 100644
index ab9cf37dc89..00000000000
--- a/16/umbraco-cms/customizing/extending-overview/extension-registry/extension-registry.md
+++ /dev/null
@@ -1,75 +0,0 @@
----
-description: >-
- Bringing new UI or additional features to the Backoffice is done by
- registering an Extension via an Extension Manifest.
----
-
-# Register an Extension
-
-Whether you're looking to make a single correction or a package, it is done via a file on the server that we call Umbraco Package JSON. This will be your starting point.
-
-## Umbraco-package.json
-
-In this file, you declare a name for the Package and declare one or more [`extension manifests`](extension-manifest.md).
-
-```json
-{
- "name": "My Customizations",
- "extensions": [
- {
- "type": "...",
- "alias": "my.customization",
- "name": "My customization"
- ...
- },
- ...
- ]
-}
-```
-
-When writing the Umbraco Package Manifest, you can use the JSON Schema located in the root of your Umbraco project. The file is called `umbraco-package-schema.json`
-
-```json
-{
- "$schema": "../../umbraco-package-schema.json",
- "name": "My Customizations",
- "extensions": [
- ...
- ]
-}
-```
-
-## Declare Extensions in JavaScript/TypeScript
-
-Are you looking for as much help as you can get, or to make a bigger project? Then it's recommended to spend the time setting up a TypeScript Project for your Customizations. [Read more about Development Setups here](../../development-flow/).
-
-TypeScript gives IntelliSense for everything, acting as documentation.
-
-The following example demonstrates how you can configure your `umbraco-package.json` file to point to a single JavaScript/TypeScript file that declares all your Manifests.
-
-There are two approaches for declaring Manifests in JavaScript/TypeScript. Read more about each option:
-
-### [The Bundle approach](../extension-types/bundle.md)
-
-The Bundle is an Extension that declares one or more Extension Manifests.
-
-### [The Entry Point approach](../extension-types/backoffice-entry-point.md)
-
-The Entry Point is an Extension that executes a method on startup. This can be used for different tasks, such as performing initial configuration and registering other Extension Manifests.
-
-### Registration via any JavaScript code
-
-Once you have running code, you can declare an Extension Manifest at any given point.
-
-It's not a recommended approach, but for some cases, you may like to register and unregister Extensions on the fly. The following example shows how to register an extension manifest via JavaScript/TypeScript code:
-
-```typescript
-import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
-
-const manifest = {
- type: '...',
- ...
-};
-
-umbExtensionsRegistry.register(extension);
-```
diff --git a/16/umbraco-cms/customizing/extending-overview/extension-registry/register-extensions.md b/16/umbraco-cms/customizing/extending-overview/extension-registry/register-extensions.md
new file mode 100644
index 00000000000..0e46a5e2455
--- /dev/null
+++ b/16/umbraco-cms/customizing/extending-overview/extension-registry/register-extensions.md
@@ -0,0 +1,120 @@
+---
+description: >-
+ You can bring new UI or additional features to the Backoffice by
+ registering an Extension via an Extension Manifest.
+---
+
+
+# Register Extensions
+Making extensions to either an Umbraco project or a package requires an umbraco-package.json file. This JSON file is the starting point for any extension.
+
+## Umbraco-package.json
+To get extensions registered in Umbraco, you need to have an `umbraco-package.json` file. This file must be located in or in a subfolder of either the `App_Plugins` folder or the `wwwroot` folder. It's recommended to place the file in `App_Plugins/#YOUR_EXTENSION_NAME#/umbraco-package.json`, or in `wwwroot/App_Plugins/#YOUR_EXTENSION_NAME#/umbraco-package.json` for packages and Razor Class Libraries. Umbraco scans for these files on boot and reads the [`Extension Manifests`](extension-manifest.md) that are present in the file to register the extensions.
+
+{% hint style="info" %}
+Extensions can also work outside of the context of a package.
+{% endhint %}
+
+{% code title="umbraco-package.json" %}
+```json
+{
+ "name": "My Customizations",
+ "extensions": [
+ {
+ "type": "...",
+ "alias": "my.customization.extension1",
+ "name": "My customization extension 1"
+ ...
+ },
+ ...
+ ]
+}
+```
+{% endcode %}
+
+
+When writing the Umbraco Package Manifest, you can use the JSON schema located in the root of your Umbraco project. This file is called `umbraco-package-schema.json`.
+
+{% code title="umbraco-package.json" %}
+```json
+{
+ "$schema": "../../umbraco-package-schema.json",
+ "name": "My Customizations",
+ "extensions": [
+ ...
+ ]
+}
+```
+{% endcode %}
+
+
+There are two additional, optional properties that can be useful:
+
+* `id` - a unique identifier of the package. If you are creating a NuGet package, use this value as the id.
+* `version` - the version of the package that is displayed in the backoffice in the overview of installed packages. This is also used for package migrations.
+
+
+This is an example of a full `umbraco-package.json` that registers two localization extensions:
+
+```json
+{
+ "$schema": "../../umbraco-package-schema.json",
+ "id": "MyCustomizations",
+ "name": "My Customizations",
+ "version": "16.0.0",
+ "extensions": [
+ {
+ "type": "localization",
+ "alias": "MyCustomizations.Localize.EnUS",
+ "name": "English",
+ "meta": {
+ "culture": "en"
+ },
+ "js": "/App_Plugins/MyCustomizations/localization/en.js"
+ },
+ {
+ "type": "localization",
+ "alias": "MyCustomizations.Localize.DkDk",
+ "name": "Danish",
+ "meta": {
+ "culture": "dk"
+ },
+ "js": "/App_Plugins/MyCustomizations/localization/dk.js"
+ }
+ ]
+}
+```
+
+
+## Advanced Registration
+### The Bundle Approach
+Instead of registering each manifest in the `umbraco-package.json`, you can have multiple manifests and build them into a bundle. You then register this bundle in a single `bundle` extension. In larger projects with a lot of extensions, this allows you to keep your `umbraco-package.json` file cleaner. Read more in the [bundle approach](../extension-types/bundle.md).
+
+### The Entry Point Approach
+The Entry Point is an extension that executes a method on startup. You can use this for different tasks, such as performing initial configuration and registering other Extension Manifests. Read more in [the entry point approach](../extension-types/backoffice-entry-point.md).
+
+### Registration with JavaScript on the Fly
+In some cases, extensions are not static and cannot be registered in the umbraco-package.json or in a bundle. Here are some examples of these cases:
+
+- your manifest might be defined based on information from the server
+- you might generate the manifests server side based on data in the database.
+
+In cases such as these, you need to register extensions on the fly.
+
+
+The following example shows how to register an Extension Manifest via JavaScript/TypeScript code:
+
+```typescript
+
+import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
+
+const manifest = {
+ type: '...',
+ // ...
+};
+
+umbExtensionsRegistry.register(manifest);
+```
+
+
+When and where you execute this code depends on your situation. In many cases, it makes sense to execute this on boot, using the [entry point approach](../extension-types/backoffice-entry-point.md).
diff --git a/16/umbraco-cms/customizing/extending-overview/extension-registry/replace-exclude-or-unregister.md b/16/umbraco-cms/customizing/extending-overview/extension-registry/replace-exclude-or-unregister.md
index 0fded461712..cd8de5eb9a4 100644
--- a/16/umbraco-cms/customizing/extending-overview/extension-registry/replace-exclude-or-unregister.md
+++ b/16/umbraco-cms/customizing/extending-overview/extension-registry/replace-exclude-or-unregister.md
@@ -4,15 +4,19 @@ description: >-
interest, 3 different options are available.
---
+
# Replace, Exclude or Unregister
+Besides adding extensions to Umbraco, sometimes you want to change what is already there. You can replace extensions with your own and exclude or unregister extensions.
+
## Replace
+You can replace an existing extension by another one.
+You can do this by defining the `overwrites` property in your [Extension Manifest](extension-manifest.md) with one Extension Alias. For multiple `overwrites` you can provide the Extension Aliases that need to be replaced as an array.
+
-If you want to bring your own extension and remove an existing, define your Extension to replace one or more other Extensions.
-This can be done by defining `overwrites` of your manifest with one Extension-alias or an array of Extension-aliases. [Read more about the Manifest Declaration here.](extension-manifest.md)
-Overwrite a single extension:
+This example overrides the `save and preview` button with an external "preview" button (single overwrite):
```typescript
const manifest = {
@@ -24,7 +28,8 @@ const manifest = {
};
```
-Overwrite multiple extensions:
+
+This example overrides both the `save and preview` button as well as the `save` button with an external "preview" button (multiple overwrite):
```typescript
const manifest = {
@@ -36,13 +41,18 @@ const manifest = {
};
```
-Once your extension is displayed in the same spot as the one defined in `overwrites`, those will be hidden.
-If your extension has conditions, then the overwrites will only be hidden when your extension is displayed. This means that the overwrites only have an effect if all the conditions are permitted and the extensions are displayed at the same spot.
+If your extension has conditions, the overwritten extensions will only be hidden when your extension is displayed. This means that the overwrites only have an effect if all the conditions are permitted and the extensions are displayed at the same spot.
+
## Exclude
+When you exclude an extension, the extension will never be displayed. This allows you to permanently hide, for example, a menu or a button. This does not unregister the extension, but rather flags it as excluded. This also means that no one else can register an extension with the same alias as the excluded extension.
+
+
+{% hint style="warning" %}
+Currently, it is not possible to un-exclude extensions once excluded.
+{% endhint %}
-To make an extension go away completely, you should exclude it. This approach secures that the extension will never be presented.
The following JavaScript code hides the `Save and Preview` button from the Document Workspace.
@@ -52,9 +62,13 @@ import { UmbExtensionRegistry } from '@umbraco-cms/backoffice/extension-api';
UmbExtensionRegistry.exclude('Umb.WorkspaceAction.Document.SaveAndPreview');
```
+When and where you execute this code depends on your situation. In many cases, it makes sense to execute this on boot, using the [entry point approach](../extension-types/backoffice-entry-point.md).
+
+
## Unregister
+You can also choose to unregister an extension. You should only use this on extensions you registered yourself and have control over. Otherwise, you might try to remove an extension before it is registered. A use case for this, is if you temporarily registered an extension and you want to remove it again.
-You can also choose to unregister an extension, this is only preferred if you registered the extension and are in control of the flow. If it's not your Extension please seek to use the `Overwrites` or `Exclude` feature.
+In other cases, you can use the `overwrites` or `exclude` option. The difference with the `exclude` approach is that unregistering removes the extension from the Extension Registry. This allows you to re-register extensions with the same alias.
```typescript
import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
@@ -62,6 +76,7 @@ import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registr
umbExtensionsRegistry.unregister('My.WorkspaceAction.AutoFillWithUnicorns');
```
-This will not prevent the Extension from being registered again.
-A use case for this is if you temporarily registered an extension and you like to remove it again.
+When and where you execute this code depends on your situation. In many cases, it makes sense to execute this on boot, using the [entry point approach](../extension-types/backoffice-entry-point.md).
+
+