` 这样的普通 HTML 元素。
* 无法解析的 snippet 导入。
这些类型的错误会导致构建失败，因此请在编写时及时修复，以避免部署失败。
要关闭诊断，请将 `mintlify.diagnostics.enabled` 设置为 `false`。
## 悬停文档 [#悬停文档]
将光标悬停在组件或属性上，即可查看其作用以及指向 Mintlify 文档中对应页面的链接。悬停在 snippet 组件上会预览 snippet 文件的内容。
## 跳转到定义 [#跳转到定义]
按住
Cmd（macOS）或
Ctrl（Windows）并点击，即可跳转到以下内容的定义：
* Snippet 组件。
* 导入路径。
* 指向本地页面的 `href` 和 `src` 属性。
扩展会从打开的文件向上查找，直到找到 `docs.json`，以此确定文档根目录，因此像 `/snippets/example.mdx` 这样的绝对导入可以正确解析。检测到的项目会显示在状态栏中。要查看扩展正在使用哪个根目录，请在命令面板中运行 **Mintlify: Show detected docs root**。
## 折叠 [#折叠]
使用行号侧边的折叠箭头来折叠页面中的区域：
* 组件和 HTML 标签区域，例如 `
…`。
* 标题小节。
* Frontmatter。
* 代码块。
* JSX 注释。
## 配置校验 [#配置校验]
扩展会根据 [Mintlify 架构](https://mintlify.com/docs.json)校验 `docs.json`。
## 可视化模式 [#可视化模式]
在可视化模式下打开任意 `.mdx` 文件，即可像在 Mintlify 仪表板中那样在富文本编辑器中编辑页面，标题、列表、表格、链接、提示框、卡片、步骤、选项卡、折叠面板、代码块和图片都可以就地编辑。
在可视化模式和文本编辑器之间切换：
* 按
Cmd+
Shift+
V（macOS）或
Ctrl+
Shift+
V（Windows）。
* 或使用面包屑行右端的编辑器选择器。
使用标题栏中的齿轮图标可选择 `.mdx` 文件默认使用哪个编辑器打开。
输入时 Markdown 快捷方式生效（`#` 表示标题，`-` 表示列表项，`**bold**`、`` `code` ``），工具栏和 `/` 菜单可用于插入组件。编辑内容会通过与 [`mint format`](/zh/cli/commands#mint-format) 相同的转换器写回为 MDX。可视化模式无法识别的组件会按原样保留。
### Snippet 表单 [#snippet-表单]
在可视化模式下，从 snippet 导入的组件会显示为一个表单，每个 prop 对应一个输入，而不是一个不透明的标签。字段根据组件解构后的 prop 和默认值推断，因此默认值为 `true` 会变成复选框，`2` 会变成数字框，`icon` 或 `logo` 会变成带缩略图的图片路径，`href` 或 `url` 会变成链接。
要控制输入项，请在导出前使用 JSDoc `@param` 注释来对组件进行文档说明。在 `.jsx` 和 `.tsx` 文件中使用 `/** … */` 块。在 `.mdx` snippet 中，使用 MDX 注释（`{/* … */}`），这样它不会被渲染：
```mdx
{/*
A product tile with a price and a call to action.
@param {string} name - Product name, shown as the title
@param {image} [icon] - Path to a square icon under /images
@param {'Free' | 'Pro' | 'Enterprise'} [tier=Free] - Which plan it belongs to
@param {number} [seats=1] - Seats included
@param {boolean} [featured] - Highlight the card
@param {url} [href] - Where the button goes
@param {text} [summary] - One or two sentences under the title
*/}
export const ProductCard = ({ name, icon, tier = 'Free', seats = 1, featured = false, href, summary, children }) => ( ... );
```
以下类型会生成对应的表单输入：
| 类型 | 输入 |
| -------------------- | ------------ |
| `string` | 文本框 |
| `text`（或 `markdown`） | 多行文本框 |
| `boolean` | 复选框 |
| `number` | 数字框 |
| `'a' \| 'b'` | 这些值的下拉框 |
| `image` | 带缩略图的路径框 |
| `url` | 链接框 |
| `color` | 带色块的文本框 |
| 其他类型 | 原始 `{…}` 表达式 |
方括号（`[name]`）表示 prop 为可选。没有方括号的已文档化 prop 会显示必填标记。`[name=value]` 在解构没有默认值时提供一个默认值。注释的第一行是显示在表单头部和 **Insert** 菜单中的描述。
`children` 永远不会作为字段：标签的主体会按原样保留，并在表单下方作摘要展示。切换到文本编辑器进行编辑。
导入的 snippet 也会出现在 **+ Insert** 菜单和 `/` 菜单中。
活动栏中的 Mintlify 视图会镜像你的 `docs.json` 导航树。顶层的 products 和 tabs 保持在根部，其导航嵌套在可展开的行中。侧边栏使用 `docs.json` 和页面 frontmatter 中的图标，页面标签取自 `sidebarTitle` 或 `title`。选中某个页面会在可视化模式下打开它。
使用 **+** 操作可以添加 groups、tabs、dropdowns、anchors、languages、products 和 versions。拖动行可以重新排序，或将一个页面拖放到某个 group 上，将其移动到该 group 的顶部。树会立即变动，然后 Mintlify 会将更改保存到 `docs.json`。
树会跟随当前活动页面，并在 `docs.json` 或页面变化时重新加载。
## 在编辑器中预览 [#在编辑器中预览]
打开一个 `.mdx` 文件，选择编辑器标题栏中的预览图标，或右键点击文件并选择 **Preview Mintlify**。预览面板会在编辑器旁打开并渲染页面。
预览工具栏包含后退、前进和重新加载按钮、地址框，以及 **Follow editor** 开关。在地址框中输入类似 `/quickstart` 的路径并按
Enter 即可跳转到该页面。开启 **Follow editor** 后，预览会随着你在编辑器中切换文件而切换页面。
在预览内按
Cmd+
F（macOS）或
Ctrl+
F（Windows）可打开针对已渲染页面的查找栏。
Enter 和
Shift+
Enter 可在匹配项之间切换。
Esc 关闭查找栏。
编辑器内预览在 iframe 中渲染，因此浏览器开发者工具无法访问它。选择预览工具栏中的 **Open in browser** 按钮，或运行 **Mintlify: Open preview in browser**，改为在浏览器中打开页面。
编辑器内预览需要 [Mintlify CLI](/zh/cli/install)。预览服务器默认在端口 `3939` 上运行，以避免与端口 3000 上的应用冲突。可通过 `mintlify.preview.port` 设置更改端口。
运行中服务器的 URL 会显示在状态栏中。选择它可以停止服务器，或运行 **Mintlify: Stop preview server**。
要查看底层 `mint dev` 进程的输出，请打开 **Mintlify Preview** 输出通道。
编写单个页面时使用编辑器内预览；当你想在整个站点范围内测试导航、搜索或身份验证时，在浏览器中使用 [`mint dev`](/zh/cli/preview)。
## 用组件包裹内容 [#用组件包裹内容]
扩展包含的 snippet 会将选中的文本包裹在组件中，而不是插入一个空组件让你填写。
使用方法：选中要包裹的内容，然后在命令面板中运行 **Snippets: Surround With** 并选择一个组件。可用的 snippet 包括 `AccordionGroup`、`CardGroup`、`CodeGroup`、`Expandable`、`Frame`、`RequestExample`、`ResponseExample` 和围栏代码块。
## 设置 [#设置]
| 设置 | 默认值 | 说明 |
| ----------------------------------------- | -------------------- | -------------------------------------------- |
| `mintlify.diagnostics.enabled` | `true` | 报告未知组件、未知属性、缺少的必需属性和无法解析的 snippet 导入。 |
| `mintlify.warnAboutConflictingExtensions` | `true` | 当你在 Mintlify MDX 扩展之外还安装了其他 MDX 扩展时发出警告。 |
| `mintlify.preview.command` | `mint dev --no-open` | 用于启动预览服务器的命令，从项目根目录运行。 |
| `mintlify.preview.followEditor` | `true` | 当你切换文件时，将预览切换到当前活动编辑器对应的页面。也可以从预览工具栏切换。 |
| `mintlify.preview.port` | `3939` | 预览服务器的端口。除非预览命令已设置端口，否则会以 `--port` 形式附加到该命令。 |
`mintlify.preview.command` 是用户级设置，工作区无法覆盖它。这可以防止克隆的仓库在你打开预览时在你的机器上运行任意命令。
## 命令 [#命令]
在命令面板中运行以下命令：
| 命令 | 说明 |
| ------------------------------------- | ------------------------ |
| **Mintlify: Preview Mintlify** | 为当前文件打开预览面板。 |
| **Mintlify: Stop preview server** | 停止正在运行的预览服务器。 |
| **Mintlify: Open preview in browser** | 在浏览器中打开预览的页面。 |
| **Mintlify: Show detected docs root** | 显示扩展解析到的 `docs.json` 文件。 |
| **Mintlify: Open component docs** | 打开光标所在组件的文档。 |
| **Mintlify: Restart language server** | 重启语言服务器。 |
## 冲突的扩展 [#冲突的扩展]
其他 MDX 扩展为 `.mdx` 文件提供各自的语法高亮和语言功能，会与此扩展冲突。请禁用其他 MDX 扩展，以避免重复的提示和不一致的高亮。
对于代码格式化，请将 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) 与此扩展搭配使用，或运行 [`mint format`](/zh/cli/commands#mint-format)。
## 故障排除 [#故障排除]
扩展相对于文档根目录解析组件。运行 **Mintlify: Show detected docs root**，确认它找到了正确的 `docs.json` 文件。如果根目录错误或缺失，请将包含 `docs.json` 文件的文件夹作为工作区打开。
如果根目录正确，请运行 **Mintlify: Restart language server**。
很可能有另一个 MDX 扩展也处于激活状态。打开扩展视图，搜索 `mdx`，并在此工作区中禁用其他所有 MDX 扩展。
打开 **Mintlify Preview** 输出通道，查看 `mint dev` 的错误信息。
* `could not run "mint dev --no-open"`：CLI 未安装。使用 `npm i -g mint` 安装。
* `Trust the workspace first`：通过 **Manage Workspace Trust** 信任该工作区。
* `no docs.json found above this file`：将包含 `docs.json` 文件的文件夹作为工作区打开。
* `Invalid docs.json`：运行 [`mint validate`](/zh/cli/commands#mint-validate) 查找配置错误。
绝对导入路径从文档根目录解析，而不是从当前文件解析。请确认该路径与 snippet 文件相对于 `docs.json` 文件的位置一致，并且检测到的根目录是正确的。