Skip to main content
The Mintlify MDX extension adds language support for Mintlify projects to VS Code, Cursor, Devin Desktop, and other editors that support the VS Code extension API. The extension knows every built-in component and property, so you get autocomplete as you type, and it reports unknown components, invalid properties, and unresolved snippet imports. The extension also runs a live preview inside your editor, so you can write and see rendered output without switching to a browser.

​
Prerequisites

  • VS Code 1.85.0 or newer
  • A documentation directory with a valid docs.json file
  • The Mintlify CLI, for the in-editor preview only

​
Install the extension

Install from the command line:
Or install from within your editor:
  1. Open the Extensions view.
  2. Search for @id:mintlify.mintlify-snippets.
  3. Click Install.
You can also install from the Visual Studio Marketplace. The extension activates when you open an .mdx file or a workspace containing a docs.json file.

​
Autocomplete

Type < to view every built-in component. Autocomplete suggests components’ properties and values inside tags. The extension suggests components that you import from reusable snippets alongside built-in ones.

​
Diagnostics

The extension reports problems in the Problems panel and underlines them in your file as you write:
  • Unknown components.
  • Unknown or duplicate properties.
  • Invalid values for enumerated properties.
  • Missing required properties.
  • Unclosed or mismatched tags.
  • Unresolved snippet imports.
These classes of error cause build failures, so fix them as you write to avoid failed deployments. To turn diagnostics off, set mintlify.diagnostics.enabled to false.

​
Hover documentation

Hover over a component or property to see what it does and a link to its page in the Mintlify documentation. Hovering over a snippet component previews the contents of the snippet file.

​
Go to definition

Hold CMD (macOS) or CTRL (Windows) and click to navigate to the definition of:
  • Snippet components.
  • Import paths.
  • href and src attributes that point to local pages.
The extension finds your docs root by walking up from the open file until it finds docs.json, so absolute imports like /snippets/example.mdx resolve correctly. The detected project appears in the status bar. To check which root the extension is using, run Mintlify: Show detected docs root from the command palette.

​
Configuration validation

The extension validates docs.json against the Mintlify schema.

​
Preview in your editor

Open an .mdx file and select the preview icon in the editor title bar, or right-click the file and select Preview Mintlify. A preview panel opens beside your editor and renders the page. In-editor previews require the Mintlify CLI. The URL of the running server appears in the status bar. Select it to stop the server, or run Mintlify: Stop preview server. To see the output of the underlying mint dev process, open the Mintlify Preview output channel.
Use the in-editor preview while you write individual pages, and mint dev in a browser when you want to test navigation, search, or authentication across your whole site.

​
Wrap content in components

The extension includes snippets that wrap selected text in a component, rather than inserting an empty component for you to fill in. To use them, select the content you want to wrap, then run Snippets: Surround With from the command palette and choose a component. Snippets are available for AccordionGroup, CardGroup, CodeGroup, Expandable, Frame, RequestExample, ResponseExample, and fenced code blocks.

​
Settings

mintlify.preview.command is a user setting, so a workspace cannot override it. This prevents a cloned repository from running an arbitrary command on your machine when you open a preview.

​
Commands

Run these from the command palette:

​
Conflicting extensions

Other MDX extensions provide their own syntax highlighting and language features for .mdx files, which conflict with this extension. Disable other MDX extensions to avoid duplicate suggestions and inconsistent highlighting. For code formatting, use Prettier alongside this extension or run mint format.

​
Troubleshooting

The extension resolves components relative to your docs root. Run Mintlify: Show detected docs root to confirm it found the correct docs.json file. If the root is wrong or missing, open the folder containing your docs.json file as your workspace.If the root is correct, run Mintlify: Restart language server.
Another MDX extension is likely also active. Open the Extensions view, search for mdx, and disable any other MDX extensions in this workspace.
Open the Mintlify Preview output channel to see the error from mint dev.
  • could not run "mint dev --no-open": The CLI is not installed. Install it with npm i -g mint.
  • Trust the workspace first: Trust the workspace through Manage Workspace Trust.
  • no docs.json found above this file: Open the folder containing your docs.json file as your workspace.
  • Invalid docs.json: Run mint validate to find the configuration error.
Absolute import paths resolve from your docs root, not from your file. Confirm the path matches the location of the snippet file relative to your docs.json file, and that the detected root is correct.

Related topics

Install the CLIMintlify CLIPreview locally