From f3a690c94e6989409f59c1e05d682818b261cc33 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 25 Aug 2026 14:50:06 -0700 Subject: [PATCH 1/4] docs: document the Mintlify MDX VS Code extension Add a page for the Mintlify MDX extension (mintlify.mintlify-snippets), which had no coverage outside a 2024 changelog entry describing its snippets-only predecessor. Covers autocomplete, diagnostics, hover docs, go-to-definition, docs.json schema validation, the in-editor preview panel, surround snippets, all four settings, and all five commands, verified against the shipped v2.0.0 manifest and bundle. Replace the unifiedjs.vscode-mdx recommendation in cli/install.mdx. Our extension warns users to disable that one, so the previous guidance routed them into a known conflict. Co-Authored-By: Claude Opus 5 (1M context) --- cli/index.mdx | 1 + cli/install.mdx | 10 ++- cli/preview.mdx | 4 + cli/vs-code-extension.mdx | 151 ++++++++++++++++++++++++++++++++++++++ docs.json | 1 + 5 files changed, 163 insertions(+), 4 deletions(-) create mode 100644 cli/vs-code-extension.mdx diff --git a/cli/index.mdx b/cli/index.mdx index 5f2eeeb91c..a0e5cadeae 100644 --- a/cli/index.mdx +++ b/cli/index.mdx @@ -54,5 +54,6 @@ Run `mint config` to set persistent defaults like your documentation subdomain. ## Next steps - [Install the CLI](/cli/install): Get the CLI installed and ready to use. +- [VS Code extension](/cli/vs-code-extension): Add autocomplete, inline error checking, and an in-editor preview. - [Preview locally](/cli/preview): Run a local development server with search and assistant support. - [Commands](/cli/commands): Complete reference for all commands and flags. diff --git a/cli/install.mdx b/cli/install.mdx index e8fbba5be1..c076a456f3 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -113,12 +113,14 @@ If `mint update` is not available on your version, reinstall the CLI with the la ``` -## Formatting +## Editor support -For syntax highlighting and code formatting in MDX files, use the following extensions: +For syntax highlighting, autocomplete, and error checking in MDX files, use the following extensions: -- **Cursor, Devin Desktop, VS Code**: [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) -- **JetBrains**: [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm) +- **Cursor, Devin Desktop, VS Code**: [Mintlify MDX extension](/cli/vs-code-extension) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for formatting. +- **JetBrains**: [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm). + +You can also format MDX files with [`mint format`](/cli/commands#mint-format). ## Troubleshooting diff --git a/cli/preview.mdx b/cli/preview.mdx index a7263ca9da..26a6725845 100644 --- a/cli/preview.mdx +++ b/cli/preview.mdx @@ -31,6 +31,10 @@ To generate a preview without installing the CLI globally, run: npx mint dev ``` + + If you write in VS Code or Cursor, the [Mintlify MDX extension](/cli/vs-code-extension) runs this preview in a panel beside your editor and scrolls it to match the page you are editing. + + ## Log in for search and assistant You must authenticate the CLI with your Mintlify account to enable search and the [assistant](/assistant/index). diff --git a/cli/vs-code-extension.mdx b/cli/vs-code-extension.mdx new file mode 100644 index 0000000000..f26ece9c0a --- /dev/null +++ b/cli/vs-code-extension.mdx @@ -0,0 +1,151 @@ +--- +title: "VS Code extension" +description: "Install the Mintlify MDX extension for autocomplete, inline diagnostics, hover documentation, and an in-editor preview while you write MDX locally." +keywords: ["VS Code", "extension", "Cursor", "MDX", "autocomplete", "diagnostics", "IntelliSense", "preview", "editor"] +--- + +The Mintlify MDX extension adds language support for Mintlify projects to VS Code. It knows every built-in component and its properties, so you get autocomplete as you type, and it reports unknown components, invalid properties, and unresolved snippet imports directly in your editor instead of when your build fails. + +The extension also runs a live preview inside your editor, so you can write and see rendered output without switching to a browser. + +The extension works in VS Code and in editors built on it, including Cursor. + +## Prerequisites + +- VS Code 1.85.0 or newer +- A documentation directory with a valid `docs.json` file +- The [Mintlify CLI](/cli/install), for the in-editor preview only + +## Install the extension + +Install from the command line: + +```bash +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. Select **Install**. + +You can also install from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). + + + The marketplace lists the extension as **Mintlify MDX**, but its identifier is `mintlify.mintlify-snippets` because it started as a snippets-only extension. Searching for "Mintlify" also returns several older extensions for unrelated products, so match the identifier to confirm you have the right one. + + +The extension activates when you open an `.mdx` file or a workspace containing a `docs.json` file. + +## Autocomplete + +Type `<` to see every built-in component. Inside a tag, autocomplete suggests that component's properties, and enumerated values for properties that accept a fixed set of options, like ``. Type ` + Use the in-editor preview while you write individual pages, and [`mint dev`](/cli/preview) 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. + +Because these snippets wrap a selection, typing the component name in your file inserts an empty component instead. + +## Settings + +| Setting | Default | Description | +| --- | --- | --- | +| `mintlify.diagnostics.enabled` | `true` | Report unknown components, unknown properties, missing required properties, and unresolved snippet imports. | +| `mintlify.warnAboutConflictingExtensions` | `true` | Warn when you have another MDX extension installed alongside this one. | +| `mintlify.preview.command` | `mint dev --no-open` | Command used to start the preview server, run from your docs root. | +| `mintlify.preview.followScroll` | `true` | Scroll the preview to the heading nearest the top of your editor. | + +`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: + +| Command | Description | +| --- | --- | +| **Mintlify: Preview Mintlify** | Open the preview panel for the current file. | +| **Mintlify: Stop preview server** | Stop the running preview server. | +| **Mintlify: Show detected docs root** | Show which `docs.json` file the extension resolved. | +| **Mintlify: Open component docs** | Open the documentation for the component at your cursor. | +| **Mintlify: Restart language server** | Restart the language server. | + +## Conflicting extensions + +Other MDX extensions provide their own syntax highlighting and language features for `.mdx` files, which conflict with this extension. If you have one installed in a Mintlify project, the extension prompts you to disable it. Disable other MDX extensions to avoid duplicate suggestions and inconsistent highlighting. + +For code formatting, use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) alongside this extension, or run [`mint format`](/cli/commands#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`](/cli/commands#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. + + diff --git a/docs.json b/docs.json index c643ccf213..fa6edace76 100644 --- a/docs.json +++ b/docs.json @@ -37,6 +37,7 @@ "root": "cli/index", "pages": [ "cli/install", + "cli/vs-code-extension", "cli/preview", "cli/commands" ] From 8dc1af72c7cce0905e1f81be55584af6e2d875cb Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 25 Aug 2026 14:53:28 -0700 Subject: [PATCH 2/4] docs: accept all prefetch word forms in Vale vocabulary The vocabulary had a bare `prefetching` entry, so `prefetches` and `prefetched` in cli/preview.mdx were flagged as misspellings. Vale wraps entries in \b, so the bare form matches only that one variant. Use `(?i)prefetch(es|ed|ing)?` rather than the uncased suffix pattern used by neighboring entries. An uncased entry also generates a case-enforcing Vale.Terms rule, which would flag a sentence-initial "Prefetching" as an error. "prefetch" has no canonical capitalization worth enforcing, so the non-enforcing form avoids a latent false positive. Co-Authored-By: Claude Opus 5 (1M context) --- .vale/styles/config/vocabularies/Mintlify/accept.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index 575cedf8b0..ed010ced0d 100644 --- a/.vale/styles/config/vocabularies/Mintlify/accept.txt +++ b/.vale/styles/config/vocabularies/Mintlify/accept.txt @@ -346,7 +346,7 @@ PostgreSQL Postman PowerShell PR -prefetching +(?i)prefetch(es|ed|ing)? prefill(s|ing|ed)? preloaded prepend(ed|ing)? From 0064df25dd040aa6ecaf7ff62e5001dd5c9ce77d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 25 Aug 2026 14:56:19 -0700 Subject: [PATCH 3/4] rename page --- cli/index.mdx | 2 +- cli/install.mdx | 2 +- cli/{vs-code-extension.mdx => mdx-extension.mdx} | 4 ++-- cli/preview.mdx | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) rename cli/{vs-code-extension.mdx => mdx-extension.mdx} (98%) diff --git a/cli/index.mdx b/cli/index.mdx index a0e5cadeae..ea54fbc3bd 100644 --- a/cli/index.mdx +++ b/cli/index.mdx @@ -54,6 +54,6 @@ Run `mint config` to set persistent defaults like your documentation subdomain. ## Next steps - [Install the CLI](/cli/install): Get the CLI installed and ready to use. -- [VS Code extension](/cli/vs-code-extension): Add autocomplete, inline error checking, and an in-editor preview. +- [Mintlify MDX extension](/cli/mdx-extension): Add autocomplete, inline error checking, and an in-editor preview. - [Preview locally](/cli/preview): Run a local development server with search and assistant support. - [Commands](/cli/commands): Complete reference for all commands and flags. diff --git a/cli/install.mdx b/cli/install.mdx index c076a456f3..6dc89c4bd5 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -117,7 +117,7 @@ If `mint update` is not available on your version, reinstall the CLI with the la For syntax highlighting, autocomplete, and error checking in MDX files, use the following extensions: -- **Cursor, Devin Desktop, VS Code**: [Mintlify MDX extension](/cli/vs-code-extension) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for formatting. +- **Cursor, Devin Desktop, VS Code**: [Mintlify MDX extension](/cli/mdx-extension) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for formatting. - **JetBrains**: [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm). You can also format MDX files with [`mint format`](/cli/commands#mint-format). diff --git a/cli/vs-code-extension.mdx b/cli/mdx-extension.mdx similarity index 98% rename from cli/vs-code-extension.mdx rename to cli/mdx-extension.mdx index f26ece9c0a..4b8c1f1093 100644 --- a/cli/vs-code-extension.mdx +++ b/cli/mdx-extension.mdx @@ -1,7 +1,7 @@ --- -title: "VS Code extension" +title: "Mintlify MDX extension" description: "Install the Mintlify MDX extension for autocomplete, inline diagnostics, hover documentation, and an in-editor preview while you write MDX locally." -keywords: ["VS Code", "extension", "Cursor", "MDX", "autocomplete", "diagnostics", "IntelliSense", "preview", "editor"] +keywords: ["Cursor", "MDX", "autocomplete", "diagnostics", "IntelliSense", "preview", "editor"] --- The Mintlify MDX extension adds language support for Mintlify projects to VS Code. It knows every built-in component and its properties, so you get autocomplete as you type, and it reports unknown components, invalid properties, and unresolved snippet imports directly in your editor instead of when your build fails. diff --git a/cli/preview.mdx b/cli/preview.mdx index 26a6725845..c8bbadc047 100644 --- a/cli/preview.mdx +++ b/cli/preview.mdx @@ -32,7 +32,7 @@ npx mint dev ``` - If you write in VS Code or Cursor, the [Mintlify MDX extension](/cli/vs-code-extension) runs this preview in a panel beside your editor and scrolls it to match the page you are editing. + If you write in VS Code or Cursor, the [Mintlify MDX extension](/cli/mdx-extension) runs this preview in a panel beside your editor and scrolls it to match the page you are editing. ## Log in for search and assistant From 1ebce22eb2b6308ca1a6c867b359fb550412ecf1 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 25 Aug 2026 15:06:51 -0700 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=92=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cli/mdx-extension.mdx | 34 +++++++++++++--------------------- 1 file changed, 13 insertions(+), 21 deletions(-) diff --git a/cli/mdx-extension.mdx b/cli/mdx-extension.mdx index 4b8c1f1093..594e4f44fb 100644 --- a/cli/mdx-extension.mdx +++ b/cli/mdx-extension.mdx @@ -4,12 +4,10 @@ description: "Install the Mintlify MDX extension for autocomplete, inline diagno keywords: ["Cursor", "MDX", "autocomplete", "diagnostics", "IntelliSense", "preview", "editor"] --- -The Mintlify MDX extension adds language support for Mintlify projects to VS Code. It knows every built-in component and its properties, so you get autocomplete as you type, and it reports unknown components, invalid properties, and unresolved snippet imports directly in your editor instead of when your build fails. +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. -The extension works in VS Code and in editors built on it, including Cursor. - ## Prerequisites - VS Code 1.85.0 or newer @@ -28,21 +26,17 @@ Or install from within your editor: 1. Open the Extensions view. 2. Search for `@id:mintlify.mintlify-snippets`. -3. Select **Install**. +3. Click **Install**. You can also install from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). - - The marketplace lists the extension as **Mintlify MDX**, but its identifier is `mintlify.mintlify-snippets` because it started as a snippets-only extension. Searching for "Mintlify" also returns several older extensions for unrelated products, so match the identifier to confirm you have the right one. - - The extension activates when you open an `.mdx` file or a workspace containing a `docs.json` file. ## Autocomplete -Type `<` to see every built-in component. Inside a tag, autocomplete suggests that component's properties, and enumerated values for properties that accept a fixed set of options, like ``. Type `CMD (macOS) or CTRL (Windows) and click to navigate to the definition of: - Snippet components. - Import paths. @@ -75,13 +69,13 @@ The extension finds your docs root by walking up from the open file until it fin ## Configuration validation -The extension validates `docs.json` against the [Mintlify schema](https://mintlify.com/docs.json), which gives you autocomplete and inline errors for configuration properties. You do not need to add a `$schema` property to your `docs.json` file for this to work in your editor. +The extension validates `docs.json` against the [Mintlify schema](https://mintlify.com/docs.json). ## 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. As you scroll, the preview follows to the heading nearest the top of 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 runs `mint dev` in the background, so it needs the [Mintlify CLI](/cli/install) installed. Because `mint dev` executes your project's code, you must trust the workspace. The URL of the running server appears in the status bar. Select it to stop the server, or run **Mintlify: Stop preview server**. +In-editor previews require the [Mintlify CLI](/cli/install). 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. @@ -95,15 +89,13 @@ The extension includes snippets that wrap selected text in a component, rather t 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. -Because these snippets wrap a selection, typing the component name in your file inserts an empty component instead. - ## Settings | Setting | Default | Description | | --- | --- | --- | | `mintlify.diagnostics.enabled` | `true` | Report unknown components, unknown properties, missing required properties, and unresolved snippet imports. | -| `mintlify.warnAboutConflictingExtensions` | `true` | Warn when you have another MDX extension installed alongside this one. | -| `mintlify.preview.command` | `mint dev --no-open` | Command used to start the preview server, run from your docs root. | +| `mintlify.warnAboutConflictingExtensions` | `true` | Warn when you have another MDX extension installed alongside the Mintlify MDX extension. | +| `mintlify.preview.command` | `mint dev --no-open` | Command used to start the preview server, run from your project root. | | `mintlify.preview.followScroll` | `true` | Scroll the preview to the heading nearest the top of your editor. | `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. @@ -122,9 +114,9 @@ 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. If you have one installed in a Mintlify project, the extension prompts you to disable it. Disable other MDX extensions to avoid duplicate suggestions and inconsistent highlighting. +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](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) alongside this extension, or run [`mint format`](/cli/commands#mint-format). +For code formatting, use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) alongside this extension or run [`mint format`](/cli/commands#mint-format). ## Troubleshooting