入门

TechDocs 作为 Backstage 的插件运行，因此您需要使用 Backstage 才能使用 TechDocs。

如果您还没有设置Backstage，请启动这里.

如果您使用了 npx @backstage/create-app, TechDocs 可能已经存在。 > > 您应该跳到下面的 设置配置 >。

添加 TechDocs 前端插件

第一步是将 TechDocs 插件添加到您的 Backstage 应用程序中。导航到您的新 Backstage 应用程序目录。然后导航到您的packages/app目录，并安装@backstage/plugin-techdocs包装

# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-techdocs

安装软件包后，您需要在应用程序中导入插件。

在packages/app/src/App.tsx进口TechDocsPage并在FlatRoutes:

packages/app/src/App.tsx
import {
  DefaultTechDocsHome,
  TechDocsIndexPage,
  TechDocsReaderPage,
} from '@backstage/plugin-techdocs';

const AppRoutes = () => {
  <FlatRoutes>
    {/* ... other plugin routes */}
    <Route path="/docs" element={<TechDocsIndexPage />}>
      <DefaultTechDocsHome />
    </Route>
    <Route
      path="/docs/:namespace/:kind/:name/*"
      element={<TechDocsReaderPage />}
    />
  </FlatRoutes>;
};

如果能用其他东西来装饰您的页面就更好了......当您突出显示文档中的文本时，如果有一个链接能将您重定向到新的问题页面，那就太酷了，不是吗？让我们来学习如何使用 TechDocs 附加组件框架来实现这一点！

随着TechDocs 附加组件框架，你可以在文档页面中渲染 React 组件，这些插件可以由任何 Backstage 插件提供。该框架由导出的@backstage/plugin-techdocs-react软件包，并且有一个<ReportIssue />在@backstage/plugin-techdocs-module-addons-contrib软件包，安装好这两个依赖项后即可使用：

import {
  DefaultTechDocsHome,
  TechDocsIndexPage,
  TechDocsReaderPage,
} from '@backstage/plugin-techdocs';
import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib';

const AppRoutes = () => {
  <FlatRoutes>
    {/* ... other plugin routes */}
    <Route path="/docs" element={<TechDocsIndexPage />}>
      <DefaultTechDocsHome />
    </Route>
    <Route
      path="/docs/:namespace/:kind/:name/*"
      element={<TechDocsReaderPage />}
    >
      <TechDocsAddons>
        <ReportIssue />
      </TechDocsAddons>
    </Route>
  </FlatRoutes>;
};

我知道，你很想看看它的样子，对吧？请看下图：

TechDocs Report Issue Add-on

单击 "打开新问题 "按钮，您将根据所使用的源代码提供商被重定向到新问题页面：

TechDocs Report Issue Template

就是这样！现在，我们需要 TechDocs 后端插件才能让前端正常工作。

添加 TechDocs 后端插件

导航至packages/backend的 Backstage 应用程序，并安装@backstage/plugin-techdocs-backend包装

# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-techdocs-backend

创建一个名为techdocs.ts内侧packages/backend/src/plugins/并添加以下内容

import { DockerContainerRunner } from '@backstage/backend-common';
import {
  createRouter,
  Generators,
  Preparers,
  Publisher,
} from '@backstage/plugin-techdocs-backend';
import Docker from 'dockerode';
import { Router } from 'express';
import { PluginEnvironment } from '../types';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  // Preparers are responsible for fetching source files for documentation.
  const preparers = await Preparers.fromConfig(env.config, {
    logger: env.logger,
    reader: env.reader,
  });

  // Docker client (conditionally) used by the generators, based on techdocs.generators config.
  const dockerClient = new Docker();
  const containerRunner = new DockerContainerRunner({ dockerClient });

  // Generators are used for generating documentation sites.
  const generators = await Generators.fromConfig(env.config, {
    logger: env.logger,
    containerRunner,
  });

  // Publisher is used for
  // 1. Publishing generated files to storage
  // 2. Fetching files from storage and passing them to TechDocs frontend.
  const publisher = await Publisher.fromConfig(env.config, {
    logger: env.logger,
    discovery: env.discovery,
  });

  // checks if the publisher is working and logs the result
  await publisher.getReadiness();

  return await createRouter({
    preparers,
    generators,
    publisher,
    logger: env.logger,
    config: env.config,
    discovery: env.discovery,
    cache: env.cache,
  });
}

