4장. TechDocs add-ons

Procedure

1. From the Developer perspective in the OpenShift Container Platform web console, click ConfigMaps > Create ConfigMap.
2. From the Create ConfigMap page, select the YAML view option in the Configure via field.

3. In the newly created ConfigMap, add the default backstage-plugin-techdocs-module-addons-contrib package configuration. For example:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

4. In the techdocsAddons section of the ConfigMap, add importName: <external_techdocs_add-on> for each external TechDocs add-on that you want to add from the specified plugin package. For example:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   where:

   <external_techdocs_add-on>

   Specifies the external TechDocs add-on that you want to install, for example, TextSize or LightBox.

5. Click Create.
6. In the web console navigation menu, click Topology.
7. Click on the overflow menu for the Red Hat Developer Hub instance that you want to use and select Edit Backstage to load the YAML view of the Red Hat Developer Hub instance.

8. In your Backstage CR, add the dynamicPluginsConfigMapName: <dynamic_plugins_configmap> key-value pair. For example:

   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: my-rhdh
   spec:
     application:
   # ...
       dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_
   # ...

   where:

   <dynamic_plugins_configmap>

   Specifies the name of your dynamic plugins ConfigMap for your Red Hat Developer Hub instance, for example, dynamic-plugins-rhdh.

9. Click Save.
10. In the web console navigation menu, click Topology and wait for the Red Hat Developer Hub pod to start.
11. Click the Open URL icon to start using the Red Hat Developer Hub platform with the new configuration changes.

Procedure

1. In your Helm chart, add the global.dynamic parameters required to install a dynamic plugin, as shown in Installing dynamic plugins using the Helm chart

   참고

   The default configuration includes the dynamic-plugins.default.yaml file, which contains all of the dynamic plugins, including TechDocs add-ons, that are preinstalled in Red Hat Developer Hub, whether they are enabled or disabled by default.

2. In your Helm chart, add the default backstage-plugin-techdocs-module-addons-contrib package configuration. For example:

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

3. In the techdocsAddons section of the Helm chart, add importName: <external_techdocs_add-on> for each external TechDocs add-on that you want to add from the specified plugin package. For example:

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   where:

   <external_techdocs_add-on>

   Specifies the external TechDocs add-on that you want to install, for example, TextSize or LightBox.

Procedure

1. Install the third-party plugin that you want to use to import your third-party add-on by entering the following command:

   yarn install

2. Obtain the source code for the third-party TechDocs add-on that you want to use.

3. Export the TechDocs add-on as a dynamic plugin using the following command:

   npx @red-hat-developer-hub/cli@latest plugin export

   참고

   The @latest tag pulls the latest version of the @red-hat-developer-hub/cli package, which is compatible with the most recent features and fixes. Use a version that is compatible with your Red Hat Developer Hub version.

4. To package the third-party TechDocs add-on as a dynamic plugin, navigate to the root directory where the plugin is stored (not the dist-dynamic directory) and run the npx command with the --tag option to specify the image name and tag. For example:

   npx @red-hat-developer-hub/cli@latest plugin package --tag quay.io/<user_name>/<techdocs_add-on_image>:latest

   참고

   The output of the package-dynamic-plugins command provides the file path to the plugin for use in the dynamic-plugin-config.yaml file.

5. To publish the third-party TechDocs add-on to a Quay repository, push the image to a registry using one of the following commands, depending on your virtualization tool:

   • To use podman, enter the following command:

     podman push quay.io/<user_name>/<techdocs_add-on_image>:latest

   • To use docker, enter the following command:

     docker push quay.io/<user_name>/<techdocs_add-on_image>:latest

6. Open your dynamic-plugins.yaml file to view or modify the configuration for the third-party TechDocs add-on. For example:

   plugins:
         - package: oci://quay.io/<user_name>/<techdocs_add-on_image>:latest!<techdocs_add-on_package>
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                <techdocs_add-on_package>
                   techdocsAddons:
                     - importName: <third-party_add-on_name>
                      config:
                         props:
                          <techdocs_add-on_property_key>: <techdocs_add-on_property_value>

   where

   <user_name>

   Specifies your Quay user name or organization name.

   <techdocs_add-on_image>

   Specifies the name of the image for the third-party add-on that you want to use, for example, mermaid.

   <techdocs_add-on_package>

   Specifies the , for example, backstage-plugin-techdocs-addon-mermaid.

   <third-party_add-on_name>

   Specifies the name of the third-party add-on that you want to use, for example, Mermaid.

   <techdocs_add-on_property_key>

   Specifies the name of the custom property that can be passed to the third-party add-on, for example, themeVariables. Properties are specific to each add-on. You can list multiple properties for an add-on.

   <techdocs_add-on_property_value>

   Specifies the value of a property key for the third-party add-on, for example, lineColor: #000000.