mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
c789e88df2
* docs(locadex): add translations * Apply suggestion from @ethanpalm * Apply suggestion from @ethanpalm --------- Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
373 lines
16 KiB
Plaintext
373 lines
16 KiB
Plaintext
---
|
||
title: "可视化编辑器"
|
||
description: "在浏览器中创建、维护并发布文档。"
|
||
keywords: ["visual editor", "WYSIWYG", "web editor"]
|
||
---
|
||
|
||
<img className="block dark:hidden my-0 pointer-events-none" src="/images/editor/editor-light.png" alt="浅色模式下的 Mintlify 可视化编辑器界面" />
|
||
|
||
<img className="hidden dark:block my-0 pointer-events-none" src="/images/editor/editor-dark.png" alt="深色模式下的 Mintlify 可视化编辑器界面" />
|
||
|
||
从你的[控制台](https://dashboard.mintlify.com/editor)打开可视化编辑器，在浏览器中直接管理文档。
|
||
|
||
* **WYSIWYG（所见即所得）编辑**：使用 WYSIWYG 编辑器修改文档，同时预览发布后的呈现效果。
|
||
* **Git 同步**：所有更改会自动与 Git 存储库同步，确保版本管理。
|
||
* **团队协作**：多人可同时编辑文档。
|
||
* **组件集成**：通过斜杠命令添加提示、代码块等组件。
|
||
* **零配置**：在控制台即可立即开始写作。
|
||
|
||
<div id="overview">
|
||
## 概览
|
||
</div>
|
||
|
||
以下是在可视化编辑器中的典型工作方式：
|
||
|
||
<Steps>
|
||
<Step title="选择你的 branch">
|
||
创建一个 branch，或直接在部署用分支上进行更改。我们建议创建一个 branch，这样你可以在更改上线前进行预览。
|
||
</Step>
|
||
|
||
<Step title="打开你的文件">
|
||
通过侧边栏导航到现有文件，或使用文件资源管理器新建文件。
|
||
</Step>
|
||
|
||
<Step title="编辑你的内容">
|
||
在可视化编辑器中进行修改。按下 <kbd>/</kbd> 打开组件菜单。
|
||
</Step>
|
||
|
||
<Step title="预览你的更改">
|
||
可视化模式会展示你的更改在上线网站上的实际效果。用它来确认一切显示正确。
|
||
</Step>
|
||
|
||
<Step title="发布你的更改">
|
||
如果你在部署用分支上工作，可直接在可视化编辑器中发布更改。若在其他 branch 上，则需先创建拉取请求（PR；亦称“合并请求”/Merge Request）进行审核，再发布。
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="editor-modes">
|
||
## 编辑器模式
|
||
</div>
|
||
|
||
可视化编辑器提供两种模式，以满足不同的编辑偏好与需求：可视化模式和 Markdown 模式。
|
||
|
||
使用编辑器工具栏中的模式开关在两种模式之间切换。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/mode-toggle-light.png" alt="在可视化编辑器中高亮显示的模式切换图标。" className="block dark:hidden" />
|
||
|
||
<img src="/images/editor/mode-toggle-dark.png" alt="在可视化编辑器中高亮显示的模式切换图标。" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<div id="visual-mode">
|
||
### 可视化模式
|
||
</div>
|
||
|
||
可视化模式提供 WYSIWYG（所见即所得）体验，你在编辑器中的更改将与发布后的文档呈现保持一致。该模式非常适合希望实时预览更改效果的场景。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/visual-mode-light.png" alt="Mintlify 可视化编辑器中的可视化编辑模式" className="block dark:hidden" />
|
||
|
||
<img src="/images/editor/visual-mode-dark.png" alt="Mintlify 可视化编辑器中的可视化编辑模式" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<div id="markdown-mode">
|
||
### Markdown 模式
|
||
</div>
|
||
|
||
Markdown 模式让你可以直接访问构成文档的文件。当你需要精确控制组件属性，或者更习惯使用 MDX 语法来编写内容时，这一模式非常适合。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/markdown-mode-light.png" alt="Mintlify 可视化编辑器中的 Markdown 模式" className="block dark:hidden" />
|
||
|
||
<img src="/images/editor/markdown-mode-dark.png" alt="Mintlify 可视化编辑器中的 Markdown 模式" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<div id="manage-content">
|
||
## 管理对象
|
||
</div>
|
||
|
||
<div id="navigate-your-files">
|
||
### 浏览文件
|
||
</div>
|
||
|
||
使用侧边栏文件浏览器来查看文档文件。点击任意文件即可在编辑器中打开。
|
||
|
||
在 macOS 上按下 <kbd>Command</kbd> + <kbd>P</kbd>，或在 Windows 上按下 <kbd>Ctrl</kbd> + <kbd>P</kbd>，即可按名称搜索文件。
|
||
|
||
<div id="create-new-pages">
|
||
### 新建页面
|
||
</div>
|
||
|
||
在文件资源管理器侧边栏中点击**创建新文件**图标。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/files-menu-light.png" className="block dark:hidden rounded-2xl border border-gray-100 shadow-lg" style={{ width:"400px",height:"auto" }} alt="可视化编辑器中的文件菜单" />
|
||
|
||
<img src="/images/editor/files-menu-dark.png" className="hidden dark:block rounded-2xl border border-white/10 shadow-lg" style={{ width:"400px",height:"auto" }} alt="深色模式下的可视化编辑器文件菜单" />
|
||
</Frame>
|
||
|
||
文件名会自动添加 `.mdx` 扩展名。要更改文件类型，点击该扩展名，并从下拉菜单中选择所需的类型。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/file-type-light.png" className="block dark:hidden" style={{ width:"auto",height:"400px" }} alt="可视化编辑器中的文件扩展名菜单。" />
|
||
|
||
<img src="/images/editor/file-type-dark.png" className="hidden dark:block" style={{ width:"auto",height:"400px" }} alt="深色模式下的可视化编辑器文件扩展名菜单。" />
|
||
</Frame>
|
||
|
||
<div id="rename-pages">
|
||
### 重命名页面
|
||
</div>
|
||
|
||
要重命名页面，点击目标文件的“更多”菜单（kebab 菜单）icon，然后在下拉菜单中选择 **Rename**。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/rename-light.png" className="block dark:hidden" alt="在可视化编辑器中重命名页面。" />
|
||
|
||
<img src="/images/editor/rename-dark.png" className="hidden dark:block" alt="在暗色模式的可视化编辑器中重命名页面。" />
|
||
</Frame>
|
||
|
||
<div id="delete-pages">
|
||
### 删除页面
|
||
</div>
|
||
|
||
要删除页面，点击该文件的“更多”菜单 icon，然后在下拉菜单中选择 **Delete**。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/delete-page-light.png" className="block dark:hidden" alt="在可视化编辑器中删除页面。" />
|
||
|
||
<img src="/images/editor/delete-page-dark.png" className="hidden dark:block" alt="在深色模式下的可视化编辑器中删除页面。" />
|
||
</Frame>
|
||
|
||
<div id="organize-your-navigation">
|
||
### 组织导航
|
||
</div>
|
||
|
||
编辑 `docs.json` 文件，在站点导航中添加新页面并移除已删除的页面。有关如何组织页面的更多信息，请参见[导航](/zh/organize/navigation)。
|
||
|
||
**示例：在 Profile 组中添加 Themes 页面**
|
||
|
||
在此示例中，你创建了一个名为 Themes 的新页面，并希望将其添加到文档中的 Profile 组。将新页面的路径添加到 `docs.json` 文件中 `Profile` 组的 `pages` 数组中，使其显示在站点导航中。
|
||
|
||
```json Adding a Themes page to the Profile group {18}
|
||
{
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "开始使用",
|
||
"pages": [
|
||
"index",
|
||
"quickstart",
|
||
"installation"
|
||
]
|
||
},
|
||
{
|
||
"group": "个人资料",
|
||
"pages": [
|
||
"settings",
|
||
"account-types",
|
||
"dashboard",
|
||
"themes"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
<div id="edit-content">
|
||
### 编辑内容
|
||
</div>
|
||
|
||
使用编辑器中的可视化模式或 Markdown 模式对页面进行修改。
|
||
|
||
在可视化模式下，按下 <kbd>/</kbd> 打开组件菜单。添加内容块、提示框、代码块以及其他组件，以自定义你的文档。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/component-menu-light.png" alt="在 Mintlify 可视化编辑器中展开并高亮显示的组件菜单" className="block dark:hidden" />
|
||
|
||
<img src="/images/editor/component-menu-dark.png" alt="在 Mintlify 可视化编辑器中展开并高亮显示的组件菜单" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
在 Markdown 模式下，你可以直接编辑页面的 MDX。在以下情况下，这会很有帮助：
|
||
|
||
* 设置特定的组件属性
|
||
* 处理复杂的嵌套组件
|
||
* 从其他来源复制并粘贴 MDX 内容
|
||
|
||
要了解更多关于如何使用 MDX 语法编写的信息，请参阅[格式化文本](/zh/create/text)和[格式化代码](/zh/create/code)。
|
||
|
||
<div id="publish-your-changes">
|
||
## 发布你的更改
|
||
</div>
|
||
|
||
你当前工作的 branch 将决定编辑器如何发布你的更改：
|
||
|
||
* **部署用分支**：发布会立即更新你的线上站点。
|
||
* **其他分支**：发布会创建一个拉取请求（PR；亦称“合并请求”/Merge Request），以便你在将其部署到生产环境之前先审阅更改。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/publish-flow-light.png" alt="Mintlify 可视化编辑器中被强调的“发布”按钮" className="block dark:hidden" />
|
||
|
||
<img src="/images/editor/publish-flow-dark.png" alt="Mintlify 可视化编辑器中被强调的“发布”按钮" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
如果你已将 Mintlify 授权给你的 GitHub 用户，你的提交将会像由你本人完成一样被签署；否则，将由 Mintlify GitHub 应用进行签署。
|
||
|
||
<div id="pull-requests-and-reviewing-changes">
|
||
### 拉取请求（PR）与变更审查
|
||
</div>
|
||
|
||
拉取请求（PR；亦称“合并请求”/Merge Request）允许你从你的 branch 提交变更，便于他人在合并到线上文档前进行审查。这样有助于确保变更准确无误，并让团队有机会就内容进行协作。
|
||
|
||
<Tip>
|
||
即使你独自作业，拉取请求也有助于预览变更并维护清晰的更新历史。
|
||
</Tip>
|
||
|
||
<div id="create-a-pull-request">
|
||
#### 创建拉取请求（PR）
|
||
</div>
|
||
|
||
<Steps>
|
||
<Step title="保存你的工作">
|
||
选择 **保存更改**，将所有更改保存到你的 branch。
|
||
</Step>
|
||
|
||
<Step title="创建拉取请求">
|
||
在编辑器工具栏中选择 **发布拉取请求**。
|
||
</Step>
|
||
|
||
<Step title="添加标题和说明">
|
||
编写清晰的标题和说明，解释：
|
||
|
||
* 做了哪些更改
|
||
* 为什么进行这些更改
|
||
* 需要重点审阅的部分
|
||
</Step>
|
||
|
||
<Step title="创建并分享">
|
||
选择 **发布拉取请求**。编辑器会提供一个链接以查看你的拉取请求。
|
||
|
||
<Frame>
|
||
<img src="/images/editor/pull-request-light.png" alt="在 Mintlify 可视化编辑器中突出的“发布拉取请求”按钮" className="block dark:hidden" />
|
||
|
||
<img src="/images/editor/pull-request-dark.png" alt="在 Mintlify 可视化编辑器中突出的“发布拉取请求”按钮" className="hidden dark:block" />
|
||
</Frame>
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="review-pull-requests">
|
||
#### 审阅拉取请求（PR）
|
||
</div>
|
||
|
||
创建拉取请求（PR）后：
|
||
|
||
1. **审阅更改**：你和团队成员可以在 Git 托管平台（如 GitHub 或 GitLab）中审阅你的拉取请求（PR）。
|
||
2. **留下反馈**：添加评论或请求修改。
|
||
3. **进一步修改**：可在可视化编辑器中继续修改。保存更改时，编辑器会将其推送到你的拉取请求（PR）。
|
||
4. **批准**：当你对更改满意时，批准该拉取请求（PR）。
|
||
5. **合并**：当你准备将更改部署到生产环境时，合并该拉取请求（PR）。
|
||
|
||
<div id="keyboard-shortcuts">
|
||
## 键盘快捷键
|
||
</div>
|
||
|
||
可视化编辑器支持复制、粘贴、撤销、全选等常见快捷键，以及以下快捷键：
|
||
|
||
| 命令 | macOS | Windows |
|
||
| :------------------------------- | :--------------------------------------------------- | :------------------------------------------------------- |
|
||
| **搜索文件** | <kbd>Cmd</kbd> + <kbd>P</kbd> | <kbd>Control</kbd> + <kbd>P</kbd> |
|
||
| **为选中文本添加链接** | <kbd>Cmd</kbd> + <kbd>K</kbd> | <kbd>Control</kbd> + <kbd>K</kbd> |
|
||
| **插入换行** | <kbd>Cmd</kbd> + <kbd>Enter</kbd> | <kbd>Control</kbd> + <kbd>Enter</kbd> |
|
||
| **加粗** | <kbd>Cmd</kbd> + <kbd>B</kbd> | <kbd>Control</kbd> + <kbd>B</kbd> |
|
||
| **斜体** | <kbd>Cmd</kbd> + <kbd>I</kbd> | <kbd>Control</kbd> + <kbd>I</kbd> |
|
||
| **下划线** | <kbd>Cmd</kbd> + <kbd>U</kbd> | <kbd>Control</kbd> + <kbd>U</kbd> |
|
||
| **删除线** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> |
|
||
| **代码** | <kbd>Cmd</kbd> + <kbd>E</kbd> | <kbd>Control</kbd> + <kbd>E</kbd> |
|
||
| **正文** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> |
|
||
| **标题 1** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> |
|
||
| **标题 2** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> |
|
||
| **标题 3** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> |
|
||
| **标题 4** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> |
|
||
| **有序列表** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> |
|
||
| **无序列表** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> |
|
||
| **引用** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd> |
|
||
| **下标** | <kbd>Cmd</kbd> + <kbd>,</kbd> | <kbd>Control</kbd> + <kbd>,</kbd> |
|
||
| **上标** | <kbd>Cmd</kbd> + <kbd>.</kbd> | <kbd>Control</kbd> + <kbd>.</kbd> |
|
||
|
||
<div id="troubleshooting">
|
||
## 故障排查
|
||
</div>
|
||
|
||
查找使用可视化编辑器时可能遇到的常见问题的解决方案。
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="发布后更改未显示">
|
||
**可能原因：**
|
||
|
||
* 部署仍在进行
|
||
* 浏览器缓存问题
|
||
* 构建或部署错误
|
||
|
||
**解决方案：**
|
||
|
||
1. 在控制台中检查部署状态。
|
||
2. 强制刷新浏览器（<kbd>Ctrl</kbd>
|
||
|
||
* <kbd>F5</kbd>
|
||
|
||
或 <kbd>Cmd</kbd>
|
||
|
||
* <kbd>Shift</kbd>
|
||
|
||
* <kbd>R</kbd>
|
||
|
||
)
|
||
3. 清除浏览器缓存。
|
||
</Accordion>
|
||
|
||
<Accordion title="发布时出现权限错误">
|
||
**可能原因：**
|
||
|
||
* 对 Git 存储库权限不足
|
||
* 与 Git 提供商的认证问题
|
||
|
||
**解决方案：**
|
||
|
||
1. 确认你对存储库具有正确的访问权限。
|
||
2. 检查你的 Git 集成是否已正确配置。
|
||
3. 查看[编辑器权限](/zh/dashboard/permissions)文档。
|
||
</Accordion>
|
||
|
||
<Accordion title="编辑器加载问题">
|
||
**可能原因：**
|
||
|
||
* 网络连接问题
|
||
* 文档存储库体量较大
|
||
|
||
**解决方案：**
|
||
|
||
1. 检查你的网络连接。
|
||
2. 刷新页面。
|
||
3. 若问题仍然存在，请联系支持。
|
||
</Accordion>
|
||
|
||
<Accordion title="文件未加载或出现错误">
|
||
**可能原因：**
|
||
|
||
* 文件中存在无效的 MDX 语法
|
||
* 文件缺失或损坏
|
||
* 文件过大导致超时
|
||
|
||
**解决方案：**
|
||
|
||
1. 检查文件语法是否存在 MDX 格式错误。
|
||
2. 验证该文件是否存在于你的存储库中。
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
<div id="next-steps">
|
||
## 后续步骤
|
||
</div>
|
||
|
||
* 学习基础的 [Git 概念](/zh/guides/git-concepts)
|
||
* 学习使用 [branch](/zh/guides/branches) 进行协作的最佳实践 |