您可能需要安装dockerode但您可能已经在后端安装了该软件包，因为Scaffolder 插件也使用它。

参见概念和技术文档架构了解更多关于制片人、生成器和出版商如何工作的信息。

最后一步是在 Backstage 应用程序后端导入 techdocs 后端插件。将以下内容添加到您的packages/backend/src/index.ts:

import techdocs from './plugins/techdocs';

// .... main should already be present.
async function main() {
  // ... other backend plugin envs
  const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs'));

  // ... other backend plugin routes
  apiRouter.use('/techdocs', await techdocs(techdocsEnv));
}

就是这样！TechDocs 的前端和后端现已添加到您的 Backstage 应用程序中。现在，让我们根据您的需要调整一些配置。

设置配置

**完整的配置参考请参见 TechDocs 配置选项。

TechDocs 后端应该生成文档吗？

techdocs:
  builder: 'local'

请注意，我们建议在 CI/CD 上生成文档。请在本章的 "基本 "和 "推荐 "部分阅读更多内容。技术文档架构但是，如果您想尽快开始设置techdocs.builder至'local'以便 TechDocs 后端负责生成文档站点。如果设置为'external'因此，Backstage 会假定这些网站是在每个实体的 CI/CD 管道上生成的，并存储在某个存储空间中。

何时techdocs.builder设置为'external'在这种情况下，TechDocs 或多或少会成为一种只读体验，它从包含所有已生成文档的存储中提供静态文件。

选择存储(出版商)

TechDocs 需要知道在哪里存储生成的文档站点，以及从哪里获取这些站点。出版商例如：谷歌云存储、亚马逊 S3 或 Backstage 服务器的本地文件系统。

在初次试用 Backstage 时，可以在 "基本 "设置中使用本地文件系统。以后，请查看使用云存储.

techdocs:
  builder: 'local'
  publisher:
    type: 'local'

在 Docker 情况下禁用 Docker(可选)

如果您的techdocs.builder设置为'external'.

TechDocs 后端插件会运行一个安装了 mkdocs 的 docker 容器，以便从源文件(Markdown)生成文档前端。如果你使用 Docker 部署后端，这将意味着你的后端 Docker 容器会尝试运行另一个用于 TechDocs 后端的 Docker 容器。

为了避免这个问题，我们提供了一个配置。app-config.yaml告诉技术文档生成器是否应该运行localmkdocs 或从docker默认以docker如果没有提供配置

techdocs:
  builder: 'local'
  publisher:
    type: 'local'
  generator:
    runIn: local

设置generator.runIn至local这意味着您必须确保您的环境与 techdocs 兼容。

您必须安装mkdocs和mkdocs-techdocs-core软件包，也可选择graphviz和plantuml从操作系统软件包管理器(如 apt)中运行。

您可以在正上方加入以下几行字USER node你的Dockerfile:

RUN apt-get update && apt-get install -y python3 python3-pip python3-venv

ENV VIRTUAL_ENV=/opt/venv
RUN python3 -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

RUN pip3 install mkdocs-techdocs-core

请注意，版本要求可能会更改，您需要查看我们的Docker文件并确保与之匹配。

在基于 Debian 的 Docker 容器上，Python 软件包必须使用操作系统软件包管理器或在虚拟环境中安装(参见相关 PEP另一种方法是使用例如pipx用于在隔离环境中安装 Python 软件包。

上述 Dockerfile 代码段安装了最新的mkdocs-techdoc-core版本号可在相应的更新日志如果您想固定版本，请使用下面的示例：

RUN pip3 install mkdocs-techdocs-core==1.2.3

注意：我们建议使用 Python 3.11 或更高版本。

注意事项：请在安装所有其他 Python 软件包之后再安装 mkdocs-techdocs-core 软件包。这个顺序很重要，可以确保我们得到一些依赖项的正确版本。

补充阅读

创建和发布文档](creation-and-publishing.md) * 返回 README

添加 TechDocs 前端插件​

添加 TechDocs 后端插件​

设置配置​

TechDocs 后端应该生成文档吗？​

选择存储(出版商)​

在 Docker 情况下禁用 Docker(可选)​

补充阅读​