Skip to main content

创建和发布文档

本节将指导您如何

先决条件​

  • 已安装 TechDocs 的工作 Backstage 实例(请参阅 TechDocs 入门)。

创建基本文件设置​

如果您有一个想要添加文档的现有版本库，请跳至为已存在的实体设置启用文档否则，请继续阅读，从头开始创建包括文档在内的新软件实体。

使用任何软件模板​

TechDocs 建立在像编写代码一样编写文档简而言之，这意味着您应该让文档与代码保持紧密联系。

您的 Backstage 应用程序默认添加了一套软件模板。 所有这些软件模板都包含了您启动和运行 TechDocs 网站以及开始编写文档所需的一切。

如果您创建的软件模板默认不包含文档，我们强烈建议您进行设置。 请遵循我们的操作指南如何在软件模板中添加文档设置开始。

启用已存在实体的文档​

先决条件

  • [在Backstage注册的]现有实体(../software-catalog/index.md#adding-components-to-the-catalog)(例如通过 catalog-info.yaml 文件)。

创建一个mkdocs.yml文件，内容如下：

site_name: 'example-docs'

nav:
  - Home: index.md

plugins:
  - techdocs-core

注意 - 上述插件部分是可选的。 如果缺少 techdocs-core 插件，Backstage 会自动将其添加到 > mkdocs 文件中。 该功能可以通过 Backstage 中的 配置选项关闭。

更新组件的实体描述，在其catalog-info.yaml在其存储库的根目录中：

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

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

创建一个/docs文件夹中至少有一个index.md文件。如果您添加了更多标记符文件，请确保更新 mkdocs.yml 文件中的导航，以便为您的文档提供正确的导航)__(如果您添加了更多标记符文件，请确保更新 mkdocs.yml 文件中的导航，以便为您的文档提供正确的导航。

注意 - 虽然 docs 是一个常用的文档存储目录名， > 但它也可以重命名为其他名称，并可通过 mkdocs.yml 进行配置。 参见 > https://www.mkdocs.org/user-guide/configuration/#docs_dir

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

# example docs

This is a basic example of documentation.

提交更改，打开拉取请求并合并。 下次运行 Backstage 时，你就能获得更新后的文档了！

创建独立文档​

可能有有些在这种情况下，您可以创建一个文档组件，它将作为 TechDocs 的独立部分发布。

首先，为文档创建一个实体。 一个最简单的例子可以是这样的：

catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: a-unique-name-for-your-docs
  annotations:
    # this could also be `url:<url>` if the documentation isn't in the same location
    backstage.io/techdocs-ref: dir:.
spec:
  type: documentation
  lifecycle: experimental
  owner: user-or-team-name

接下来，为mkdocs，它将用于解析您的文档：

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

最后，在名为docs/文件结构现在应该是这样的：

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

最后但并非最不重要的一点是，使用以下方法在软件目录中注册组件选择之一.

撰写和预览文档​

使用技术文档-客户端当你想在撰写文档时预览文档时，这个功能非常有用。

为此，您可以运行

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