feat(mdx): support recma plugins (#10241)

packages/docusaurus-mdx-loader/src/processor.ts

@@ -54,6 +54,7 @@ export type MDXOptions = {
   admonitions: boolean | Partial<AdmonitionOptions>;
   remarkPlugins: MDXPlugin[];
   rehypePlugins: MDXPlugin[];
+  recmaPlugins: MDXPlugin[];
   beforeDefaultRemarkPlugins: MDXPlugin[];
   beforeDefaultRehypePlugins: MDXPlugin[];
 };
@@ -150,6 +151,10 @@ async function createProcessorFactory() {
       ...(options.rehypePlugins ?? []),
     ];
 
+    // Maybe we'll want to introduce default recma plugins later?
+    // For example https://github.com/domdomegg/recma-mdx-displayname ?
+    const recmaPlugins = [...(options.recmaPlugins ?? [])];
+
     if (format === 'md') {
       // This is what permits to embed HTML elements with format 'md'
       // See https://github.com/facebook/docusaurus/pull/8960
@@ -173,6 +178,7 @@ async function createProcessorFactory() {
       ...options,
       remarkPlugins,
       rehypePlugins,
+      recmaPlugins,
       providerImportSource: '@mdx-js/react',
     };
 

packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts

@@ -63,6 +63,7 @@ describe('validateOptions', () => {
         markdownPluginsObjectStub,
         [markdownPluginsFunctionStub, {option1: '42'}],
       ],
+      recmaPlugins: [markdownPluginsFunctionStub],
     };
     expect(testValidate(userOptions)).toEqual(userOptions);
   });

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -250,6 +250,7 @@ export default async function pluginContentBlog(
         admonitions,
         rehypePlugins,
         remarkPlugins,
+        recmaPlugins,
         truncateMarker,
         beforeDefaultRemarkPlugins,
         beforeDefaultRehypePlugins,
@@ -262,6 +263,7 @@ export default async function pluginContentBlog(
           admonitions,
           remarkPlugins,
           rehypePlugins,
+          recmaPlugins,
           beforeDefaultRemarkPlugins: [
             footnoteIDFixer,
             ...beforeDefaultRemarkPlugins,

packages/docusaurus-plugin-content-blog/src/options.ts

@@ -9,6 +9,7 @@ import {
   Joi,
   RemarkPluginsSchema,
   RehypePluginsSchema,
+  RecmaPluginsSchema,
   AdmonitionsSchema,
   RouteBasePathSchema,
   URISchema,
@@ -29,6 +30,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   truncateMarker: /<!--\s*truncate\s*-->|\{\/\*\s*truncate\s*\*\/\}/,
   rehypePlugins: [],
   remarkPlugins: [],
+  recmaPlugins: [],
   showReadingTime: true,
   blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
   blogTagsListComponent: '@theme/BlogTagsListPage',
@@ -93,6 +95,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   showReadingTime: Joi.bool().default(DEFAULT_OPTIONS.showReadingTime),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
+  recmaPlugins: RecmaPluginsSchema.default(DEFAULT_OPTIONS.recmaPlugins),
   admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
   editUrl: Joi.alternatives().try(URISchema, Joi.function()),
   editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles),

packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts

@@ -60,6 +60,7 @@ describe('normalizeDocsPluginOptions', () => {
       // @ts-expect-error: it seems to work in practice?
       remarkPlugins: [markdownPluginsObjectStub],
       rehypePlugins: [markdownPluginsFunctionStub],
+      recmaPlugins: [markdownPluginsFunctionStub],
       beforeDefaultRehypePlugins: [],
       beforeDefaultRemarkPlugins: [],
       breadcrumbs: true,

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -293,6 +293,7 @@ export default async function pluginContentDocs(
       const {
         rehypePlugins,
         remarkPlugins,
+        recmaPlugins,
         beforeDefaultRehypePlugins,
         beforeDefaultRemarkPlugins,
       } = options;
@@ -307,6 +308,7 @@ export default async function pluginContentDocs(
           admonitions: options.admonitions,
           remarkPlugins,
           rehypePlugins,
+          recmaPlugins,
           beforeDefaultRehypePlugins,
           beforeDefaultRemarkPlugins,
           staticDirs: siteConfig.staticDirectories.map((dir) =>

packages/docusaurus-plugin-content-docs/src/options.ts

@@ -10,6 +10,7 @@ import {
   Joi,
   RemarkPluginsSchema,
   RehypePluginsSchema,
+  RecmaPluginsSchema,
   AdmonitionsSchema,
   RouteBasePathSchema,
   URISchema,
@@ -40,6 +41,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
   remarkPlugins: [],
   rehypePlugins: [],
+  recmaPlugins: [],
   beforeDefaultRemarkPlugins: [],
   beforeDefaultRehypePlugins: [],
   showLastUpdateTime: false,
@@ -123,6 +125,7 @@ const OptionsSchema = Joi.object<PluginOptions>({
   ),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
+  recmaPlugins: RecmaPluginsSchema.default(DEFAULT_OPTIONS.recmaPlugins),
   beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRemarkPlugins,
   ),

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -72,6 +72,7 @@ export default function pluginContentPages(
         admonitions,
         rehypePlugins,
         remarkPlugins,
+        recmaPlugins,
         beforeDefaultRehypePlugins,
         beforeDefaultRemarkPlugins,
       } = options;
@@ -82,6 +83,7 @@ export default function pluginContentPages(
           admonitions,
           remarkPlugins,
           rehypePlugins,
+          recmaPlugins,
           beforeDefaultRehypePlugins,
           beforeDefaultRemarkPlugins,
           staticDirs: siteConfig.staticDirectories.map((dir) =>

packages/docusaurus-plugin-content-pages/src/options.ts

@@ -9,6 +9,7 @@ import {
   Joi,
   RemarkPluginsSchema,
   RehypePluginsSchema,
+  RecmaPluginsSchema,
   AdmonitionsSchema,
   RouteBasePathSchema,
   URISchema,
@@ -25,6 +26,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   mdxPageComponent: '@theme/MDXPage',
   remarkPlugins: [],
   rehypePlugins: [],
+  recmaPlugins: [],
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: true,
@@ -41,6 +43,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   mdxPageComponent: Joi.string().default(DEFAULT_OPTIONS.mdxPageComponent),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
+  recmaPlugins: RecmaPluginsSchema.default(DEFAULT_OPTIONS.recmaPlugins),
   beforeDefaultRehypePlugins: RehypePluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
   ),

packages/docusaurus-utils-validation/src/index.ts

@@ -19,6 +19,7 @@ export {
   PluginIdSchema,
   RemarkPluginsSchema,
   RehypePluginsSchema,
+  RecmaPluginsSchema,
   AdmonitionsSchema,
   RouteBasePathSchema,
   URISchema,

packages/docusaurus-utils-validation/src/validationSchemas.ts

@@ -36,6 +36,7 @@ const MarkdownPluginsSchema = Joi.array()
 
 export const RemarkPluginsSchema = MarkdownPluginsSchema;
 export const RehypePluginsSchema = MarkdownPluginsSchema;
+export const RecmaPluginsSchema = MarkdownPluginsSchema;
 
 export const AdmonitionsSchema = JoiFrontMatter.alternatives()
   .try(

project-words.txt

@@ -284,6 +284,8 @@ rachelnabors
 Ramón
 reactjs
 rearchitecture
+recma
+Recma
 recrawl
 redirections
 Redoc

website/_dogfooding/dogfooding.config.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import path from 'path';
+import RecmaMDXDisplayName from 'recma-mdx-displayname';
 import type {PluginConfig, Plugin} from '@docusaurus/types';
 import type {Options as DocsOptions} from '@docusaurus/plugin-content-docs';
 import type {Options as BlogOptions} from '@docusaurus/plugin-content-blog';
@@ -42,6 +44,13 @@ export const dogfoodingPluginInstances: PluginConfig[] = [
       },
       onInlineTags: 'warn',
       tags: 'tags.yml',
+      recmaPlugins: [
+        [
+          RecmaMDXDisplayName,
+          (vfile: {path: string}) =>
+            `MDXContent(${path.relative(process.cwd(), vfile.path)})`,
+        ],
+      ],
 
       // Using a _ prefix to test against an edge case regarding MDX partials: https://github.com/facebook/docusaurus/discussions/5181#discussioncomment-1018079
       path: '_dogfooding/_docs tests',

website/docs/api/plugins/plugin-content-blog.mdx

@@ -60,6 +60,7 @@ Accepted fields:
 | `blogArchiveComponent` | `string` | `'@theme/BlogArchivePage'` | Root component of the blog archive page. |
 | `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
 | `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
+| `rehypePlugins` | `any[]` | `[]` | Recma plugins passed to MDX. |
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
 | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
 | `truncateMarker` | `RegExp` | `/<!--\s*truncate\s*-->/` \| `\{\/\*\s*truncate\s*\*\/\}/` | Truncate marker marking where the summary ends. |

website/docs/api/plugins/plugin-content-docs.mdx

@@ -55,6 +55,7 @@ Accepted fields:
 | `docCategoryGeneratedIndexComponent` | `string` | `'@theme/DocCategoryGeneratedIndexPage'` | Root component of the generated category index page. |
 | `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
 | `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
+| `rehypePlugins` | `any[]` | `[]` | Recma plugins passed to MDX. |
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
 | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
 | `showLastUpdateAuthor` | `boolean` | `false` | Whether to display the author who last updated the doc. |

website/docs/api/plugins/plugin-content-pages.mdx

@@ -42,6 +42,7 @@ Accepted fields:
 | `mdxPageComponent` | `string` | `'@theme/MDXPage'` | Component used by each MDX page. |
 | `remarkPlugins` | `[]` | `any[]` | Remark plugins passed to MDX. |
 | `rehypePlugins` | `[]` | `any[]` | Rehype plugins passed to MDX. |
+| `rehypePlugins` | `any[]` | `[]` | Recma plugins passed to MDX. |
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
 | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
 | `showLastUpdateAuthor` | `boolean` | `false` | **Only for Markdown pages**. Whether to display the author who last updated the page. |

website/package.json

@@ -60,6 +60,7 @@
     "react-dom": "^18.0.0",
     "react-lite-youtube-embed": "^2.3.52",
     "react-medium-image-zoom": "^5.1.6",
+    "recma-mdx-displayname": "^0.4.1",
     "rehype-katex": "^7.0.0",
     "remark-math": "^6.0.0",
     "swc-loader": "^0.2.3",

yarn.lock

@@ -14055,6 +14055,11 @@ rechoir@^0.6.2:
   dependencies:
     resolve "^1.1.6"
 
+recma-mdx-displayname@^0.4.1:
+  version "0.4.1"
+  resolved "https://registry.yarnpkg.com/recma-mdx-displayname/-/recma-mdx-displayname-0.4.1.tgz#45ba59d2ac573795233d20a0bda1c2f03e85e301"
+  integrity sha512-2apUFDEAiqkz4QmQboOVrLdvWyyR5dC6Is4S4gwxCFxznNfDk+W4bNBWK+9oWUO91olFZg7Edd7Lw5XkRTOuRQ==
+
 recursive-readdir@^2.2.2:
   version "2.2.3"
   resolved "https://registry.yarnpkg.com/recursive-readdir/-/recursive-readdir-2.2.3.tgz#e726f328c0d69153bcabd5c322d3195252379372"