可视化编辑器

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

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

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

​

概览

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

1. Choose your branch

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

2. Open your file

   在侧边栏中定位到现有文件，或通过文件资源管理器创建新文件。

3. Edit your content

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

4. Preview your changes

   可视化模式会展示你的更改在上线站点上的呈现效果。用它来核对一切是否正确。

5. Publish your changes

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

​

编辑器模式

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

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

​

可视化模式

可视化模式提供 WYSIWYG（所见即所得）体验，你在编辑器中的更改会如实呈现为已发布文档的最终效果。此模式非常适合需要实时预览更改的场景。

​

Markdown 模式

Markdown 模式可让你直接访问文档的底层 MDX 代码。当你需要对组件属性进行精细控制，或更倾向于使用 Markdown 语法编写时，此模式非常适合。

​

管理对象

​

浏览文件

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

在 macOS 上按 Command + P，或在 Windows 上按 Ctrl + P，即可按名称搜索文件。

​

创建新页面

在文件资源管理器侧边栏中，选择 Create a new file 图标。

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

​

重命名页面

要重命名页面，点击目标文件的省略号菜单 icon，并在下拉菜单中选择Rename。

​

删除页面

要删除页面，点击目标文件的三点菜单 icon，然后在下拉菜单中选择Delete。

​

组织导航

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

示例：在 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），以便你在部署到生产环境前先审查更改。

​

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

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

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

​

创建拉取请求（PR）

1. 保存你的工作

   选择 保存更改，将你在当前 branch 上的所有更改保存。

2. 创建拉取请求

   在编辑器工具栏中选择 Publish Pull Request。

3. 添加标题和说明

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

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

   选择 Publish Pull Request。编辑器会提供一个链接，供你查看拉取请求（PR）。

   

​

审阅拉取请求（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 + F5 或 Cmd + Shift + R）。
3. 清除浏览器缓存。

发布时出现权限错误

可能原因：

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

解决方案：

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

编辑器加载问题

可能原因：

• 网络连接异常
• 文档存储库体量较大

解决方案：

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

文件未加载或显示错误

可能原因：

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

解决方案：

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

​

下一步

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