创建知识库

在 Mintlify 上托管团队内部知识库，以整合信息、提升搜索效果，并降低维护成本。

内部知识库可以帮助你的团队快速找到答案，并维护统一的权威信息源（source of truth）。如果团队信息分散在不同渠道和平台上，人们在搜索答案时往往会找到不准确的信息，甚至找不到信息。通过将答案集中到一个所有人都能访问的地方，并为团队提供一个专门记录共享知识的空间，集中式知识库可以解决这一问题。

Mintlify 提供搭建知识库的基础设施，让整个团队都能参与贡献。

• AI 驱动搜索：通过 AI 助手 使用你的知识库内容来回答问题，让用户即使不知道去哪找，也能找到答案。
• Slack 集成：将 AI 助手添加到 Slack，这样你的团队就可以在不离开工作流程的情况下提问。
• 低门槛贡献：使用 web editor 和 agent，团队中的任何人都可以在不学习 Git 或 Markdown 的前提下更新内容。
• 内置认证：通过 SSO 或 OAuth 控制访问，并使用 个性化 为不同用户组展示不同的内容。

​

先决条件

如果你尚未创建 Mintlify 项目，请参阅 快速开始 来部署你的站点。

• 一个认证系统（如 Okta 或 Azure AD 之类的 SSO 或 OAuth 提供方）
• 对用于托管的域名拥有控制权
• 拥有你在 Mintlify 组织中的管理员权限

​

迁移现有内容

如果你是从头开始创建知识库，可以直接跳转到设计导航结构。

​

审核现有内容

对你当前知识库中的内容进行盘点和整理。这样可以帮助你了解需要迁移哪些内容、规划如何在新的知识库中组织这些内容、识别内容中的空白，并确认你已经将所有内容迁移到新的知识库中。

• 文章总数：帮助评估迁移工作量并跟踪完成度。
• 主题和内容：为你的导航结构和内容组织方式提供依据。
• 当前组织方式：查看你的内容目前是如何组织的，以及它是否符合你期望的结构。
• 内容类型：确定文本、PDF、视频和嵌入式内容是否有任何格式转换需求。
• metadata：识别需要保留的任何 metadata，例如日期、作者和标签。
• 访问要求：为你的知识库确定最佳的认证方式。

​

导出你现有的内容

大多数知识库平台都支持以标准格式导出内容。你选择的格式取决于当前使用的平台以及你的侧重点。

• 导出为 Markdown，这是迁移到 Mintlify 的最简方式。（推荐）
• 如果 Markdown 不可用，则导出为 HTML。之后你必须将内容转换为 Markdown。
• 如果你有需要保留的结构化 metadata，则导出为 JSON 或 CSV。

​

设计导航结构

你的导航结构决定了人们如何在知识库中查找内容。你可以沿用现有结构，或者重新设计，使其更好地符合你团队对内容的思考方式。

迁移是优化结构的好时机。思考一下你当前的组织方式是否真正适合你的团队，或者是否可以通过重新组织来让信息更容易被找到。

你的 docs.json 文件定义了知识库的导航结构。请在项目存储库的根目录下创建这个文件。

{
  "navigation": {
    "groups": [
      {
        "group": "Finance",
        "pages": [
            "finance/overview",
            "finance/budgeting-process",
            "finance/expense-reports",
            "finance/cost-allocation"
        ]
      },
      {
        "group": "HR",
        "pages": [
            "hr/overview",
            "hr/onboarding",
            "hr/benefits",
            "hr/time-off-policy"
        ]
      },
      {
        "group": "工程",
        "pages": [
          "engineering/overview",
          "engineering/dev-setup",
          "engineering/deployment",
          "engineering/code-standards"
        ]
      }
    ]
  }
}

关于如何组织你的知识库结构的更多信息，请参阅导航。

​

设置认证

确定在你的知识库中，哪些人需要访问哪些内容。

如果所有人都应该访问整个知识库，则只需设置认证。

如果你需要将某些内容的访问权限限制为特定用户或 groups，则需要同时设置认证和个性化。

​

迁移你的内容

将导出的内容移动到与你设计的导航结构相匹配的文件夹层级中。如有需要，将内容转换为 Markdown，补充缺失的 frontmatter，并设置内部链接。

1. 整理文件

   创建与 docs.json 结构相匹配的文件夹。例如，如果你的 docs.json 中有名为 Finance 的分组，则创建一个 finance/ 文件夹：

   your-project/
   ├── docs.json
   ├── finance/
   │   ├── overview.mdx
   │   ├── budgeting-process.mdx
   │   ├── expense-reports.mdx
   │   └── cost-allocation.mdx
   ├── hr/
   │   ├── overview.mdx
   │   ├── onboarding.mdx
   │   ├── benefits.mdx
   │   └── time-off-policy.mdx
   └── engineering/
       ├── overview.mdx
       ├── dev-setup.mdx
       ├── deployment.mdx
       └── code-standards.mdx
   

   将每篇文章放入其对应的文件夹中。文件路径必须与 docs.json 中的路径一致。例如，如果 docs.json 中引用的是 "finance/expense-reports"，则项目存储库中的文件应为 finance/expense-reports.mdx。

