${{ 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.

这样你的用户每次通过模板创建组件，就能自动获得一个开箱即用的 TechDocs 站点。

### 方式二：为已有实体启用文档

前置条件：实体已经注册到软件目录（可通过 `catalog-info.yaml` 等任一方式注册，参见[软件目录使用指南](https://gitcode.com/GitHub_Trending/ba/backstage/blob/ed1c5013baaa001f25837c58c4acd849f538346a/docs/features/software-catalog/index.md?utm_source=gitcode_repo_files)）。

按以下五步为已有实体添加文档：

**第 1 步：在仓库根目录创建 `mkdocs.yml`**

```yaml
site_name: 'example-docs'

nav:
  - Home: index.md

plugins:
  - techdocs-core

注意：plugins 一节是可选的。如果 mkdocs.yml 中没有声明插件，Backstage 会自动把 techdocs-core 插件加进去；该行为可以通过 TechDocs 配置 中的 techdocs.generator.mkdocs.omitTechdocsCorePlugin 关闭。

第 2 步：在 catalog-info.yaml 中声明 backstage.io/techdocs-ref 注解

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

backstage.io/techdocs-ref 注解 告诉 TechDocs 从哪里下载文档源文件，用于生成实体的 TechDocs 站点。它最常见的写法是一个相对 catalog-info.yaml 所在位置的路径，指向 mkdocs.yml 所在目录（详见下文"注解深入解析"）。

第 3 步：在仓库根目录创建 docs 文件夹，并至少放入一个 index.md

如果你新增了更多 Markdown 文件，记得同步更新 mkdocs.yml 中的 nav，才能生成正确的导航。

说明：docs 只是文档目录的常用名称，完全可以改名，并在 mkdocs.yml 中用 docs_dir 指定（详见 MkDocs 官方配置文档中关于 docs_dir 的说明）。

第 4 步：创建 docs/index.md，例如

# example docs

This is a basic example of documentation.

第 5 步：提交、开 PR、合并

完成后，下次运行 Backstage 就能看到更新后的文档了。

仓库中的 documented-component 示例 就是一个标准范例：它的 catalog-info.yaml 声明了 backstage.io/techdocs-ref: dir:.，mkdocs.yml 定义了包含多级子页面（Subpage、Code Sample、Deeper Nav 等）的完整导航，可以直接作为你搭建文档结构的参照。

方式三：创建独立文档组件

有些场景下你希望文档不紧贴代码存放，但仍要发布出来——例如新人入职教程（onboarding tutorial）。此时可以创建一个 type: documentation 的文档组件，作为 TechDocs 的独立部分发布。

第 1 步：创建文档实体

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: a-unique-name-for-your-docs
  annotations:
    # 如果文档不在同一位置，也可以写成 `url:<url>`
    backstage.io/techdocs-ref: dir:.
spec:
  type: documentation
  lifecycle: experimental
  owner: user-or-team-name

第 2 步：创建 mkdocs 配置文件

site_name: a-unique-name-for-your-docs
site_description: An informative description
plugins:
  - techdocs-core
nav:
  - Getting Started: index.md

第 3 步：在 docs/ 目录中添加 index.md 及你想要的 Markdown 文档

最终目录结构：

your-great-documentation/
  docs/
    index.md
  catalog-info.yaml
  mkdocs.yml

第 4 步：用任一方式把组件注册到软件目录（参见软件目录使用指南）。

深入解析 backstage.io/techdocs-ref 注解

这个注解是 TechDocs 获取文档源文件的关键，理解它的取值规则能帮你避免大量"文档不显示"的问题。

dir: 前缀：文档与代码同仓（强烈推荐）

TechDocs 与"文档即代码"理念对齐，因此几乎所有场景下都推荐把注解设置为 dir:.。看到 dir:.，它的含义是：

• 文档源码与 catalog-info.yaml 位于同一位置；
• 特别是 mkdocs.yml 与 catalog-info.yaml 在同一目录（互为同级文件）；
• 下载包含这两个文件及其所有子目录的目录，即可获得文档的全部源内容。

目录树形态：

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

如果你希望保持根目录精简，可以把 mkdocs.yml 放到子目录，并把注解改为 dir:./sub-folder：

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

url: 前缀：文档与代码分离（少数场景）

在极少数文档源内容与 catalog-info.yaml 完全分离的场景下，可以改用 url: 前缀，指向源码托管平台上的具体位置，各平台的典型写法（<branch_name> 替换为实际分支）：

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

与 dir: 一样，url: 也可以指向仓库内非根目录（即包含 mkdocs.yml 与 docs/ 的目录）。注意目录路径需要以 / 结尾，以保证相对路径解析的一致性。

为什么 URL Reader 比 git clone 更快？

URL Reader 使用源码托管平台的 API 直接下载仓库的 zip/tarball 归档，归档不带任何 git 历史且经过压缩，因此传输的数据量远小于 git clone 需要拉取的内容，是 TechDocs 的 Preparer 阶段 中推荐使用的下载方式。

编写与预览文档：使用 techdocs-cli serve

techdocs-cli（位于 packages/techdocs-cli）可以让你在本地 Backstage 实例中预览文档，并对改动实时热重载，非常适合边写边看。

在文档仓库目录下运行：

cd /path/to/docs-repository/
npx @techdocs/cli serve

关于 serve 命令的要点：

• 默认使用 Docker 与 techdocs-container 来保证所有依赖就绪；可用 --no-docker 关闭，改用本机 mkdocs 可执行文件。
• 该命令会启动两个本地服务：MkDocs 预览服务（默认端口 8000）和一个 Backstage 应用服务（默认端口 3000）。Backstage 应用内置了自定义 TechDocs API 实现，把 MkDocs 预览服务当作代理来获取生成的文档文件与静态资源。
• serve 命令不会主动拉取 Docker 镜像，而是使用本地已有的镜像。如果预览异常（例如文档改动不再被检测到），执行 docker pull spotify/techdocs 更新镜像即可。
• 内置预览应用可能与你的实际 Backstage 外观/行为不同，可用 --preview-app-bundle-path 指向你自己的应用 bundle（通常是 dist 或 build 目录）。
• 若使用自定义 techdocs Docker 镜像，请确保其入口是 ENTRYPOINT ["mkdocs"]，或用 --docker-entrypoint 覆盖。

常用命令参数：

Usage: techdocs-cli serve [options]

Options:
  -i, --docker-image <DOCKER_IMAGE>          要使用的 mkdocs docker 容器 (默认: "spotify/techdocs")
  --docker-entrypoint <DOCKER_ENTRYPOINT>    覆盖镜像入口
  --docker-option <DOCKER_OPTION...>         向 docker run 传递额外选项，如 "--add-host=internal.host:192.168.11.12"（可多次添加）
  --no-docker                                不使用 Docker，改用当前环境中的 MkDocs 可执行文件
  --mkdocs-parameter-clean                   向容器内的 mkdocs server 传递 "--clean" 参数
  --mkdocs-parameter-dirtyreload             向容器内的 mkdocs server 传递 "--dirtyreload" 参数
  --mkdocs-parameter-strict                  向容器内的 mkdocs server 传递 "--strict" 参数
  --mkdocs-port <PORT>                       MkDocs 服务端口 (默认: "8000")
  --preview-app-bundle-path <PATH_TO_BUNDLE> 使用其他 web 应用预览文档
  --preview-app-port <PORT>                  预览服务端口，仅与 "--preview-app-bundle-path" 联用 (默认: "3000")
  -c, --mkdocs-config-file-name <FILENAME>   mkdocs 使用的配置文件
  -v --verbose                               输出详细日志 (默认: false)

完整的 CLI 命令参考（generate、publish、migrate 等）见 TechDocs CLI 文档。

生成与发布链路：Preparer、Generator 与 Publisher

要深入理解"创建文档"背后的机制，需要知道 TechDocs 生成一个站点要经历三个阶段（详见 concepts.md）：

1. TechDocs Preparer（准备器）：第一步。根据 backstage.io/techdocs-ref 注解从源码托管平台（GitHub、GitLab 等）拉取 Markdown 源文件，交给生成器。有两种实现：
   • Common Git Preparer：对任意仓库 URL 执行 git clone；
   • URL Reader：调用托管平台 API 下载文件（更快，推荐）。
2. TechDocs Generator（生成器）：第二步。运行 techdocs-container（Docker）或本机 mkdocs CLI，把 Markdown 源文件生成静态 HTML 及资源文件。techdocs.generator.runIn 决定走 Docker 还是本地。
3. TechDocs Publisher（发布器）：第三步。把生成的静态文件上传到存储。techdocs.publisher.type 决定存储位置（本地文件系统、GCS、S3 等）。发布器同时负责：① 把生成的静态文件写入存储（由 techdocs.builder 配置驱动）；② 用户访问 TechDocs 站点时从存储读取文件。

Build Strategy（构建策略）

techdocs.builder 的默认行为是：设为 'local' 时，techdocs-backend 在本地构建文档；否则跳过构建。但 TechDocs 后端支持实现自定义的 Build Strategy 接口，按实体粒度决定"该实体文档由本地构建、外部进程构建、还是两者混合构建"——这就是混合构建策略（hybrid build strategy） 的实现基础。

三种核心配置项

默认情况下，getting-started.md 给出的基础配置如下（完整的配置参考见 TechDocs 配置文档）：

techdocs:
  builder: 'local' # Alternatives - 'external'
  generator:
    runIn: 'docker' # Alternatives - 'local'
  publisher:
    type: 'local' # Alternatives include 'googleGcs', 'awsS3', and other supported publishers