Red Hat Developer Hub 的 5-4

1. 使用以下命令安装 npx 软件包 以运行 HEKETI-cli ：

   npm install -g npx

2. 使用以下命令安装 HEKETI-cli 工具：

   npm install -g @techdocs/cli

3. 使用以下命令安装 mkdocs 插件：

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

4. 使用以下命令生成 HEKETI 站点：

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

   其中 < path_to_repo > 是用来克隆存储库的文件路径中的位置。

1. 为您的云存储供应商设置必要的身份验证环境变量。

2. 使用以下命令发布您的 HEKETI ：

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

3. 在软件模板中添加 .github/workflows/wagon.yml 文件。例如：

   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

流程

1. 在 Red Hat Developer Hub 实例中，点 Catalog > Self-service > Register Existing Component。

2. 在 Select URL 框中，使用以下格式输入您要从存储库导入的 catalog-info.yaml 文件的 URL：

   https://github.com/&lt;project_name&gt; /<repo_name&gt; /blob/<branch_name&gt; /<file_directory> /catalog-info.yaml

3. 点 Analyze
4. 点 Finish

验证

1. 在 Red Hat Developer Hub 导航菜单中，单击 Docs。
2. 验证您导入的文档是否在 Documentation 页面的表中列出。

流程

1. 从 OpenShift Container Platform Web 控制台中的 Developer 视角，点 ConfigMaps > Create ConfigMap。
2. 在 Create ConfigMap 页面中，在 Configure via 字段中选择 YAML view 选项。

3. 在新创建的 ConfigMap 中，添加默认的 backstage-plugin- swig-module-addons-contrib 软件包配置。例如：

   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. 在 ConfigMap 的 HEKETIAddons 部分中，为您要从指定插件软件包添加的每个外部 TechDocs 附加组件添加 importName: <external_techdocs_add-on>。例如：

   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>

   其中：

   <external_techdocs_add-on>

   指定要安装的外部 TechDocs 附加组件，如 TextSize 或 LightBox。

5. 点 Create。
6. 在 Web 控制台导航菜单中，单击 Topology。
7. 点您要使用的 Red Hat Developer Hub 实例的溢出菜单，然后选择 Edit Backstage 以加载 Red Hat Developer Hub 实例的 YAML 视图。

8. 在 Backstage CR 中，添加 dynamicPluginsConfigMapName: & lt;dynamic_plugins_configmap > 键值对。例如：

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

   其中：

   <dynamic_plugins_configmap>

   为您的 Red Hat Developer Hub 实例指定动态插件 ConfigMap 的名称，如 dynamic-plugins-rhdh。

9. 点击 Save。
10. 在 Web 控制台导航菜单中，点 Topology 并等待 Red Hat Developer Hub pod 启动。
11. 点 Open URL 图标以使用 Red Hat Developer Hub 平台以及新的配置更改。

流程

1. 在 Helm Chart 中，添加安装动态插件所需的 global.dynamic 参数，如使用 Helm Chart 安装动态插件 所示

   注意

   默认配置包含 dynamic-plugins.default.yaml 文件，其中包含所有动态插件，包括 TechDocs 附加组件，这些插件已在 Red Hat Developer Hub 中预安装，无论是默认启用还是禁用。

2. 在 Helm Chart 中，添加默认的 backstage-plugin-5-4-module-addons-contrib 软件包配置。例如：

   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. 在 Helm Chart 的 HEKETI Addons 部分中，为您要从指定插件软件包添加的每个外部 TechDocs 附加组件添加 importName: <external_techdocs_add-on>。例如：

   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>

   其中：

   <external_techdocs_add-on>

   指定要安装的外部 TechDocs 附加组件，如 TextSize 或 LightBox。

流程

1. 输入以下命令安装您要用来导入第三方附加组件的第三方插件：

   yarn install

2. 获取您要使用的第三方 TechDocs 附加组件的源代码。

3. 使用以下命令将 TechDocs 附加组件导出为动态插件：

   npx @janus-idp/cli@latest package export-dynamic-plugin

   注意

   @latest 标签拉取 @janus-idp/cli 软件包的最新版本，该软件包与最新的功能和修复程序兼容。使用与 Red Hat Developer Hub 版本兼容的版本。

