为Backstage注入活力！TechDocs完整安装及Yarn Workspace设置指南

大家好！今天，我们将详细探讨如何安装TechDocs（技术文档），它是Backstage的核心功能之一，也被誉为开发者体验（DevEx）的瑰宝。🚀

在构建新的Backstage Monorepo之后，当您尝试添加TechDocs以实现“文档即代码（Documentation as Code）”管理时，是否曾困惑于应该输入哪些命令以及按什么顺序？我们在此发布在Yarn Workspace环境中完美安装前端和后端包的“官方指南”！💡

---

🏗️ 为什么TechDocs安装要采用Yarn Workspace方式？

Backstage从根本上采用了Monorepo（单体仓库）结构。由于前端（packages/app）和后端（packages/backend）是分离的，因此在添加新功能时，需要分别为每个包的领域安装相应的库。

此时，使用Yarn Workspaces功能，您可以轻松管理安装，而无需从根目录导航到每个子包。🛠️

---

🌟 TechDocs安装的“黄金命令”顺序

要启用TechDocs，您需要同时安装前端插件和后端插件。

第一步：安装前端包 (app) 🎨

首先，安装用于构建用户阅读文档的UI界面的包。

Bash

yarn workspace app add @backstage/plugin-techdocs

• 含义: 将TechDocs前端库添加到名为’app’的工作区（packages/app）。

第二步：安装后端包 (backend) ⚙️

接下来，安装负责处理、生成和提供文档数据的后端包。

Bash

yarn workspace backend add @backstage/plugin-techdocs-backend

• 含义: 将TechDocs后端处理逻辑添加到名为’backend’的工作区（packages/backend）。

---

🔍 安装后需要做什么？（附加设置指南）

仅仅安装了包并不意味着文档会立即出现！还需要进行一些代码连接工作。🕵️‍♂️

🛠️ 前端连接 (packages/app/src/App.tsx)

您需要将安装的@backstage/plugin-techdocs注册到应用程序的路由中。

TypeScript

// App.tsx内部示例
import { TechdocsPage } from '@backstage/plugin-techdocs';

// ... 路由定义部分
<Route path="/docs" element={<TechdocsPage />} />

🛠️ 后端连接 (packages/backend/src/plugins/techdocs.ts)

在最新的Backstage版本中，通常使用New Backend System。在这种情况下，只需在index.ts文件中添加以下一行即可。

TypeScript

// packages/backend/src/index.ts
backend.add(import('@backstage/plugin-techdocs-backend/alpha'));

---

💡 实战技巧：理解TechDocs的工作原理

TechDocs内部使用名为MkDocs的静态网站生成器。📖

1. Preparation: 从源代码仓库抓取Markdown文件。
2. Generation: 运行MkDocs将其转换为HTML。
3. Storage: 将转换后的HTML存储到S3、GCS或本地文件系统。
4. Visualization: Backstage UI（前端）加载这些存储的内容并展示给用户。

请记住，为了使此过程顺利进行，您的本地环境中必须安装Python和mkdocs-techdocs-core包！🐍

---

🏁 结论：整洁的安装是良好维护的开始！

在Backstage Monorepo中添加TechDocs时，请记住以下命令：

1. yarn workspace app add @backstage/plugin-techdocs 🎨
2. yarn workspace backend add @backstage/plugin-techdocs-backend ⚙️

通过这两个步骤，您的团队将向真正的DevOps文化迈进一大步，在同一个地方管理代码和文档！🚀

---