1. Install the npx package to run techdocs-cli using the following command:

   npm install -g npx

2. Install the techdocs-cli tool using the following command:

   npm install -g @techdocs/cli

3. Install the mkdocs plugins using the following command:

   pip install "mkdocs-techdocs-core==1.*"

4. Generate your techdocs site using the following command:

   npx @techdocs/cli generate --no-docker --source-dir <path_to_repo> --output-dir ./site

   Where <path_to_repo> is the location in the file path that you used to clone your repository.

1. Set the necessary authentication environment variables for your cloud storage provider.

2. Publish your techdocs using the following command:

   npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site

3. Add a .github/workflows/techdocs.yml file in your Software Template(s). For example:

   name: Publish TechDocs Site
   
   on:
    push:
      branches: [main]
      # You can even set it to run only when TechDocs related files are updated.
      # paths:
      #   - "docs/**"
      #   - "mkdocs.yml"
   
   jobs:
    publish-techdocs-site:
      runs-on: ubuntu-latest
   
      # The following secrets are required in your CI environment for publishing files to AWS S3.
      # e.g. You can use GitHub Organization secrets to set them for all existing and new repositories.
      env:
        TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        AWS_REGION: ${{ secrets.AWS_REGION }}
        ENTITY_NAMESPACE: 'default'
        ENTITY_KIND: 'Component'
        ENTITY_NAME: 'my-doc-entity'
        # In a Software template, Scaffolder will replace {{cookiecutter.component_id | jsonify}}
        # with the correct entity name. This is same as metadata.name in the entity's catalog-info.yaml
        # ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'
   
      steps:
        - name: Checkout code
          uses: actions/checkout@v3
   
        - uses: actions/setup-node@v3
        - uses: actions/setup-python@v4
          with:
            python-version: '3.9'
   
        - name: Install techdocs-cli
          run: sudo npm install -g @techdocs/cli
   
        - name: Install mkdocs and mkdocs plugins
          run: python -m pip install mkdocs-techdocs-core==1.*
   
        - name: Generate docs site
          run: techdocs-cli generate --no-docker --verbose
   
        - name: Publish docs site
          run: techdocs-cli publish --publisher-type awsS3 --storage-name $TECHDOCS_S3_BUCKET_NAME --entity $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME

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

   Note

   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 @janus-idp/cli@latest package export-dynamic-plugin

   Note

   The @latest tag pulls the latest version of the @janus-idp/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 @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/<user_name>/<techdocs_add-on_image>:latest

   Note

   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.

Procedure

1. From the Developer perspective in the OpenShift Container Platform web console, click ConfigMaps.
2. From the ConfigMaps page, click the ConfigMap that contains the TechDocs add-on that you want to remove.
3. Select the YAML view option in the Configure via field.

4. In the plugins section of the ConfigMap, do one of the following actions based on whether you want to disable or remove a TechDocs add-on:

   • To temporarily disable all of the TechDocs add-ons in a particular plugin package, change the value of the disabled field to true. 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: true
             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 remove, for example, TextSize.

   • To remove one or more TechDocs add-ons from your Red Hat Developer Hub instance, delete importName: <external_techdocs_add-on> for each external TechDocs add-on that you want to remove from the techdocsAddons section of your ConfigMap. 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 remove, for example, TextSize.

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

Procedure

1. In your TechDocs documentation, highlight the text that you want to report an issue for.
2. Click the text in the ReportIssue box, for example, Open new GitHub issue.

3. From the new issue page in your repository, use the template to create the issue that you want to report.

   Note

   The default issue title is Documentation feedback: <highlighted_text>, where <highlighted_text> is the text that you highlighted in your TechDocs documentation.

   In the issue description, <highlighted_text> is the default value for the The highlighted text field.

Procedure

1. In your TechDocs header, click the Settings icon.

2. Use the sliding scale to adjust the size of your documentation text.

   Note

   • The default text size is 100%
   • The minimize text size is 90%
   • The maximum text size is 150%

Procedure

1. In your TechDocs documentation, click on the image that you want to view in a lightbox.

2. In the lightbox, you can do any of the following actions:

   • Click the image or scroll to zoom in or zoom out.
   • Click the arrow to navigate between images.