MDX for Visual Studio Code

Visual Studio Code extension to add language support for MDX.

Install
Settings
TypeScript
Plugins
Syntax highlighting
- Custom Languages in Code Blocks
ESLint
Auto-close tags
Prettier
Sponsor
Changelog
License

Install

Get it on the VS Code Marketplace or install it by using Quick Open (Ctrl + P) and running the following:

ext install unifiedjs.vscode-mdx

Settings

All MDX language server configurations can be configured via Visual Studio Code settings. MDX for VSCode supports the following additional setting:

mdx.server.enable (boolean, default: true) — Enable the MDX language server.

TypeScript

This extension offers type safety for MDX files based on TypeScript’s types in JSDoc. For MDX specific details, see the TypeScript section of the repository readme.

Plugins

For information on plugin support, see the Plugins section of the repository readme.

Syntax highlighting

Syntax highlighting for MDX is based on the MDX TextMate grammar.

Custom Languages in Code Blocks

MDX for Visual Studio Code supports syntax highlighting for a number of well-known languages in code blocks. However, it’s impossible to support all languages within the MDX extension. Instead, if an extensions adds support for a language, it can add support for MDX code blocks.

The following example adds support for syntax highlighting MDX code blocks tagged with mermaid. You can use this example and replace mermaid with the appropriate values to support your own language. Save the file to syntaxes/mdx.mermaid.tmLanguage.json.

{
  "fileTypes": [],
  // This can be something else.
  "scopeName": "mdx.mermaid.codeblock",
  "injectionSelector": "L:source.mdx",
  "patterns": [
    {
      "begin": "(?:^|\\G)[\\t ]*(`{3,})(?:[\\t ]*((?i:(?:.*\\.)?mermaid))(?:[\\t ]+((?:[^\\n\\r`])+))?)(?:[\\t ]*$)",
      "beginCaptures": {
        "1": {
          "name": "string.other.begin.code.fenced.mdx"
        },
        "2": {
          "name": "entity.name.function.mdx"
        }
      },
      "contentName": "meta.embedded.mermaid",
      "end": "(\\1)(?:[\\t ]*$)",
      "endCaptures": {
        "1": {
          "name": "string.other.end.code.fenced.mdx"
        }
      },
      "name": "markup.code.mermaid.mdx",
      "patterns": [
        {
          "include": "source.mermaid"
        }
      ]
    },
    {
      "begin": "(?:^|\\G)[\\t ]*(~{3,})(?:[\\t ]*((?i:(?:.*\\.)?mermaid))(?:[\\t ]+((?:[^\\n\\r])+))?)(?:[\\t ]*$)",
      "beginCaptures": {
        "1": {
          "name": "string.other.begin.code.fenced.mdx"
        },
        "2": {
          "name": "entity.name.function.mdx"
        }
      },
      "contentName": "meta.embedded.mermaid",
      "end": "(\\1)(?:[\\t ]*$)",
      "endCaptures": {
        "1": {
          "name": "string.other.end.code.fenced.mdx"
        }
      },
      "name": "markup.code.mermaid.mdx",
      "patterns": [
        {
          "include": "source.mermaid"
        }
      ]
    }
  ]
}

In package.json, add the following section. Replace mermaid with your actual language and remove comments.

{
  "contributes": {
    "grammars": [
      {
        // This must match the scopeName in the tmLanguage file.
        "scopeName": "mdx.mermaid.codeblock",
        "path": "./syntaxes/mdx.mermaid.tmLanguage.json",
        "injectTo": [
          "source.mdx"
        ],
        "embeddedLanguages": {
          "source.mermaid": "mermaid",
        }
      }
    ]
  }
}

ESLint

You can lint MDX with ESLint using eslint-plugin-mdx. To integrate ESLint in Visual Studio Code, install the VS Code ESLint extension.

Auto-close tags

If you want VS Code to automatically close tags while you type, install Auto Close Tag and configure it to also include the mdx language:

{
  "auto-close-tag.activationOnLanguage": [
    // …
    "mdx"
  ]
}

Prettier

Prettier supports MDX 1, but MDX 2 and 3 are not officially supported yet. We recommend against formatting MDX files with Prettier. To opt out, add the following line to your .prettierignore file: