> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mintlify MDX 扩展

> 安装 Mintlify MDX 扩展，在本地编写 MDX 时获得自动补全、内联诊断、悬停文档和编辑器内预览。

Mintlify MDX 扩展为 VS Code、Cursor、Devin Desktop 以及其他支持 VS Code 扩展 API 的编辑器提供 Mintlify 项目的语言支持。该扩展了解每个内置组件和属性，因此你在输入时可以获得自动补全，它还会报告未知组件、无效属性和无法解析的 snippet 导入。

该扩展还会在编辑器内运行实时预览，让你无需切换到浏览器即可边写作边查看渲染结果。

<div id="prerequisites">
  ## 前提条件
</div>

* VS Code 1.85.0 或更高版本
* 包含有效 `docs.json` 文件的文档目录
* [Mintlify CLI](/docs/zh/cli/install)（仅编辑器内预览需要）

<div id="install-the-extension">
  ## 安装扩展
</div>

从命令行安装：

```bash theme={null}
code --install-extension mintlify.mintlify-snippets
```

或在编辑器内安装：

1. 打开扩展视图。
2. 搜索 `@id:mintlify.mintlify-snippets`。
3. 点击 **Install**。

你也可以从 [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets) 安装。

当你打开 `.mdx` 文件或包含 `docs.json` 文件的工作区时，扩展会自动激活。

<div id="autocomplete">
  ## 自动补全
</div>

输入 `<` 即可查看所有内置组件。自动补全会在标签内提示组件的属性和值。

除内置组件外，扩展还会提示你从[可复用 snippet](/docs/zh/create/reusable-snippets) 导入的组件。

<div id="diagnostics">
  ## 诊断
</div>

扩展会在“问题”面板中报告问题，并在你编写时在文件中以下划线标出：

* 未知组件。
* 未知或重复的属性。
* 枚举属性的无效值。
* 缺少必需属性。
* 未闭合或不匹配的标签。
* 无法解析的 snippet 导入。

这些类型的错误会导致构建失败，因此请在编写时及时修复，以避免部署失败。

要关闭诊断，请将 `mintlify.diagnostics.enabled` 设置为 `false`。

<div id="hover-documentation">
  ## 悬停文档
</div>

将光标悬停在组件或属性上，即可查看其作用以及指向 Mintlify 文档中对应页面的链接。悬停在 snippet 组件上会预览 snippet 文件的内容。

<div id="go-to-definition">
  ## 跳转到定义
</div>

按住 <kbd>CMD</kbd>（macOS）或 <kbd>CTRL</kbd>（Windows）并点击，即可跳转到以下内容的定义：

* Snippet 组件。
* 导入路径。
* 指向本地页面的 `href` 和 `src` 属性。

扩展会从打开的文件向上查找，直到找到 `docs.json`，以此确定文档根目录，因此像 `/snippets/example.mdx` 这样的绝对导入可以正确解析。检测到的项目会显示在状态栏中。要查看扩展正在使用哪个根目录，请在命令面板中运行 **Mintlify: Show detected docs root**。

<div id="configuration-validation">
  ## 配置校验
</div>

