技术文档操作指南

如何从 TechDocs Basic 迁移到推荐部署方法？

TechDocs 基本部署方法和推荐部署方法的主要区别在于文档的生成和存储位置。在基本或开箱即用的设置中，文档生成和存储在运行 Backstage 实例的服务器上。但推荐设置是在 CI/CD 上生成文档，并将生成的站点存储到外部存储(如 AWS S3 或 GCS)。 Backstage 实例中的 TechDocs 应转为只读模式。请阅读《TechDocs 基本部署方法和推荐部署方法》中的更多详情和优势。技术文档架构.

以下是从基本设置切换到推荐设置所需的步骤 - 从基本设置到推荐设置

1.准备云存储

选择一个云存储提供商，如 AWS、Google Cloud 或 Microsoft Azure。按照以下详细说明进行操作使用云存储在 TechDocs 中。

2.从 CI/CD 发布到存储

从包含源标记符文件的每个版本库的 CI/CD 工作流中开始发布 TechDocs 网站。阅读以下详细说明配置 CI/CD.

将 TechDocs 切换为只读模式

在Backstage实例的app-config.yaml，设置techdocs.builder从'local'至'external'这样，TechDocs 就不会尝试生成文档。请看技术文档配置供参考。

如何理解 techdocs-ref 注释值

如果 TechDocs 被配置为生成文档，它会首先根据backstage.io/techdocs-ref注解中定义的catalog-info.yaml文件。准备步骤。

我们强烈建议backstage.io/techdocs-ref注释中的每个记录的目录实体的catalog-info.yaml设为dir:.这是因为 TechDocs 符合 "文档如同代码 "的理念，即文档的编写和管理应与底层软件本身的源代码同步进行。

当您看到dir:.你可以把它翻译成

文档源代码与 catalog-info.yaml 文件位于同一位置。尤其是，mkdocs.yml 文件是 catalog-info.yaml 的同级文件(即位于同一目录下)。

该实体的目录树如下所示：

├── catalog-info.yaml
├── mkdocs.yml
└── docs
    └── index.md

例如，如果您想保留一个精简的根目录，可以将您的mkdocs.yml子目录中的文件，并更新backstage.io/techdocs-ref相应的注释值，例如改为dir:./sub-folder:

├── catalog-info.yaml
└── sub-folder
    ├── mkdocs.yml
    └── docs
        └── index.md

在极少数情况下，您的 TechDocs 源内容的管理和存储位置完全独立于您的catalog-info.yaml，您可以指定一个 URL 位置引用，其确切值会根据源代码托管服务提供商的不同而有所变化。请注意，这里的dir:前缀url:例如

GitHub: url:https://githubhost.com/org/repo/tree/<branch_name> GitLab: url:https://gitlabhost.com/org/repo/tree/<branch_name> Bitbucket: url:https://bitbuckethost.com/project/repo/src/<branch_name> Azure: url:https://azurehost.com/organization/project/_git/repository Bitbucket: url:https://bitbuckethost.com/project/repo/src/<branch_name> Bitbucket: url:https://bitbuckethost.com/project/repo/src/<branch_name> Azure: `url:https://azurehost.com/organization/project/_git/repository<

注意，正如可以使用dir:前缀，也可以提供一个指向版本库内非根目录的路径，该目录包含mkdocs.yml文件和docs/目录。

例如url:https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/examples/documented-component

为什么 URL 阅读器比 git 克隆更快？

URL Reader 使用源代码托管服务提供商下载仓库的压缩包或 tar 包。该压缩包不附带任何 git 历史记录，而且是压缩文件，因此文件大小远小于 git clone 需要传输的数据量。

如何自定义 TechDocs 主页？

TechDocs 采用了与 Backstage 中的搜索和目录插件类似的可组合模式。为了方便使用，我们提供了与目录插件类似的默认表格体验，但您也可以根据自己组织的需要提供完全自定义的体验。例如，TechDocs 提供了另一种基于网格的布局("TechDocs")。<EntityListDocsGrid>)和面板布局 (TechDocsCustomHome).

