diff --git a/.vale/styles/config/vocabularies/Mintlify/accept.txt b/.vale/styles/config/vocabularies/Mintlify/accept.txt index 575cedf8b..ed010ced0 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)? diff --git a/cli/index.mdx b/cli/index.mdx index 5f2eeeb91..ea54fbc3b 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. +- [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 e8fbba5be..6dc89c4bd 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/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). ## Troubleshooting diff --git a/cli/mdx-extension.mdx b/cli/mdx-extension.mdx new file mode 100644 index 000000000..594e4f44f --- /dev/null +++ b/cli/mdx-extension.mdx @@ -0,0 +1,143 @@ +--- +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: ["Cursor", "MDX", "autocomplete", "diagnostics", "IntelliSense", "preview", "editor"] +--- + +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](/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. Click **Install**. + +You can also install from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). + +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](/create/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](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. + +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. + + + 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. + +## 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 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. + +## 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. 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/cli/preview.mdx b/cli/preview.mdx index a7263ca9d..c8bbadc04 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/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 You must authenticate the CLI with your Mintlify account to enable search and the [assistant](/assistant/index). diff --git a/docs.json b/docs.json index c643ccf21..fa6edace7 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" ]