可视化编辑器

在浏览器中创建、维护和发布文档

从你的控制台打开可视化编辑器，直接在浏览器中管理文档。

• WYSIWYG（所见即所得）编辑：使用所见即所得（WYSIWYG）编辑器修改文档，并实时预览发布后的效果。
• Git 同步：所有更改会自动与 Git 存储库同步，确保版本控制。
• 团队协作：多人可同时编辑文档。
• 组件集成：通过斜杠命令添加提示、代码块和其他组件。
• 无需配置：可在控制台立即开始撰写。

​

概览

以下是在可视化编辑器中的典型工作方式：

1. 选择你的 branch

   创建一个 branch，或直接在部署用分支上进行更改。我们建议创建一个 branch，这样你可以在更改上线前进行预览。

2. 打开你的文件

   通过侧边栏导航到现有文件，或使用文件资源管理器新建文件。

3. 编辑你的内容

   在可视化编辑器中进行修改。按下 / 打开组件菜单。

4. 预览你的更改

   可视化模式会展示你的更改在上线网站上的实际效果。用它来确认一切显示正确。

5. 发布你的更改

   如果你在部署用分支上工作，可直接在可视化编辑器中发布更改。若在其他 branch 上，则需先创建拉取请求（PR；亦称“合并请求”/Merge Request）进行审核，再发布。

​

编辑器模式

可视化编辑器提供两种模式，以满足不同的编辑偏好与需求：可视化模式和 Markdown 模式。

使用编辑器工具栏中的模式开关在两种模式之间切换。

​

可视化模式

可视化模式提供 WYSIWYG（所见即所得）体验，你在编辑器中的更改将与发布后的文档呈现保持一致。该模式非常适合希望实时预览更改效果的场景。

​

Markdown 模式

Markdown 模式可直接访问文档底层的 MDX 代码。此模式非常适合在需要精确控制组件属性，或偏好使用 Markdown 语法撰写内容时使用。

​

管理对象

​

浏览文件

使用侧边栏的文件浏览器查看文档。点击任意文件即可在编辑器中打开。

在 macOS 上按 Command

或在 Windows 上按 Ctrl

即可按名称搜索文件。

​

新建页面

在文件资源管理器侧边栏中点击创建新文件图标。

文件名会自动添加 .mdx 扩展名。要更改文件类型，点击该扩展名，并从下拉菜单中选择所需的类型。

​

重命名页面

要重命名页面，点击目标文件的“更多”菜单（kebab 菜单）icon，然后在下拉菜单中选择 Rename。

​

删除页面

要删除页面，点击该文件的“更多”菜单 icon，然后在下拉菜单中选择 Delete。

​

组织导航

编辑 docs.json 文件，在站点导航中添加新页面并移除已删除的页面。有关如何组织页面的更多信息，请参见导航。

示例：在 Profile 组中添加 Themes 页面

在此示例中，你创建了一个名为 Themes 的新页面，并希望将其添加到文档中的 Profile 组。将新页面的路径添加到 docs.json 文件中 Profile 组的 pages 数组中，使其显示在站点导航中。

Adding a Themes page to the Profile group

{
    "navigation": {
        "groups": [
            {
                "group": "开始使用",
                "pages": [
                    "index",
                    "quickstart",
                    "installation"
                ]
            },
            {
                "group": "个人资料",
                "pages": [
                    "settings",
                    "account-types",
                    "dashboard",
                    "themes"
                ]
            }
        ]
    }
}

​

编辑内容

在编辑器中使用可视化模式或 Markdown 模式对页面进行修改。

在可视化模式下，按 / 打开组件菜单。添加内容块、提示、代码块和其他组件，以自定义你的文档。

在 Markdown 模式下，你可以直接编辑页面的 MDX。在以下场景中会很有帮助：

• 设置特定的组件属性
• 处理复杂的嵌套组件
• 从其他来源复制并粘贴 MDX 内容

参见 格式化文本 和 格式化代码，了解更多关于使用 Markdown 语法写作的信息。

​

发布你的更改

你当前工作的 branch 将决定编辑器如何发布你的更改：