在您的app默认情况下，你可能会在你的App.tsx:

const AppRoutes = () => {
  <FlatRoutes>
    <Route path="/docs" element={<TechDocsIndexPage />}>
      <DefaultTechDocsHome />
    </Route>
  </FlatRoutes>;
};

使用 TechDocsCustomHome

您可以使用 TechDocs 面板布局 (<TechDocsCustomHome />).

修改您的App.tsx具体如下

import { TechDocsCustomHome } from '@backstage/plugin-techdocs';
//...

const techDocsTabsConfig = [
  {
    label: 'Recommended Documentation',
    panels: [
      {
        title: 'Golden Path',
        description: 'Documentation about standards to follow',
        panelType: 'DocsCardGrid',
        filterPredicate: entity =>
          entity?.metadata?.tags?.includes('recommended') ?? false,
      },
    ],
  },
];

const AppRoutes = () => {
  <FlatRoutes>
    <Route
      path="/docs"
      element={<TechDocsCustomHome tabsConfig={techDocsTabsConfig} />}
    />
  </FlatRoutes>;
};

建立自定义主页

但您可以更换<DefaultTechDocsHome />的新目录中创建和维护这样一个组件。packages/app/src/components/techdocs并在App.tsx:

例如，您可以定义以下自定义主页组件：

import React from 'react';

import { Content } from '@backstage/core-components';
import {
  CatalogFilterLayout,
  EntityOwnerPicker,
  EntityTagPicker,
  UserListPicker,
  EntityListProvider,
} from '@backstage/plugin-catalog-react';
import {
  TechDocsPageWrapper,
  TechDocsPicker,
} from '@backstage/plugin-techdocs';
import { Entity } from '@backstage/catalog-model';

import { EntityListDocsGrid } from '@backstage/plugin-techdocs';

export type CustomTechDocsHomeProps = {
  groups?: Array<{
    title: React.ReactNode;
    filterPredicate: ((entity: Entity) => boolean) | string;
  }>;
};

export const CustomTechDocsHome = ({ groups }: CustomTechDocsHomeProps) => {
  return (
    <TechDocsPageWrapper>
      <Content>
        <EntityListProvider>
          <CatalogFilterLayout>
            <CatalogFilterLayout.Filters>
              <TechDocsPicker />
              <UserListPicker initialFilter="all" />
              <EntityOwnerPicker />
              <EntityTagPicker />
            </CatalogFilterLayout.Filters>
            <CatalogFilterLayout.Content>
              <EntityListDocsGrid groups={groups} />
            </CatalogFilterLayout.Content>
          </CatalogFilterLayout>
        </EntityListProvider>
      </Content>
    </TechDocsPageWrapper>
  );
};

然后，您可以将以下内容添加到您的App.tsx:

import { CustomTechDocsHome } from './components/techdocs/CustomTechDocsHome';
// ...
const AppRoutes = () => {
  <FlatRoutes>
    <Route path="/docs" element={<TechDocsIndexPage />}>
      <CustomTechDocsHome
        groups={[
          {
            title: 'Recommended Documentation',
            filterPredicate: entity =>
              entity?.metadata?.tags?.includes('recommended') ?? false,
          },
          {
            title: 'My Docs',
            filterPredicate: 'ownedByUser',
          },
        ]}
      />
    </Route>
  </FlatRoutes>;
};

如何自定义 TechDocs 阅读器页面？

与自定义 TechDocs 主页的方法类似，也可以自定义 TechDocs 阅读器页面。在您的app默认情况下，你可能会在你的App.tsx:

const AppRoutes = () => {
  <Route path="/docs/:namespace/:kind/:name/*" element={<TechDocsReaderPage />}>
    {techDocsPage}
  </Route>;
};

techDocsPage是默认的 techdocs 阅读器页面，位于packages/app/src/components/techdocs它包括以下内容，无需进行任何设置。