扩展会根据 [Mintlify 架构](https://mintlify.com/docs.json)校验 `docs.json`。

<div id="preview-in-your-editor">
  ## 在编辑器中预览
</div>

打开一个 `.mdx` 文件，选择编辑器标题栏中的预览图标，或右键点击文件并选择 **Preview Mintlify**。预览面板会在编辑器旁打开并渲染页面。

编辑器内预览需要 [Mintlify CLI](/docs/zh/cli/install)。运行中服务器的 URL 会显示在状态栏中。选择它可以停止服务器，或运行 **Mintlify: Stop preview server**。

要查看底层 `mint dev` 进程的输出，请打开 **Mintlify Preview** 输出通道。

<Tip>
  编写单个页面时使用编辑器内预览；当你想在整个站点范围内测试导航、搜索或身份验证时，在浏览器中使用 [`mint dev`](/docs/zh/cli/preview)。
</Tip>

<div id="wrap-content-in-components">
  ## 用组件包裹内容
</div>

扩展包含的 snippet 会将选中的文本包裹在组件中，而不是插入一个空组件让你填写。

使用方法：选中要包裹的内容，然后在命令面板中运行 **Snippets: Surround With** 并选择一个组件。可用的 snippet 包括 `AccordionGroup`、`CardGroup`、`CodeGroup`、`Expandable`、`Frame`、`RequestExample`、`ResponseExample` 和围栏代码块。

<div id="settings">
  ## 设置
</div>

| 设置                                        | 默认值                  | 说明                                       |
| ----------------------------------------- | -------------------- | ---------------------------------------- |
| `mintlify.diagnostics.enabled`            | `true`               | 报告未知组件、未知属性、缺少的必需属性和无法解析的 snippet 导入。    |
| `mintlify.warnAboutConflictingExtensions` | `true`               | 当你在 Mintlify MDX 扩展之外还安装了其他 MDX 扩展时发出警告。 |
| `mintlify.preview.command`                | `mint dev --no-open` | 用于启动预览服务器的命令，从项目根目录运行。                   |
| `mintlify.preview.followScroll`           | `true`               | 将预览滚动到最接近编辑器顶部的标题处。                      |

`mintlify.preview.command` 是用户级设置，工作区无法覆盖它。这可以防止克隆的仓库在你打开预览时在你的机器上运行任意命令。

<div id="commands">
  ## 命令
</div>

在命令面板中运行以下命令：

| 命令                                    | 说明                       |
| ------------------------------------- | ------------------------ |
| **Mintlify: Preview Mintlify**        | 为当前文件打开预览面板。             |
| **Mintlify: Stop preview server**     | 停止正在运行的预览服务器。            |
| **Mintlify: Show detected docs root** | 显示扩展解析到的 `docs.json` 文件。 |
| **Mintlify: Open component docs**     | 打开光标所在组件的文档。             |
| **Mintlify: Restart language server** | 重启语言服务器。                 |

<div id="conflicting-extensions">
  ## 冲突的扩展
</div>

其他 MDX 扩展为 `.mdx` 文件提供各自的语法高亮和语言功能，会与此扩展冲突。请禁用其他 MDX 扩展，以避免重复的提示和不一致的高亮。

对于代码格式化，请将 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) 与此扩展搭配使用，或运行 [`mint format`](/docs/zh/cli/commands#mint-format)。

<div id="troubleshooting">
  ## 故障排除
</div>

<AccordionGroup>
  <Accordion title="组件被报告为未知">
    扩展相对于文档根目录解析组件。运行 **Mintlify: Show detected docs root**，确认它找到了正确的 `docs.json` 文件。如果根目录错误或缺失，请将包含 `docs.json` 文件的文件夹作为工作区打开。

    如果根目录正确，请运行 **Mintlify: Restart language server**。
  </Accordion>

  <Accordion title="自动补全和高亮表现不一致">
    很可能有另一个 MDX 扩展也处于激活状态。打开扩展视图，搜索 `mdx`，并在此工作区中禁用其他所有 MDX 扩展。
  </Accordion>

  <Accordion title="预览无法启动">
    打开 **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`](/docs/zh/cli/commands#mint-validate) 查找配置错误。
  </Accordion>

  <Accordion title="Snippet 导入被报告为无法解析">
    绝对导入路径从文档根目录解析，而不是从当前文件解析。请确认该路径与 snippet 文件相对于 `docs.json` 文件的位置一致，并且检测到的根目录是正确的。
  </Accordion>
</AccordionGroup>


## Related topics

- [安装 CLI](/docs/zh/cli/install.md)
- [Mintlify CLI](/docs/zh/cli/index.md)
- [本地预览](/docs/zh/cli/preview.md)