2. 为每篇文章添加 frontmatter

   每个 .mdx 文件在顶部都需要包含带有 metadata 的 frontmatter。每个页面都需要有一个 title 和 description。有关页面 metadata 的更多信息，请参见 Pages。

   ---
   title: "Expense Report Process"
   description: "How to submit and track expense reports"
   ---
   
   Your content here...
   
3. 设置内部链接

   使用从项目根目录开始的路径在页面之间创建链接。

   See [Onboarding Guide](/hr/onboarding) for new employee setup.
   
   For questions, contact [HR Benefits Team](/hr/benefits#common-questions).
   
4. 将 HTML 和其他格式转换为 Markdown

   如果你将内容导出为 HTML，请将其转换为 Markdown。可以使用的一些工具包括：

   • Pandoc：命令行工具，可在多种格式之间进行转换。
   • CloudConvert：在线转换工具，支持 HTML、DOCX、PDF 等多种格式。
   • VS Code extensions：在扩展中搜索 “HTML to Markdown”。
5. 处理多种内容格式

   如果你有 PDF、视频或其他媒体，请决定如何将它们纳入你的知识库。

   • 嵌入视频：嵌入视频或链接到托管的视频。
   • 链接到 PDF：将 PDF 添加到你的项目存储库，并从相关页面链接到它们。
   • 将 PDF 转换为 Markdown：如果你希望 PDF 的内容成为一个页面，请将 PDF 转换为 Markdown。

​

设置 AI 助手

AI 助手会自动为 Pro 和 Custom 套餐启用。AI 助手让你的团队可以提问，并从你的知识库中获取附带引用来源的回答。

在控制台中配置 AI 助手：

• 示例问题：添加常见问题，如 “how do I submit an expense report” 或 “what is the vacation policy”，这样用户就可以一键获取答案。
• 搜索站点：添加 AI 助手在回答问题时可以搜索的其他站点。
• 分流邮箱：为 AI 助手无法解答的问题设置一个支持邮箱地址。

​

将 AI 助手添加到 Slack

Slack 机器人 让你的团队无需离开 Slack 就能向 AI 助手提问。你可以创建一个频道，让机器人回复其中的每一条消息，或者让团队成员在任意频道中通过 @ 提及该机器人来获取回复。

​

启用团队共建

只有当不只是最初搭建的人，而是所有人都能参与更新时，知识库才能保持准确。Mintlify 为团队成员提供三种方式，帮助他们快速参与维护你的知识库。

​

Web editor

Web editor 允许任何人在浏览器中创建和编辑页面。贡献者可以：

• 通过可视化界面或使用 Markdown 编辑页面。
• 通过拖放操作重新组织导航。
• 上传图片和媒体文件。
• 创建 branch 并发起拉取请求（PR；亦称“合并请求”/Merge Request）以供审核。

这非常适合那些了解内容但不熟悉代码工作流的领域专家使用。

​

Agent

控制台中的 agent 可以根据自然语言提示生成文档更新。描述你想要修改的内容，agent 会创建包含这些更新的拉取请求（PR；亦称“合并请求”/Merge Request）。

例如，某个团队成员可以输入提示：“在报销政策页面中添加一个部分，说明如何提交超过 50 美元餐饮费用的收据”，并将现有的报销政策页面复制到提示中。agent 会起草内容并打开一个 PR 供审核。

​

本地

任何有权访问你的知识库存储库的人都可以在其偏好的本地编辑器中工作，并将更改推送到你的存储库。

​

建立维护工作流程

如果不进行维护，知识库会很快变得陈旧。建立机制来保持内容实时更新，并帮助你的团队持续为知识库做出贡献。

1. 指定内容所有者

   为每个部分指定一个负责人或一个小团队。他们不必亲自撰写所有内容，但需要负责：

   • 定期审查内容。
   • 标记过时的信息。
   • 审批其所属部分的新页面。
   • 在有人报告错误时做出回应。
2. 设置审查周期和内容验证

   内容会随着时间变得陈旧。制定一个审查计划。

   • 关键内容：每 30 天审查一次
   • 标准内容：每 90 天审查一次
   • 常青内容：每年审查一次

   在审查时，检查：

   • 链接是否仍然有效？
   • 系统或流程是否发生了变化？
   • 示例是否是最新的？
   • 是否有需要补充的新信息？
3. 制定贡献指南

   让任何人都能轻松改进知识库。你的指南应涵盖：

   • 格式：你是否有特定的模板或格式要求？
   • 流程：他人应如何提出并提交更改？
   • 审查：由谁来审查提交？处理周期是多少？
   • 范围：哪些类型的内容属于覆盖范围？
4. 监控使用指标

   审查你的团队如何使用知识库，以便为内容排定优先级并识别可改进的领域。为审查使用指标设定一个固定节奏——按月或按季度都是不错的间隔。

   • 哪些文章浏览量最高？优先投入精力保持这些内容准确且易于阅读。
   • 哪些文章完全没有浏览量？考虑删除它们或改进其可发现性。
   • 跳出率是多少？如果用户立即离开，说明内容可能不够有用，或者导航还有改进空间。

​

后续步骤

你的知识库已经可以上线了。部署完成后：

1. 向团队发布知识库。
2. 在 Analytics 中监控使用情况和搜索模式。
3. 当人们发现内容缺口时，鼓励他们参与补充。
4. 定期审查并更新内容。

最成功的知识库都会根据团队的实际使用方式不断演进。