Skip to main content
Mintlify MDX 扩展为 VS Code、Cursor、Devin Desktop 以及其他支持 VS Code 扩展 API 的编辑器提供 Mintlify 项目的语言支持。该扩展了解每个内置组件和属性，因此你在输入时可以获得自动补全，它还会报告未知组件、无效属性和无法解析的 snippet 导入。 该扩展还会在编辑器内运行实时预览，让你无需切换到浏览器即可边写作边查看渲染结果。

​
前提条件

  • VS Code 1.85.0 或更高版本
  • 包含有效 docs.json 文件的文档目录
  • Mintlify CLI（仅编辑器内预览需要）

​
安装扩展

从命令行安装：
或在编辑器内安装：
  1. 打开扩展视图。
  2. 搜索 @id:mintlify.mintlify-snippets。
  3. 点击 Install。
你也可以从 Visual Studio Marketplace 安装。 当你打开 .mdx 文件或包含 docs.json 文件的工作区时，扩展会自动激活。

​
自动补全

输入 < 即可查看所有内置组件。自动补全会在标签内提示组件的属性和值。 除内置组件外，扩展还会提示你从可复用 snippet 导入的组件。

​
诊断

扩展会在“问题”面板中报告问题，并在你编写时在文件中以下划线标出：
  • 未知组件。
  • 未知或重复的属性。
  • 枚举属性的无效值。
  • 缺少必需属性。
  • 未闭合或不匹配的标签。
  • 无法解析的 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。

​
配置校验

扩展会根据 Mintlify 架构校验 docs.json。

​
在编辑器中预览

打开一个 .mdx 文件，选择编辑器标题栏中的预览图标，或右键点击文件并选择 Preview Mintlify。预览面板会在编辑器旁打开并渲染页面。 编辑器内预览需要 Mintlify CLI。运行中服务器的 URL 会显示在状态栏中。选择它可以停止服务器，或运行 Mintlify: Stop preview server。 要查看底层 mint dev 进程的输出，请打开 Mintlify Preview 输出通道。
编写单个页面时使用编辑器内预览；当你想在整个站点范围内测试导航、搜索或身份验证时，在浏览器中使用 mint dev。

​
用组件包裹内容

扩展包含的 snippet 会将选中的文本包裹在组件中，而不是插入一个空组件让你填写。 使用方法：选中要包裹的内容，然后在命令面板中运行 Snippets: Surround With 并选择一个组件。可用的 snippet 包括 AccordionGroup、CardGroup、CodeGroup、Expandable、Frame、RequestExample、ResponseExample 和围栏代码块。

​
设置

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

​
命令

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

​
冲突的扩展

其他 MDX 扩展为 .mdx 文件提供各自的语法高亮和语言功能，会与此扩展冲突。请禁用其他 MDX 扩展，以避免重复的提示和不一致的高亮。 对于代码格式化，请将 Prettier 与此扩展搭配使用，或运行 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 查找配置错误。
绝对导入路径从文档根目录解析，而不是从当前文件解析。请确认该路径与 snippet 文件相对于 docs.json 文件的位置一致，并且检测到的根目录是正确的。

相关主题

安装 CLIMintlify CLI本地预览