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

​
前提条件

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

​
安装扩展

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

​
自动补全

输入 < 即可查看所有内置组件。自动补全会在标签内提示组件的属性和值、在 </ 后匹配闭合标签，以及像 <Badge color="…"> 这样的枚举属性值。 除内置组件外，扩展还会提示你从可复用 snippet 导入的组件。className、id 和 style 会在所有组件和 HTML 元素上提供，在 className="…" 内输入时会提示 Tailwind 实用类，包括像 md: 和 hover: 这样的变体。

​
诊断

扩展会在“问题”面板中报告问题，并在你编写时在文件中以下划线标出：
  • 未知组件。
  • 未知或重复的属性。
  • 枚举属性的无效值。
  • 缺少必需属性。
  • 未闭合或不匹配的标签，包括像 <div> 这样的普通 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 标签区域，例如 <Accordion>…</Accordion>。
  • 标题小节。
  • Frontmatter。
  • 代码块。
  • JSX 注释。

​
配置校验

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

​
可视化模式

在可视化模式下打开任意 .mdx 文件，即可像在 Mintlify 仪表板中那样在富文本编辑器中编辑页面。标题、列表、表格、链接、提示框、卡片、步骤、选项卡、折叠面板、代码块和图片都可以就地编辑。 在可视化模式和文本编辑器之间切换：
  • 按 Cmd+Shift+V（macOS）或 Ctrl+Shift+V（Windows）。
  • 或使用面包屑行右端的编辑器选择器。
使用标题栏中的齿轮图标可选择 .mdx 文件默认使用哪个编辑器打开。 输入时 Markdown 快捷方式生效（# 表示标题，- 表示列表项，**bold**、`code`），工具栏和 / 菜单可用于插入组件。编辑内容会通过与 mint format 相同的转换器写回为 MDX。可视化模式无法识别的组件会按原样保留。

​
Snippet 表单

在可视化模式下，从 snippet 导入的组件会显示为一个表单，每个 prop 对应一个输入，而不是一个不透明的标签。可视化模式会根据组件函数签名中的 prop 及其默认值推断字段。默认值为 true 会变成复选框，2 会变成数字框，icon 或 logo 会变成带缩略图的图片路径，href 或 url 会变成链接。 要控制输入项，请在导出前使用 JSDoc @param 注释来对组件进行文档说明。在 .jsx 和 .tsx 文件中使用 /** … */ 块。在 .mdx snippet 中，使用 MDX 注释（{/* … */}），这样它不会被渲染：
以下类型会生成对应的表单输入： 方括号（[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。预览服务器默认在端口 3939 上运行，以避免与端口 3000 上的应用冲突。可通过 mintlify.preview.port 设置更改端口。 运行中服务器的 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本地预览