• 部署用分支：发布会立即更新你的线上站点。
• 其他分支：发布会创建一个拉取请求（PR；亦称“合并请求”/Merge Request），以便你在将其部署到生产环境之前先审阅更改。

如果你已将 Mintlify 授权给你的 GitHub 用户，你的提交将会像由你本人完成一样被签署；否则，将由 Mintlify GitHub 应用进行签署。

​

拉取请求（PR）与变更审查

拉取请求（PR；亦称“合并请求”/Merge Request）允许你从你的 branch 提交变更，便于他人在合并到线上文档前进行审查。这样有助于确保变更准确无误，并让团队有机会就内容进行协作。

即使你独自作业，拉取请求也有助于预览变更并维护清晰的更新历史。

​

创建拉取请求（PR）

1. 保存你的工作

   选择 保存更改，将所有更改保存到你的 branch。

2. 创建拉取请求

   在编辑器工具栏中选择 发布拉取请求。

3. 添加标题和说明

   编写清晰的标题和说明，解释：

   • 做了哪些更改
   • 为什么进行这些更改
   • 需要重点审阅的部分
4. 创建并分享

   选择 发布拉取请求。编辑器会提供一个链接以查看你的拉取请求。

   

​

审阅拉取请求（PR）

创建拉取请求（PR）后：

1. 审阅更改：你和团队成员可以在 Git 托管平台（如 GitHub 或 GitLab）中审阅你的拉取请求（PR）。
2. 留下反馈：添加评论或请求修改。
3. 进一步修改：可在可视化编辑器中继续修改。保存更改时，编辑器会将其推送到你的拉取请求（PR）。
4. 批准：当你对更改满意时，批准该拉取请求（PR）。
5. 合并：当你准备将更改部署到生产环境时，合并该拉取请求（PR）。

​

键盘快捷键

可视化编辑器支持复制、粘贴、撤销、全选等常见快捷键，以及以下快捷键：

命令	macOS	Windows
搜索文件	Cmd + P	Control + P
为选中文本添加链接	Cmd + K	Control + K
插入换行	Cmd + Enter	Control + Enter
加粗	Cmd + B	Control + B
斜体	Cmd + I	Control + I
下划线	Cmd + U	Control + U
删除线	Cmd + Shift + S	Control + Shift + S
代码	Cmd + E	Control + E
正文	Cmd + Alt + 0	Control + Alt + 0
标题 1	Cmd + Alt + 1	Control + Alt + 1
标题 2	Cmd + Alt + 2	Control + Alt + 2
标题 3	Cmd + Alt + 3	Control + Alt + 3
标题 4	Cmd + Alt + 4	Control + Alt + 4
有序列表	Cmd + Shift + 7	Control + Shift + 7
无序列表	Cmd + Shift + 8	Control + Shift + 8
引用	Cmd + Shift + B	Control + Shift + B
下标	Cmd + ,	Control + ,
上标	Cmd + .	Control + .

​

故障排查

查找使用可视化编辑器时可能遇到的常见问题的解决方案。

发布后更改未显示

可能原因：

• 部署仍在进行
• 浏览器缓存问题
• 构建或部署错误

解决方案：

1. 在控制台中检查部署状态。

2. 强制刷新浏览器（Ctrl

   或 Cmd

   )

3. 清除浏览器缓存。

发布时出现权限错误

可能原因：

• 对 Git 存储库权限不足
• 与 Git 提供商的认证问题

解决方案：

1. 确认你对存储库具有正确的访问权限。
2. 检查你的 Git 集成是否已正确配置。
3. 查看编辑器权限文档。

编辑器加载问题

可能原因：

• 网络连接问题
• 文档存储库体量较大

解决方案：

1. 检查你的网络连接。
2. 刷新页面。
3. 若问题仍然存在，请联系支持。

文件未加载或出现错误

可能原因：

• 文件中存在无效的 MDX 语法
• 文件缺失或损坏
• 文件过大导致超时

解决方案：

1. 检查文件语法是否存在 MDX 格式错误。
2. 验证该文件是否存在于你的存储库中。

​

后续步骤

• 学习基础的 Git 概念
• 学习在 branch 上协作的最佳实践