Document syntax highlighting for MDX code blocks (#444)

MDX syntax highlighting can’t possibly support all past, present, and
future languages in code blocks. Extensions can inject their own syntax
highlighting.

This documentation helps extension authors to support their own language
in 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].