Mintlify MDX extension

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 opens .mdx files in a visual editor and 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:

code --install-extension mintlify.mintlify-snippets

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, closing tags after </, and enumerated prop values like <Badge color="…">.

The extension suggests components that you import from reusable snippets alongside built-in ones. className, id, and style are offered on every component and HTML element, and typing inside className="…" suggests Tailwind utility classes, including variants like md: and hover:.

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, including plain HTML elements like <div>.
• 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.

Folding

Use the gutter chevrons to collapse regions of a page:

• Component and HTML tag regions, like <Accordion>…</Accordion>.
• Heading sections.
• Frontmatter.
• Code blocks.
• JSX comments.

Configuration validation

The extension validates docs.json against the Mintlify schema.

Visual mode

Open any .mdx file in visual mode to edit the page in a rich editor like the one in the Mintlify dashboard, with headings, lists, tables, links, callouts, cards, steps, tabs, accordions, code blocks, and images all editable in place.

To switch between visual mode and the text editor:

• Press Cmd+Shift+V (macOS) or Ctrl+Shift+V (Windows).
• Or use the editor picker at the right end of the breadcrumbs row.

Use the gear icon in the title bar to pick which editor .mdx files open with by default.

Markdown shortcuts work as you type (# for a heading, - for a list item, **bold**, `code`), and the toolbar and / menu insert components. Visual mode writes edits back as MDX through the same converter as mint format, and preserves unfamiliar components as written.

Snippet forms

In visual mode, a component imported from a snippet appears as a form with one input per prop instead of an opaque tag. Visual mode infers fields from the props in the component’s function signature and their default values, so a default of true becomes a checkbox, 2 becomes a number box, icon or logo becomes an image path with a thumbnail, and href or url becomes a link.

To control the inputs, document the component with a JSDoc @param comment right before the export. In .jsx and .tsx files use a /** … */ block. In .mdx snippets, use an MDX comment ({/* … */}) so it doesn’t render:

{/*
  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 }) => ( ... );

The following types produce the matching form inputs:

Brackets ([name]) mark a prop optional. A documented prop without brackets shows a required marker. [name=value] supplies a default when the component’s signature doesn’t already have one. The first line of the comment is the description shown in the form header and the Insert menu.

children is never a field. Visual mode leaves the tag’s body as written and summarizes it under the form. Switch to the text editor to edit it.

Imported snippets also appear in the + Insert menu and the / menu.

Docs sidebar

The Mintlify view in the activity bar mirrors your docs.json navigation tree. Top-level products and tabs stay at the root, with their navigation nested in expandable rows. The sidebar uses icons from docs.json and page frontmatter, and page labels come from sidebarTitle or title. Selecting a page opens it in visual mode.

Use the + action to add groups, tabs, dropdowns, anchors, languages, products, and versions. Drag rows to reorder them, or drop a page on a group to move it to the top of that group. The tree moves immediately, then Mintlify saves the change to docs.json.

The tree follows the active page and reloads when docs.json or a page changes.

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.

The preview toolbar has back, forward, and reload buttons, an address box, and a Follow editor toggle. Type a path like /quickstart in the address box and press Enter to navigate to that page. With Follow editor on, the preview switches pages as you change files in your editor.

Press Cmd+F (macOS) or Ctrl+F (Windows) inside the preview to open a find bar for the rendered page. Enter and Shift+Enter step through matches. Esc closes the find bar.

The in-editor preview renders in an iframe, so browser dev tools can’t reach it. Select the Open in browser button in the preview toolbar, or run Mintlify: Open preview in browser, to open the page in your browser instead.

In-editor previews require the Mintlify CLI. The preview server runs on port 3939 by default so it doesn’t collide with apps on port 3000. Change the port with the mintlify.preview.port setting.

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.

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