<Page themeId="documentation">
  <TechDocsReaderPageHeader />
  <TechDocsReaderPageSubheader />
  <TechDocsReaderPageContent />
</Page>

如果您想编写自己的techDocsPage您可以将 TechDocsPage 的子代替换为其他内容。也许您是只是有兴趣更换接头：

<Page themeId="documentation">
  <Header type="documentation" title="Custom Header" />
  <TechDocsReaderPageContent />
</Page>

或者您想禁用上下文搜索

<Page themeId="documentation">
  <Header type="documentation" title="Custom Header" />
  <TechDocsReaderPageContent withSearch={false} />
</Page>

或者您想替换整个 TechDocs 页面。

<Page themeId="documentation">
  <Header type="documentation" title="Custom Header" />
  <Content data-testid="techdocs-content">
    <p>my own content</p>
  </Content>
</Page>

如何从 TechDocs Alpha 版迁移到 Beta 版

本指南仅适用于 "推荐的 "TechDocs 部署方法(其中使用了 > 外部存储提供商和外部 CI/CD)。如果您使用的是 >"基本 "或 "开箱即用 "设置，则可以到此为止！无需任何操作。

在本指南中，TechDocs Beta 版本被定义为：

TechDocs 插件：至少 v0.11.0 TechDocs 后端插件：至少 v0.10.0 TechDocs CLI：至少 `v0.7.0

TechDocs 测试版对访问和存储 TechDocs 内容的方式进行了重大修改，允许使用不区分大小写的实体三元组路径(例如："......")访问页面。/docs/namespace/kind/name而在以前的版本中，只能在/docs/namespace/Kind/name为了实现这一更改，必须使用实体三元组小写的对象键将文档存储在外部存储提供商中。

测试版之后新安装的 TechDocs 无需任何操作即可正常运行，但对于在此版本之前运行 TechDocs 的用户，则需要进行迁移，以便存储桶中的所有现有内容都符合小写实体三元组的要求。

确保您拥有存储提供商的正确权限：为了迁移存储提供商中的文件，"techdocs-cli "需要能够读取/复制/重命名/移动/删除文件。具体说明因存储提供商而异，详情请查看使用云存储页面。 2. 运行非破坏性的文件迁移：确保您已安装最新版本的 "techdocs-cli"。然后运行以下命令，使用与您的提供商/配置相关的详细信息。这将把所有文件从 "名称空间/种类/名称/种类excel.html "复制到 "名称空间/种类/名称/种类excel.html"，而不会删除原始文件。

techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --verbose

Deploy the updated versions of the TechDocs plugins: Once the migration above has been run, you can deploy the beta versions of the TechDocs backend and frontend plugins to your Backstage instance. 4. Verify that your TechDocs sites are still loading/accessible: Try accessing a TechDocs site using different entity-triplet case variants, e.g. /docs/namespace/KIND/name or /docs/namespace/kind/name. Your TechDocs site should load regardless of the URL path casing you use. 5. Clean up the old objects from storage: Once you've verified that your TechDocs site is accessible, you can clean up your storage bucket by re-running the migrate command on the TechDocs CLI, but with an additional removeOriginal flag passed:

techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --removeOriginal --verbose

更新您的 CI/CD 管道以使用测试版的 TechDocs CLI：最后，您可以更新您所有的 CI/CD 管道以使用至少 v0.x.y 版的 TechDocs CLI，从而确保所有站点都发布到新的、小写的实体三元组路径。

如果在运行此迁移时遇到问题，请报告问题您可以通过更改配置暂时恢复到发布前的存储预期：

techdocs:
  legacyUseCaseSensitiveTripletPaths: true

如何实现自己的 TechDocs API

TechDocs 插件默认提供两个主要应用程序接口的实现技术文档存储接口负责与 TechDocs 存储对话以获取要渲染的文件，以及TechDocsApi负责与 techdocs 后端对话。

在某些情况下，您可能需要自己实现这两个 API，以便根据自己的需要对其进行定制。本指南的目的是指导您如何分两步实现这一点。

根据需要实施 TechDocsStorageApi 和 TechDocsApi 接口。

export class TechDocsCustomStorageApi implements TechDocsStorageApi {
  // your implementation
}

export class TechDocsCustomApiClient implements TechDocsApi {
  // your implementation
}

使用 "ApiFactories "在 "App.tsx "中覆盖 API refs `techdocsStorageApiRef "和 "techdocsApiRef"。了解更多有关应用程序 API 的信息。

const app = createApp({
  apis: [
    // TechDocsStorageApi
    createApiFactory({
      api: techdocsStorageApiRef,
      deps: { discoveryApi: discoveryApiRef, configApi: configApiRef },
      factory({ discoveryApi, configApi }) {
        return new TechDocsCustomStorageApi({ discoveryApi, configApi });
      },
    }),
    // TechDocsApi
    createApiFactory({
      api: techdocsApiRef,
      deps: { discoveryApi: discoveryApiRef },
      factory({ discoveryApi }) {
        return new TechDocsCustomApiClient({ discoveryApi });
      },
    }),
  ],
});

如何在软件模板中添加文档设置

软件模板中的 Backstage 是一个可以帮助用户从已配置的模板中创建新组件的工具。它自带一套默认模板供用户使用，但用户也可以添加自己的模板.

如果您已经设置了自己的模板，我们强烈建议您在这些模板中包含 TechDocs 的必要设置。在创建新组件时，您的用户将自动获得一个 TechDocs 网站并开始运行，为他们编写技术文档做好准备。

本指南的目的是指导您如何在新模板中添加所需的配置和一些默认的标记符文件。您可以使用React-ssr-template在学习步骤时作为参考。

先决条件

现有软件模板，包括一个 template.yaml 和一个骨架文件夹，其中至少包括一个 catalog-info.yaml。

在骨架文件夹中的 catalog-info.yaml 中添加以下几行，更新组件的实体描述。

annotations:
  backstage.io/techdocs-ref: dir:.

backstage.io/techdocs-ref被 TechDocs 用来下载文档源文件，以生成实体的 TechDocs 网站。

在骨架文件夹根目录下创建一个内容如下的 mkdocs.yml 文件：

site_name: ${{values.component_id}}
site_description: ${{values.description}}

nav:
  - Introduction: index.md

plugins:
  - techdocs-core

在骨架文件夹中创建一个/docs文件夹，其中至少包含一个index.md文件。

docs/index.md例如，可以有以下内容

# ${{ values.component_id }}

${{ values.description }}

## Getting started

Start writing your documentation by adding more markdown (.md) files to this
folder (/docs) or replace the content in this file.

注意： site_name、component_id 和 site_description 的值取决于您配置 template.yaml 的方式。

完成！您现在可以在自己的软件模板中支持 TechDocs 了！

防止下载谷歌字体

如果您的 Backstage 实例无法访问互联网，则生成将失败。 TechDocs 会尝试从 Google 下载 Roboto 字体。您可以在 mkdocs.yaml 中添加以下行来禁用它：

theme:
  name: material
  font: false

注意：必须添加name: material，否则将无法运行

如何在 TechDocs 中启用 iframe

TechDocs 使用DOMPurify库对 HTML 进行消毒，防止 XSS 攻击。

可以根据允许的主机列表来允许某些 iframe。要做到这一点，请在techdocs.sanitizer.allowedIframeHosts您的app-config.yaml.

例如

techdocs:
  sanitizer:
    allowedIframeHosts:
      - drive.google.com

这样，所有 src 属性中主机位于sanitizer.allowedIframeHosts将显示列表。

如何在 TechDocs 中呈现 PlantUML 图表

