可视化编辑器

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

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

概览

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

选择你的 branch

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

打开你的文件

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

编辑你的内容

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

预览你的更改

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

发布你的更改

如果你在部署用分支上工作，可直接在可视化编辑器中发布更改。若在其他 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）

保存你的工作

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

创建拉取请求

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

添加标题和说明

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

做了哪些更改
为什么进行这些更改
需要重点审阅的部分

创建并分享

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

审阅拉取请求（PR）

创建拉取请求（PR）后：

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

故障排查

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

发布后更改未显示

可能原因：

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

解决方案：

在控制台中检查部署状态。
强制刷新浏览器（Ctrl
- F5
或 Cmd
- Shift
- R
)
清除浏览器缓存。

发布时出现权限错误

可能原因：

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

解决方案：

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

编辑器加载问题

可能原因：

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

解决方案：

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

文件未加载或出现错误

可能原因：

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

解决方案：

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

后续步骤

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

开始使用

组织

自定义

创建对象

文档 API

部署

优化

可视化编辑器

概览