[DOCS-4552] Flat hirerachy to increase readability

modules/administration-guide/examples/snip_che-non-default-vsx-registry-instance.adoc

@@ -1 +1 @@
-* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. This subset is xref:adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance[customizable].
+* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. You can customize this subset xref:adding-or-removing-extensions-in-a-workspace_{context}[using a workspace] or xref:adding-or-removing-extensions-on-linux_{context}[using a Linux operating system].

modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc

@@ -7,9 +7,9 @@
 [id="extensions-for-microsoft-visual-studio-code-open-source"]
 = Extensions for Microsoft Visual Studio Code - Open Source
 
-To manage extensions, link:https://github.com/microsoft/vscode[this IDE] uses one of these link:https://open-vsx.org/about[Open VSX] registry instances:
+To manage extensions, {prod-short} uses one of the following Open VSX registry instances:
 
-* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. This subset is xref:adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance[customizable].
+* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. You can customize this subset xref:adding-or-removing-extensions-in-a-workspace_{context}[using a workspace] or xref:adding-or-removing-extensions-on-linux_{context}[using a Linux operating system].
 
 * The public link:https://open-vsx.org[open-vsx.org] registry that is accessed over the internet.
 
@@ -19,4 +19,6 @@ include::example$snip_{project-context}-default-vsx-registry.adoc[]
 
 include::partial$proc_selecting-an-open-vsx-registry-instance.adoc[leveloffset=+1]
 
-include::partial$proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc[leveloffset=+1]
+include::partial$proc_adding-or-removing-extensions-in-a-workspace.adoc[leveloffset=+1]
+
+include::partial$proc_adding-or-removing-extensions-on-linux.adoc[leveloffset=+1]

modules/administration-guide/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc

@@ -0,0 +1,105 @@
+:_content-type: PROCEDURE
+
+[id="adding-or-removing-extensions-in-a-workspace_{context}"]
+= Adding or removing extensions by using a {prod-short} workspace
+
+[role="_abstract"]
+You can add or remove extensions in the embedded Open VSX registry instance directly within a {prod-short} workspace to create a custom build for your organization.
+
+[IMPORTANT]
+====
+The embedded plugin registry will be deprecated in future releases and replaced by the Open VSX registry. Setting up an internal, on-premises Open VSX registry provides full control over the extension lifecycle, enables offline use, and improves compliance. Refer to the xref:running-the-open-vsx-on-premises.adoc[Running the Open VSX On-Premises] procedure for detailed setup instructions.
+====
+
+.Prerequisites
+
+* You are logged in to your {prod-short} instance as an administrator.
+* You have started a workspace using the link:https://github.com/eclipse-che/che-plugin-registry[plugin registry repository].
+* You have created a link:https://access.redhat.com/terms-based-registry/[Red Hat Registry Service Account] and have the username and token available.
+* For IBM Power (`ppc64le`) and IBM Z (`s390x`) architectures, you must build the custom plugin registry locally on the corresponding hardware.
+* (Optional) You can rebuild the container based on the latest tag or SHA to get the latest security fixes after a {prod-short} update.
+
+.Procedure
+
+. Open a terminal in your workspace.
+
+. Check out the Git tag that corresponds to your {prod-short} version:
++
+[source,bash,subs="+quotes"]
+----
+$ git checkout __<product_version>__
+----
+
+. Identify the publisher and extension name for each extension you want to add:
+.. Find the extension on the link:https://open-vsx.org/[Open VSX registry website].
+.. Copy the URL of the extension's listing page.
+.. Extract the `<publisher>` and `<name>` from the URL:
++
+[subs="+quotes"]
+----
+https://open-vsx.org/extension/__<publisher>__/__<name>__
+----
++
+[TIP]
+====
+If the extension is only available from link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace], but not link:https://open-vsx.org[Open VSX], you can ask the extension publisher to publish it on link:https://open-vsx.org[open-vsx.org] according to these link:https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[instructions], potentially using this link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action].
+
+If the extension publisher is unavailable or unwilling to publish the extension to link:https://open-vsx.org[open-vsx.org], and if there is no Open VSX equivalent of the extension, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team.
+====
+
+. Open the `openvsx-sync.json` file in the repository.
+
+. Add or remove extensions using the following JSON syntax:
++
+[source,json,subs="+quotes"]
+----
+{
+    "id": "__<publisher>__.__<name>__",
+    "version": "__<extension_version>__"
+}
+----
++
+[TIP]
+====
+If you have a closed-source extension or an extension developed only for internal use in your organization, you can add the extension directly from a `.vsix` file by using a URL accessible to your custom plugin registry container:
+
+[source,json,subs="+quotes"]
+----
+{
+    "id": "__<publisher>__.__<name>__",
+    "download": "__<url_to_download_vsix_file>__",
+    "version": "__<extension_version>__"
+}
+----
+
+Read the link:https://aka.ms/vsmarketplace-ToU[Terms of Use] for the link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace] before using its resources.
+====
+
+. Log in to the Red Hat registry:
+.. Navigate to *Terminal* -> *Run Task...* -> *devfile*.
+.. Run the *1. Login to registry.redhat.io* task.
+.. Enter your Red Hat Registry Service Account credentials when prompted.
+
+. Build and publish the custom plugin registry:
+.. Navigate to *Terminal* -> *Run Task...* -> *devfile*.
+.. Run the *2. Build and Publish a Custom Plugin Registry* task.
++
+[NOTE]
+====
+Verify that the `CHE_CODE_VERSION` in the `build-config.json` file matches the version of the editor currently used with {prod-short}. Update it if necessary.
+====
+
+. Configure {prod-short} to use the custom plugin registry:
+.. Navigate to *Terminal* -> *Run Task...* -> *devfile*.
+.. Run the *3. Configure Che to use the Custom Plugin Registry* task.
+
+.Verification
+
+. Check that the `plugin-registry` pod has restarted and is running.
+. Restart your workspace.
+. Open the *Extensions* view in the IDE and verify that your added extensions are available.
+
+.Additional resources
+
+* link:https://github.com/eclipse-che/che-plugin-registry[Plugin registry repository]
+* xref:running-the-open-vsx-on-premises.adoc[Running the Open VSX On-Premises]