在Backstage中配置并使用Tech-Docs

注意
本文档基于 Backstage 1.32.0 版本编写，并采用自 1.24.0 版本以来官方推荐使用的新后端系统（New BackEnd System）。Backstage 仍处于不断更新发展中，本文下述步骤可能将不适用于后续更新版本。

一、开发前准备

1. 确保能够登录或持有 Backstage 服务所在服务器的 Root 账户权限
2. 确保至少已经完成了 GitLab 的集成；若未完成本部分工作，请参考此文档：在Backstage中集成GitLab
3. 开发参考文档：
   • Backstage 官方 | 技术文档

二、集成技术文档

（1）安装依赖

首先检查一下 app/package.json 文件中是否已经存在了 @backstage/plugin-techdocs 依赖，以及 backend/package.json 文件中是否已经存在了 @backstage/plugin-techdocs-backend 依赖。

一般来说，在初始化 Backstage 项目时，Backstage 官方的脚手架就会自动为我们准备好这两个依赖包。

若确实不存在，则请参考此文档进行安装与配置：Backstage 官方 | 技术文档 — 开始

（2）安装外部依赖

首先我们需要使用 Root 账户登录到 Backstage 服务所在的服务器中。

在服务器中安装如下几个依赖包：

1. python3
2. pip3
3. mkdocs
4. mkdocs-techdocs-core

（3）准备 md 配置文件

在 examples/template/content 文件夹中新建文件 mkdocs.yml，并添加如下内容：

1
2
3
4
5
6

site_name: ${{ values.name }} doc
site_description: An informative description of ${{ values.name }}
plugins:
  - techdocs-core
nav:
  - Home: index.md

其中 site_name 以及 site_description 定义这个 Tech-doc 模块的名称和描述信息，在 site_name 中添加 ${{ values.name }} 也就是创建的项目名称，是为了确保唯一性。

• plugins 表示将使用 techdocs-core 依赖插件对这个 Tech-doc 进行分析和构建
• nav 是对 Tech-doc 结构的说明：以本例来说，Home 是目录名称，index.md 表示该目录对应的 md 文档

（4）准备配置文件中对应的文档

在 content 文件夹下新建一个文件夹 docs，并在其中新建文件 index.md（这里的 index.md 就是对应上面的配置文件中声明的 index.md）。

index.md 文件中可以预先添加如下内容：

1
2
3

# example docs

This is a basic example of documentation.

（5）添加配置标签

在 content 文件夹下的 catalog-info.yaml 文件中，添加如下内容：

1
2
3
4
5
6
7
8
9

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name }}
  annotations:
    # ...others
    backstage.io/techdocs-ref: dir:./
spec:
  # ...others

接下来会对此标签值的含义做出解释：

• dir 表示以文件相对路径的形式查找对应 docs 所在位置；./ 表示以 catalog-info.yaml 文件为基准，在同级文件夹下寻找名为 docs 的 md 文件夹（这里的 docs 命名为固定的）
• 还有另一种方式是 url:<url>，表示通过 url 网络路径方式查找对应的 md 文件，<url> 填写项目中 docs 文件夹所在位置的 https 链接地址

三、最终呈现效果

效果图如下：

至此，Backstage 核心功能之一的 Tech-Docs 功能也顺利集成完了。