Document syntax highlighting for MDX code blocks

.changeset/khaki-coats-press.md

@@ -0,0 +1,5 @@
+---
+'vscode-mdx': patch
+---
+
+Document how to support custom languages in MDX code blocks.

packages/vscode-mdx/README.md

@@ -17,6 +17,7 @@
 * [TypeScript](#typescript)
 * [Plugins](#plugins)
 * [Syntax highlighting](#syntax-highlighting)
+  * [Custom Languages in Code Blocks](#custom-languages-in-code-blocks)
 * [ESLint](#eslint)
 * [Auto-close tags](#auto-close-tags)
 * [Sponsor](#sponsor)
@@ -60,6 +61,102 @@ repository readme.
 Syntax highlighting for MDX is based on the
 [MDX TextMate grammar](https://github.com/wooorm/markdown-tm-language).
 
+### 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`.
+
+```jsonc
+{
+  "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.
+
+```jsonc
+{
+  "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`][eslint-plugin-mdx].