PlantUML 允许您使用纯文本语言创建图表。每个图表描述都以关键字 -(@startXYZ 和 @endXYZ，取决于图表类型)开始。对于 UML 图表，应使用关键字 @startuml 和 @enduml。有关所有类型图表的更多详情，请访问PlantUML 语言参考指南.

UML 图表详情：-

嵌入式 PlantUML 图例

在这里，markdown 文件本身包含图表描述。

```plantuml
@startuml
title Login Sequence
    ComponentA->ComponentB: Login Request
    note right of ComponentB: ComponentB logs message
    ComponentB->ComponentA: Login Response
@enduml

#### 引用 PlantUML 图表示例

在这里，markdown 文件引用了另一个文件 (`*.puml`或`*.pu`)，其中包含图表说明。

```md
```plantuml
!include umldiagram.puml

注：要引用外部图表文件，我们需要在路径中包含图表目录。 请参考[Docker文件](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)了解详情。

## 如何在 TechDocs 中添加美人鱼支持

添加`Mermaid`支持，您可以使用[`kroki`](https://kroki.io)它是所有流行的图表即代码工具的单一渲染网关。 它支持大量的图表类型。

1. **创建并发布 Docker 镜像：** 从以下 `Dockerfile` 中创建 Docker 镜像并将其发布到 DockerHub。

```docker
FROM python:3.10-alpine

RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig

RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.2.0

RUN pip install mkdocs-kroki-plugin

ENTRYPOINT [ "mkdocs" ]

在你的 DockerHub 中创建一个仓库，然后在你的Dockerfile存在：

docker build . -t dockerHub_Username/repositoryName:tagName

docker 镜像就绪后，将其推送到 DockerHub。

更新 app-config.yaml： 这样当你的应用程序生成 TechDocs 时，它就会从 DockerHub 拉取你的 docker 镜像。

techdocs:
  builder: 'local' # Alternatives - 'external'
  generator:
    runIn: 'docker' # Alternatives - 'local'
    dockerImage: dockerHub_Username/repositoryName:tagName
    pullImage: true
  publisher:
    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.

在 mkdocs.yml 中添加 kroki 插件：

plugins:
  - techdocs-core
  - kroki

注意：你很可能也想在你的 > mkdocs.yml 中设置一个 kroki```ServerURL 配置。默认值是公共托管的 kroki.io。如果你的组织图表中有敏感信息，你应该设置 > 一个你自己的服务器并使用它 > 来代替。请查看 mkdocs-krokii-plugin config > 了解更多插件配置细节。

在 TechDocs 中添加美人鱼代码：

```kroki-mermaid
sequenceDiagram
GitLab->>Kroki: Request rendering
Kroki->>Mermaid: Request rendering
Mermaid-->>Kroki: Image
Kroki-->>GitLab: Image

完成！现在，您已经有了以下图表和美人鱼的支持：

* `PlantUML` * `BlockDiag` * `BPMN` * `ByteField` * `SeqDiag` * `ActDiag` * `NwDiag` * `PacketDiag` * `RackDiag` * `C4 with PlantUML` * `Ditaa` * `Erd` * `Excalidraw` * `GraphViz` * `Nomnoml` * `Pikchr` * `Svgbob` * `UMlet` * `Vega` * `Vega-Lite` * `WaveDrom`

## 如何实施混合构建策略

