Add support for some popular transformer plugins (#501)

remcohaszing · web-flow · commit 9b3b9ce426c6 · 2025-04-19T13:52:17.000+02:00
This adds support for the following transformer plugins: - `recma-export-filepath` - `rehype-mdx-title` - `remark-mdx-frontmatter` These plugins all follow the same pattern; they expose some form of metatada as an ESM export. I think these are some of the most popular plugins that actually affect the editor experience. I don’t like that support for these plugins is hardcoded. This is only due to the lack of an alternative. For now I welcome hardcoded support for other plugins. I intend to iterate on this to provide a better editor experience for YAML frontmatter. Refs #297
diff --git a/.changeset/lucky-chicken-ring.md b/.changeset/lucky-chicken-ring.md
@@ -0,0 +1,5 @@
+---
+'@mdx-js/language-service': minor
+---
+
+Replace `resolveRemarkPlugins` with `remarkPlugins`
diff --git a/.changeset/sad-melons-play.md b/.changeset/sad-melons-play.md
@@ -0,0 +1,8 @@
+---
+'@mdx-js/typescript-plugin': patch
+'@mdx-js/language-service': patch
+'@mdx-js/language-server': patch
+'vscode-mdx': patch
+---
+
+Add support for `recma-export-filepath`, `rehype-mdx-title`, and `remark-mdx-frontmatter`
diff --git a/packages/language-server/lib/index.js b/packages/language-server/lib/index.js
@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 /**
+ * @import {VirtualCodePlugin} from '@mdx-js/language-service'
  * @import {PluggableList} from 'unified'
  */
 
@@ -10,7 +11,7 @@ import process from 'node:process'
 import {
   createMdxLanguagePlugin,
   createMdxServicePlugin,
-  resolveRemarkPlugins
+  resolvePlugins
 } from '@mdx-js/language-service'
 import {
   createConnection,
@@ -82,7 +83,9 @@ connection.onInitialize(async (parameters) => {
    */
   function getLanguagePlugins(tsconfig) {
     /** @type {PluggableList | undefined} */
-    let plugins
+    let remarkPlugins
+    /** @type {VirtualCodePlugin[] | undefined} */
+    let virtualCodePlugins
     let checkMdx = false
     let jsxImportSource = 'react'
 
@@ -101,7 +104,7 @@ connection.onInitialize(async (parameters) => {
       )
       const jiti = createJiti(tsconfig)
 
-      plugins = resolveRemarkPlugins(
+      ;[remarkPlugins, virtualCodePlugins] = resolvePlugins(
         commandLine.raw?.mdx,
         (name) => jiti(name).default
       )
@@ -111,7 +114,8 @@ connection.onInitialize(async (parameters) => {
 
     return [
       createMdxLanguagePlugin(
-        plugins || defaultPlugins,
+        remarkPlugins || defaultPlugins,
+        virtualCodePlugins,
         checkMdx,
         jsxImportSource
       )
diff --git a/packages/language-service/README.md b/packages/language-service/README.md
@@ -19,7 +19,7 @@
 * [API](#api)
   * [`createMdxLanguagePlugin([plugins][, checkMdx][, jsxImportSource])`](#createmdxlanguagepluginplugins-checkmdx-jsximportsource)
   * [`createMdxServicePlugin(options)`](#createmdxservicepluginoptions)
-  * [`resolveRemarkPlugins(mdxConfig, resolvePlugin)`](#resolveremarkpluginsmdxconfig-resolveplugin)
+  * [`resolvePlugins(mdxConfig, resolvePlugin)`](#resolvepluginsmdxconfig-resolveplugin)
 * [Compatibility](#compatibility)
 * [Types](#types)
 * [Security](#security)
@@ -57,7 +57,7 @@ In Deno with [`esm.sh`][esmsh]:
 import {
   createMdxLanguagePlugin,
   createMdxServicePlugin,
-  resolveRemarkPlugins
+  resolvePlugins
 } from 'https://esm.sh/@mdx-js/language-service'
 ```
 
@@ -68,7 +68,7 @@ In browsers with [`esm.sh`][esmsh]:
   import {
     createMdxLanguagePlugin,
     createMdxServicePlugin,
-    resolveRemarkPlugins
+    resolvePlugins
   } from 'https://esm.sh/@mdx-js/language-service?bundle'
 </script>
 ```
@@ -136,9 +136,9 @@ The following commands are supported:
 
 The Volar service plugin for MDX files.
 
-### `resolveRemarkPlugins(mdxConfig, resolvePlugin)`
+### `resolvePlugins(mdxConfig, resolvePlugin)`
 
-Resolve remark plugins from TypeScript’s parsed command line options.
+Resolve plugins from TypeScript’s parsed command line options.
 
 #### Parameters
 
@@ -149,8 +149,14 @@ Resolve remark plugins from TypeScript’s parsed command line options.
 
 #### Returns
 
-An array of resolved plugins, or `undefined` in case of an invalid
-configuration.
+A tuple where the first item is n array of resolved plugins,
+or `undefined` in case of an invalid configuration.
+The second item is an array of supported transformer plugins.
+The supported transformer plugins are:
+
+* [`recma-export-filepath`](https://github.com/remcohaszing/recma-export-filepath)
+* [`rehype-mdx-title`](https://github.com/remcohaszing/rehype-mdx-title)
+* [`remark-mdx-frontmatter`](https://github.com/remcohaszing/remark-mdx-frontmatter)
 
 ## Compatibility
 
diff --git a/packages/language-service/lib/index.js b/packages/language-service/lib/index.js
@@ -1,3 +1,7 @@
+/**
+ * @typedef {import('./plugins/plugin.js').VirtualCodePlugin} VirtualCodePlugin
+ */
+
 export {createMdxLanguagePlugin} from './language-plugin.js'
 export {createMdxServicePlugin} from './service-plugin.js'
-export {resolveRemarkPlugins} from './tsconfig.js'
+export {resolvePlugins} from './tsconfig.js'
diff --git a/packages/language-service/lib/language-plugin.js b/packages/language-service/lib/language-plugin.js
@@ -4,6 +4,7 @@
  * @import {LanguagePlugin} from '@volar/language-service'
  * @import {PluggableList} from 'unified'
  * @import {URI} from 'vscode-uri'
+ * @import {VirtualCodePlugin} from './plugins/plugin.js'
  */
 
 import remarkMdx from 'remark-mdx'
@@ -14,9 +15,10 @@ import {VirtualMdxCode} from './virtual-code.js'
 /**
  * Create a [Volar](https://volarjs.dev) language plugin to support MDX.
  *
- * @param {PluggableList} [plugins]
+ * @param {PluggableList} [remarkPlugins]
  *   A list of remark syntax plugins. Only syntax plugins are supported.
  *   Transformers are unused.
+ * @param {VirtualCodePlugin[]} [virtualCodePlugins]
  * @param {boolean} checkMdx
  *   If true, check MDX files strictly.
  * @param {string} jsxImportSource
@@ -25,13 +27,14 @@ import {VirtualMdxCode} from './virtual-code.js'
  *   A Volar language plugin to support MDX.
  */
 export function createMdxLanguagePlugin(
-  plugins,
+  remarkPlugins,
+  virtualCodePlugins,
   checkMdx = false,
   jsxImportSource = 'react'
 ) {
   const processor = unified().use(remarkParse).use(remarkMdx)
-  if (plugins) {
-    processor.use(plugins)
+  if (remarkPlugins) {
+    processor.use(remarkPlugins)
   }
 
   processor.freeze()
@@ -48,6 +51,7 @@ export function createMdxLanguagePlugin(
         return new VirtualMdxCode(
           snapshot,
           processor,
+          virtualCodePlugins || [],
           checkMdx,
           jsxImportSource
         )
diff --git a/packages/language-service/lib/plugins/plugin.js b/packages/language-service/lib/plugins/plugin.js
@@ -0,0 +1,17 @@
+/**
+ * @import {Nodes} from 'mdast'
+ */
+
+/**
+ * @typedef VirtualCodePluginObject
+ *   An object returned by a virtual code plugin.
+ * @property {(node: Nodes) => undefined} [visit]
+ *   Visit an mdast node.
+ * @property {() => string} finalize
+ *   Generate the JavaScript string to insert into the virtual code.
+ */
+
+/**
+ * @typedef {() => VirtualCodePluginObject} VirtualCodePlugin
+ *   An internal plugin for MDX analyzer that represents an MDX plugin.
+ */
diff --git a/packages/language-service/lib/plugins/recma-export-filepath.js b/packages/language-service/lib/plugins/recma-export-filepath.js
@@ -0,0 +1,24 @@
+/**
+ * @import {VirtualCodePlugin} from './plugin.js'
+ */
+
+/**
+ * @param {unknown} options
+ * @returns {VirtualCodePlugin}
+ */
+export function recmaExportFilepath(options) {
+  const opts = typeof options === 'object' && options !== null ? options : {}
+  const name = 'name' in opts ? String(opts.name) : 'filepath'
+
+  return () => {
+    return {
+      finalize() {
+        return (
+          '/** Generated by [recma-export-filepath](https://github.com/remcohaszing/recma-export-filepath) */\nexport const ' +
+          name +
+          " = /** @type {string} */ ('')"
+        )
+      }
+    }
+  }
+}
diff --git a/packages/language-service/lib/plugins/rehype-mdx-title.js b/packages/language-service/lib/plugins/rehype-mdx-title.js
@@ -0,0 +1,33 @@
+/**
+ * @import {VirtualCodePlugin} from './plugin.js'
+ */
+
+/**
+ * @param {unknown} options
+ * @returns {VirtualCodePlugin}
+ */
+export function rehypeMdxTitle(options) {
+  const opts = typeof options === 'object' && options !== null ? options : {}
+  const maxRank = 'maxRank' in opts ? Number(opts.maxRank) : 1
+  const name = 'name' in opts ? String(opts.name) : 'title'
+
+  return () => {
+    let hasTitle = false
+
+    return {
+      visit(node) {
+        hasTitle ||= node.type === 'heading' && node.depth <= maxRank
+      },
+
+      finalize() {
+        return (
+          '/** Generated by [rehype-mdx-title](https://github.com/remcohaszing/rehype-mdx-title) */\nexport const ' +
+          name +
+          ' = /** @type {string' +
+          (hasTitle ? '' : ' | undefined') +
+          "} */ ('')"
+        )
+      }
+    }
+  }
+}
diff --git a/packages/language-service/lib/plugins/remark-mdx-frontmatter.js b/packages/language-service/lib/plugins/remark-mdx-frontmatter.js
@@ -0,0 +1,32 @@
+/**
+ * @import {VirtualCodePlugin} from './plugin.js'
+ */
+
+/**
+ * @param {unknown} options
+ * @returns {VirtualCodePlugin}
+ */
+export function remarkMdxFrontmatter(options) {
+  const opts = typeof options === 'object' && options !== null ? options : {}
+  const name = 'name' in opts ? String(opts.name) : 'frontmatter'
+
+  return () => {
+    let hasFrontmatter = false
+
+    return {
+      visit(node) {
+        hasFrontmatter ||= node.type === 'toml' || node.type === 'yaml'
+      },
+
+      finalize() {
+        return (
+          '/** Generated by [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) */\nexport const ' +
+          name +
+          ' = /** @type {' +
+          (hasFrontmatter ? 'any' : 'undefined') +
+          '} */ (undefined)'
+        )
+      }
+    }
+  }
+}
diff --git a/packages/language-service/lib/tsconfig.js b/packages/language-service/lib/tsconfig.js
@@ -1,43 +1,51 @@
 /**
  * @import {Pluggable, PluggableList, Plugin} from 'unified'
+ * @import {VirtualCodePlugin} from './plugins/plugin.js'
  */
 
+import {recmaExportFilepath} from './plugins/recma-export-filepath.js'
+import {rehypeMdxTitle} from './plugins/rehype-mdx-title.js'
+import {remarkMdxFrontmatter} from './plugins/remark-mdx-frontmatter.js'
+
 /**
  * Resolve remark plugins from TypeScript’s parsed command line options.
  *
  * @param {unknown} mdxConfig
  *   The parsed command line options from which to resolve plugins.
  * @param {(name: string) => Plugin} resolvePlugin
  *   A function which takes a plugin name, and resolvs it to a remark plugin.
- * @returns {PluggableList | undefined}
+ * @returns {[PluggableList?, VirtualCodePlugin[]?]}
  *   An array of resolved plugins, or `undefined` in case of an invalid
  *   configuration.
  */
-export function resolveRemarkPlugins(mdxConfig, resolvePlugin) {
+export function resolvePlugins(mdxConfig, resolvePlugin) {
   if (
     typeof mdxConfig !== 'object' ||
     !mdxConfig ||
     !('plugins' in mdxConfig)
   ) {
-    return
+    return []
   }
 
   const pluginConfig = mdxConfig.plugins
 
   if (typeof pluginConfig !== 'object' || !pluginConfig) {
-    return
+    return []
   }
 
   const pluginArray = Array.isArray(pluginConfig)
     ? pluginConfig
     : Object.entries(pluginConfig)
 
   if (pluginArray.length === 0) {
-    return
+    return []
   }
 
   /** @type {Pluggable[]} */
-  const plugins = []
+  const remarkPlugins = []
+  /** @type {VirtualCodePlugin[]} */
+  const virtualCodePlugins = []
+
   for (const maybeTuple of pluginArray) {
     const [name, ...options] = Array.isArray(maybeTuple)
       ? maybeTuple
@@ -47,8 +55,20 @@ export function resolveRemarkPlugins(mdxConfig, resolvePlugin) {
       continue
     }
 
-    plugins.push([resolvePlugin(name), ...options])
+    switch (name) {
+      case 'recma-export-filepath':
+        virtualCodePlugins.push(recmaExportFilepath(options[0]))
+        break
+      case 'rehype-mdx-title':
+        virtualCodePlugins.push(rehypeMdxTitle(options[0]))
+        break
+      case 'remark-mdx-frontmatter':
+        virtualCodePlugins.push(remarkMdxFrontmatter(options[0]))
+        break
+      default:
+        remarkPlugins.push([resolvePlugin(name), ...options])
+    }
   }
 
-  return plugins
+  return [remarkPlugins, virtualCodePlugins]
 }
diff --git a/packages/language-service/lib/virtual-code.js b/packages/language-service/lib/virtual-code.js
diff --git a/packages/language-service/test/language-plugin.js b/packages/language-service/test/language-plugin.js
diff --git a/packages/language-service/test/tsconfig.js b/packages/language-service/test/tsconfig.js
diff --git a/packages/typescript-plugin/lib/index.cjs b/packages/typescript-plugin/lib/index.cjs

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@mdx-js/language-service': minor
 +---
++
 +Replace `resolveRemarkPlugins` with `remarkPlugins`