Mintlify MDX

Language support for Mintlify documentation projects in VS Code.

Features

• Syntax highlighting for MDX: frontmatter (YAML), import/export blocks, JSX components and attributes, {expressions}, JSX comments, and fenced code blocks (including ```mdx). Markdown inside <MDX>…</MDX> within an expression ({cond ? <MDX>…</MDX> : null}) is highlighted as MDX rather than JSX text.
• Autocomplete for every built-in Mintlify component after <, for their props inside a tag, for enumerated prop values (<Badge color="…">), for matching close tags after </, and for components imported from snippets. className, id and style are offered on every component and HTML element, and inside className="…" you get Tailwind utility classes (with variants like md: and hover:).
• Hover docs for components and props, with a link to the Mintlify docs. Hovering a snippet component previews the snippet file.
• Go to definition (Cmd/Ctrl+click) on snippet components, import paths, and href/src attributes that point to local pages.
• Diagnostics: unresolved snippet imports, unknown components, unknown/duplicate props, invalid enum values, missing required props, and unclosed or mismatched tags, including plain HTML elements like <div>. Content inside <MDX> fragments in expressions is checked like page content.
• .mintignore: files your .mintignore excludes (plus the ones Mintlify always skips, like README.md and node_modules) are left out of path completions. An excluded page gets a note that it won't be published, imports and links that point at excluded files are flagged, and excluded pages are marked in the docs sidebar. .mintignore itself gets ignore-file syntax highlighting.
• Folding: collapse component and HTML tag regions (<Accordion>…</Accordion>), heading sections, frontmatter, code blocks, and JSX comments from the gutter chevrons.
• docs.json IntelliSense: docs.json is validated against the official schema (https://mintlify.com/docs.json), so you get completion for every supported key (top-level and nested: navigation, colors, navbar, footer, integrations, …), enum values (theme, appearance.default, …), hover descriptions, and red squiggles for missing required or invalid values. This uses VS Code's built-in JSON language features, so it needs network access to download the schema once (see json.schemaDownload.enable); it also works in any editor if the file has "$schema": "https://mintlify.com/docs.json".
• docs.json detection: the docs root is found by walking up from the open file, so absolute imports like /snippets/foo.mdx resolve correctly. The status bar shows the detected project.
• Conflict warning: if another MDX extension (for example unifiedjs.vscode-mdx) is installed in a Mintlify project, you get a one-time prompt to disable it.
• Visual editor: every .mdx file can open in Visual Mode, a rich editor for the page like the one in the Mintlify dashboard: headings, lists, tables, links, callouts, cards, steps, tabs, accordions, code blocks with language/filename headers, images, and more, all editable in place. Switch between them with the editor picker at the right end of the breadcrumbs row (Visual Mode ⇧⌘V ⌄ / Text Editor ⌄) or Cmd/Ctrl+Shift+V; the gear in the title bar picks which one .mdx files open with by default. Markdown shortcuts work (# , - , **bold**, `code`) and the toolbar inserts components. Edits are written back as MDX through the same converter as mint format; components the editor doesn't know are kept as-is.
• Docs sidebar: the Mintlify activity-bar view mirrors the 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. Page labels come from sidebarTitle or title, and selecting a page opens it in the visual editor. 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 saves the change to docs.json. The tree follows the active page and reloads when docs.json or a page changes.
• Snippet forms: in Visual Mode, a component imported from a snippet (import { ProductCard } from "/snippets/product-card.mdx") is shown as a form with one input per prop instead of an opaque <ProductCard … /> chip. Fields are inferred from the component's destructured props and their defaults; add a doc comment to get typed inputs, labels, and required markers (see Describing snippet props). Imported snippets also appear in the + Insert menu and the / menu.
• Live preview: right-click an .mdx file → Preview Mintlify runs mint dev and shows the page beside the editor. The preview toolbar has back/forward/reload, an address box (type a path like /quickstart and press Enter), a Follow editor toggle that switches pages as you change files, and an Open in browser button. Cmd/Ctrl+F opens a find bar inside the previewed page (Enter / Shift+Enter step through matches, Esc closes).
• Preview as groups: right-click → Preview as groups… (or View as… in the preview toolbar) lists the groups your pages declare in groups: frontmatter, plus any you type, and opens another preview tab running mint dev --groups … on its own port. Each tab is a separate server mocking a signed-in user in those groups, so you can compare views side by side. Closing a group tab stops its server. Needs mint 4.2.810 or later, the first CLI that keeps each port's preview separate. A page whose frontmatter groups (names, or includes/excludes rules, evaluated the way mint does) leave those users out shows a 404 stand-in, as a site with authentication would, with a Show anyway button. Sites that use personalization (where such pages still open by URL) can set mintlify.preview.restrictedPages to "show". Group tabs show a banner naming the groups being previewed. This is a local approximation that doesn't use your site's real authentication or identity provider, so always confirm access on the deployed site before relying on a page being gated.
• Surround snippets (AccordionGroup, CardGroup, CodeGroup, Frame, …) for wrapping selected text.

Describing snippet props

Visual Mode builds a form for every component imported from a snippet. Without any annotation the inputs are guessed: a default of true makes a checkbox, 2 a number box, a prop called icon or logo an image path with a thumbnail, href/url a link, description/summary a multi-line box, and so on. To control it, document the props with JSDoc @param tags in a comment right before the component. In .jsx/.tsx files that is a /** … */ block; in .mdx snippets use an MDX comment, {/* … */}, so it doesn't render as text:

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

Brackets ([name]) mark a prop optional; a documented prop without brackets shows a required marker. [name=value] supplies a default when the destructuring has none. The first line of the comment is the description shown in the form header and the Insert menu. children is never a field: the tag's body is left as written and summarized under the form (switch to Markdown to edit it).

Settings

Commands

• Mintlify: Show detected docs root
• Mintlify: Open component docs
• Mintlify: Preview as groups…
• Mintlify: Open preview in browser (for dev tools, browser extensions, etc.)
• Mintlify: Stop preview servers
• Mintlify: Restart language server