Flat hirerachy to increase visibility

Author: gtrivedi88

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/examples/snip_che-steps-to-add-or-remove-extensions-in-openvsx-sync-json.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/examples/snip_che-steps-to-build-custom-plugin-registry-in-workspace.adoc

@@ -0,0 +1,104 @@
+:_content-type: PROCEDURE
+
+[id="adding-or-removing-extensions-in-a-workspace_{context}"]
+= Adding or removing extensions by using a {prod-short} workspace
+
+You can add or remove extensions in the embedded Open VSX registry instance directly within a {prod-short} workspace. This results in a custom build of the Open VSX registry that can be used in your organization's workspaces.
+
+[IMPORTANT]
+====
+You can manage Visual Studio Code extensions by setting up and using an internal, on-premises Open VSX registry. This approach provides full control over the extension lifecycle, enables offline use, and improves compliance. The embedded plugin registry will be deprecated in future releases, with the Open VSX registry serving as its successor. 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]