4. 要将第三方 TechDocs 附加组件打包为动态插件，请导航到存储插件的根目录（而不是 dist-dynamic 目录），并使用-- tag 选项运行 npx 命令以指定镜像名称和标签。例如：

   npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/<user_name>/<techdocs_add-on_image>:latest

   注意

   package-dynamic-plugins 命令的输出提供了插件的文件路径，以便在 dynamic-plugin-config.yaml 文件中使用。

5. 要将第三方 TechDocs 附加组件发布到 Quay 存储库，请使用以下其中一个命令将镜像推送到 registry，具体取决于您的虚拟化工具：

   • 要使用 podman，请输入以下命令：

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

   • 要使用 docker，请输入以下命令：

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

6. 打开您的 dynamic-plugins.yaml 文件，以查看或修改第三方 TechDocs 附加组件的配置。例如：

   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>

   其中

   <user_name>

   指定您的 Quay 用户名或机构名称。

   <techdocs_add-on_image>

   指定要使用的第三方附加组件的镜像名称，例如 mermaid。

   <techdocs_add-on_package>

   指定，例如 backstage-plugin-5-4-addon-mermaid。

   <third-party_add-on_name>

   指定您要使用的第三方附加组件的名称，例如 Mermaid。

   <techdocs_add-on_property_key>

   指定可传递给第三方附加组件的自定义属性名称，例如，me Variables。属性特定于每个附加组件。您可以列出附加组件的多个属性。

   <techdocs_add-on_property_value>

   指定第三方附加组件的 property 键的值，例如 lineColor: #000000。

流程

1. 从 OpenShift Container Platform Web 控制台中的 Developer 视角，点 ConfigMaps。
2. 在 ConfigMap 页面中，点击包含您要删除的 TechDocs 附加组件的 ConfigMap。
3. 在 Configure via 字段中选择 YAML view 选项。

4. 在 ConfigMap 的 plugins 部分，根据您要禁用还是删除 TechDocs 附加组件来执行以下操作之一：

   • 要临时禁用特定插件软件包中的所有 TechDocs 附加组件，请将 disabled 字段的值更改为 true。例如：

     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>

     其中：

     <external_techdocs_add-on>

     指定您要删除的外部 TechDocs 附加组件，如 TextSize。

   • 要从 Red Hat Developer Hub 实例中删除一个或多个 TechDocs 附加组件，请删除 您要从 ConfigMap 的 HEKETI Addons 部分中删除 importName: <external_techdocs_add-on> 的每个外部 TechDocs 附加组件。例如：

     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>

     其中：

     <external_techdocs_add-on>

     指定您要删除的外部 TechDocs 附加组件，如 TextSize。

5. 点击 Save。
6. 在 Web 控制台导航菜单中，点 Topology 并等待 Red Hat Developer Hub pod 启动。
7. 点 Open URL 图标以使用 Red Hat Developer Hub 平台以及新的配置更改。

流程

1. 在您的 TechDocs 文档中，突出显示您要报告问题的文本。
2. 单击 ReportIssue 框中的文本，如 Open new GitHub issue。

3. 在存储库中的新问题页面中，使用模板来创建您要报告的问题。

   注意

   默认问题标题为 Documentation feedback: &lt ;highlighted_text& gt;，其中 &lt ;highlighted_text > 是您在 TechDocs 文档中突出显示的文本。

   在问题描述中，<highlighted_text > 是 The highlighted text 字段的默认值。

流程

1. 在 TechDocs 标头中，点 Settings 图标。

2. 使用滑块调整文档文本的大小。

   注意
   • 默认文本大小为 100%
   • 最小化文本大小为 90%
   • 最大文本大小为 150%

流程

1. 在您的 TechDocs 文档中，点您要在 lightbox 中查看的镜像。

2. 在 lightbox 中，您可以执行以下操作：

   • 点镜像或滚动以缩放或缩放。
   • 点箭头在镜像间导航。