其局限性之一是[建议的部署](./architecture.md#recommended-deployment)对于某些用户来说，这可能是不必要的，而且也为用户加入 Backstage 设置了门槛。 然而，纯粹的本地 TechDocs 构建限制了 TechDocs 创建者使用 Backstage 提供的工具，以及 Backstage 包含的插件和功能。`mkdocs`安装。

为了满足这两种使用情况，用户可以实施自定义的[建设战略](./concepts.md#techdocs-build-strategy)逻辑来编码哪些 TechDocs 应在本地构建，哪些将从外部构建。

为了实现这种混合构建模式：

1. In your Backstage instance's `app-config.yaml`, set `techdocs.builder` to `'local'`. This ensures that Backstage will build docs for users who want the 'out-of-the-box' experience. 2. Configure external storage of TechDocs as normal for a production deployment. This allows Backstage to publish documentation to your storage, as well as allowing other users to publish documentation from their CI/CD pipelines. 3. Create a custom build strategy, that implements the `DocsBuildStrategy` interface, and which implements your custom logic for determining whether to build docs for a given entity. For example, to only build docs when an entity has the `company.com/techdocs-builder` annotation set to `'local'`: ```typescript export class AnnotationBasedBuildStrategy { private readonly config: Config; constructor(config: Config) { this.config = config; } async shouldBuild(_: Entity): Promise<boolean> { return ( this.entity.metadata?.annotations?.['company.com/techdocs-builder'] === 'local' ); } } ``` 4. Pass an instanc

现在，用户应该可以选择由 TechDocs 后端通过添加`company.com/techdocs-builder`如果该注解的值是`'local'`的值，TechDocs 后端将为其构建和发布文档。 如果`company.com/techdocs-builder`注释不是`'local'`用户有责任将文档发布到 TechDocs 外部存储的适当位置。

## 如何使用其他 mkdocs 插件？

默认插件[mkdocs-techdocs-core](https://github.com/backstage/mkdocs-techdocs-core)您的组织可能有核心插件之外的需求，以下是启用其他插件的推荐方法。

### 安装插件

#### 与 CI 生成

如果在 CI 中使用`@techdocs/cli`，你需要在执行 cli 的运行时安装所需的 mkdocs 插件。 这可能是一个 docker 映像或 Jenkins 节点。 使用`--no-docker`标记，以获取您刚刚安装的插件。

#### 与当地发电

创建一个新的 docker 映像，扩展[spotify/techdocs](https://github.com/backstage/techdocs-container)大致是这样：

```Dockerfile
FROM spotify/techdocs:<version>

pip install <the_plugin_you_want>
...

然后发布图像，并在配置中的techdocs.generator.dockerImage密钥.

在 mkdocs 配置中指定插件

要使用该插件，必须在mkdocs.yaml您可以将插件添加到适用文件中，也可以指定默认值。

要让所有 TechDocs 组件都能使用 mkdocs 插件，您可以将其列在techdocs.generator.mkdocs.defaultPlugins配置或使用--defaultPlugincli选项取决于您的设置。

参考其他组件 TechDocs

在系统中，您可能会有多个实体，例如一个带有网站和应用程序接口的系统，当从 Monorepo 提供服务时，您可能希望将 TechDocs 保存在资源库中的一个位置。

在这种情况下，您可以添加backstage.io/techdocs-entity注释，并指向 OwnersentityRef这样，子组件就可以读取父组件的文档，并将技术文档链接填写在AboutCard元素和技术文档选项卡

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: example
  namespace: default
  title: Example
  description: This is the parent entity
  annotations:
    backstage.io/techdocs-ref: dir:.

---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: example-platfrom
  title: Example Application Platform
  namespace: default
  description: This is the child entity
  annotations:
    backstage.io/techdocs-entity: system:default/example

如何从 TechDocs Basic 迁移到推荐部署方法？​

1.准备云存储​

2.从 CI/CD 发布到存储​

将 TechDocs 切换为只读模式​

如何理解 techdocs-ref 注释值​

为什么 URL 阅读器比 git 克隆更快？​

如何自定义 TechDocs 主页？​

使用 TechDocsCustomHome​

建立自定义主页​

如何自定义 TechDocs 阅读器页面？​

如何从 TechDocs Alpha 版迁移到 Beta 版​

如何实现自己的 TechDocs API​

如何在软件模板中添加文档设置​

防止下载谷歌字体​

如何在 TechDocs 中启用 iframe​

如何在 TechDocs 中呈现 PlantUML 图表​

UML 图表详情：-​

嵌入式 PlantUML 图例​

在 mkdocs 配置中指定插件​

参考其他组件 TechDocs​