跳转到主要内容

​
简介

本指南将介绍如何在 Mintlify 上创建内部知识库。你将设置导航结构、迁移内容、配置认证，并建立维护流程。 本指南假设你正在将现有知识库中的内容迁移到 Mintlify。如果你是从零开始创建一个全新的知识库，可以遵循类似步骤，但可以跳过梳理和迁移这两个步骤。 如果你还没有创建 Mintlify 项目，请参阅 快速开始 来部署你的网站。

​
先决条件

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

​
审核现有内容

对你当前知识库中的内容进行盘点和整理。这样可以帮助你了解需要迁移哪些内容、规划如何在新的知识库中组织这些内容、识别内容中的空白，并确认你已经将所有内容迁移到新的知识库中。
  • 文章总数：帮助评估迁移工作量并跟踪完成度。
  • 主题和内容：为你的导航结构和内容组织方式提供依据。
  • 当前组织方式：查看你的内容目前是如何组织的，以及它是否符合你期望的结构。
  • 内容类型：确定文本、PDF、视频和嵌入式内容是否有任何格式转换需求。
  • metadata：识别需要保留的任何 metadata，例如日期、作者和标签。
  • 访问要求：为你的知识库确定最佳的认证方式。

​
导出你现有的内容

大多数知识库平台都支持以标准格式导出内容。你选择的格式取决于当前使用的平台以及你的侧重点。
  • 导出为 Markdown，这是迁移到 Mintlify 的最简方式。（推荐）
  • 如果 Markdown 不可用，则导出为 HTML。之后你必须将内容转换为 Markdown。
  • 如果你有需要保留的结构化 metadata，则导出为 JSON 或 CSV。

​
设计导航结构

你的导航结构决定了人们如何在知识库中查找内容。你可以沿用现有结构，或者重新设计，使其更好地符合你团队对内容的思考方式。
迁移是优化结构的好时机。思考一下你当前的组织方式是否真正适合你的团队，或者是否可以通过重新组织来让信息更容易被找到。
你的 docs.json 文件定义了知识库的组织方式。请在项目存储库的根目录下创建这个文件。 
{
  "navigation": {
    "groups": [
      {
        "group": "财务",
        "pages": [
            "finance/overview",
            "finance/budgeting-process",
            "finance/expense-reports",
            "finance/cost-allocation"
        ]
      },
      {
        "group": "人力资源",
        "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 方案中自动启用。你可以在控制台中自定义该助手。
  • 搜索网站：选择除你的知识库之外，助手在回答问题时可以搜索的其他网站。
  • 设置示例问题：设置当有人打开助手面板时显示的默认问题。如果人们经常会问诸如“how do I submit an expense report”或“what is the company’s vacation policy”之类的问题，可以在这里添加它们，以节省大家的时间。

​
Slack 集成

如果你的团队使用 Slack，你可以将 Slack 应用 添加到工作区。这样，团队成员就可以在不离开 Slack 的情况下查询你的知识库。

​
建立维护工作流程

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

指定内容所有者

为每个部分指定一个负责人或一个小团队。他们不必亲自撰写所有内容，但需要负责：
  • 定期审查内容。
  • 标记过时的信息。
  • 审批其所属部分的新页面。
  • 在有人报告错误时做出回应。
2

设置审查周期和内容验证

内容会随着时间变得陈旧。制定一个审查计划。
  • 关键内容：每 30 天审查一次
  • 标准内容：每 90 天审查一次
  • 常青内容：每年审查一次
在审查时，检查：
  • 链接是否仍然有效？
  • 系统或流程是否发生了变化？
  • 示例是否是最新的？
  • 是否有需要补充的新信息？
3

制定贡献指南

让任何人都能轻松改进知识库。你的指南应涵盖：
  • 格式：你是否有特定的模板或格式要求？
  • 流程：他人应如何提出并提交更改？
  • 审查：由谁来审查提交？处理周期是多少？
  • 范围：哪些类型的内容属于覆盖范围？
4

监控使用指标

审查你的团队如何使用知识库，以便为内容排定优先级并识别可改进的领域。为审查使用指标设定一个固定节奏——按月或按季度都是不错的间隔。
  • 哪些文章浏览量最高？优先投入精力保持这些内容准确且易于阅读。
  • 哪些文章完全没有浏览量？考虑删除它们或改进其可发现性。
  • 跳出率是多少？如果用户立即离开，说明内容可能不够有用，或者导航还有改进空间。

​
后续步骤

你的知识库已经可以上线了。部署完成后：
  1. 向团队发布知识库。
  2. 在 Analytics 中监控使用情况和搜索模式。
  3. 当人们发现内容缺口时，鼓励他们参与补充。
  4. 定期审查并更新内容。
最成功的知识库都会根据团队的实际使用方式不断演进。