From cc506c895000b4073383f04d6e7d2a4b80d312f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Fri, 21 Jun 2024 19:25:32 +0200 Subject: [PATCH] feat(mdx): support recma plugins (#10241) --- packages/docusaurus-mdx-loader/src/processor.ts | 6 ++++++ .../src/__tests__/options.test.ts | 1 + packages/docusaurus-plugin-content-blog/src/index.ts | 2 ++ packages/docusaurus-plugin-content-blog/src/options.ts | 3 +++ .../src/__tests__/options.test.ts | 1 + packages/docusaurus-plugin-content-docs/src/index.ts | 2 ++ packages/docusaurus-plugin-content-docs/src/options.ts | 3 +++ packages/docusaurus-plugin-content-pages/src/index.ts | 2 ++ packages/docusaurus-plugin-content-pages/src/options.ts | 3 +++ packages/docusaurus-utils-validation/src/index.ts | 1 + .../docusaurus-utils-validation/src/validationSchemas.ts | 1 + project-words.txt | 2 ++ website/_dogfooding/dogfooding.config.ts | 9 +++++++++ website/docs/api/plugins/plugin-content-blog.mdx | 1 + website/docs/api/plugins/plugin-content-docs.mdx | 1 + website/docs/api/plugins/plugin-content-pages.mdx | 1 + website/package.json | 1 + yarn.lock | 5 +++++ 18 files changed, 45 insertions(+) diff --git a/packages/docusaurus-mdx-loader/src/processor.ts b/packages/docusaurus-mdx-loader/src/processor.ts index c96bf168e954..00f2a3035bd2 100644 --- a/packages/docusaurus-mdx-loader/src/processor.ts +++ b/packages/docusaurus-mdx-loader/src/processor.ts @@ -54,6 +54,7 @@ export type MDXOptions = { admonitions: boolean | Partial; 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', }; diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts index 3e925cf10687..050e2a016023 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts +++ b/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); }); diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index 6d40bea301df..2792e9015e15 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/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, diff --git a/packages/docusaurus-plugin-content-blog/src/options.ts b/packages/docusaurus-plugin-content-blog/src/options.ts index 5835c32fc18f..ade2e0e07e7b 100644 --- a/packages/docusaurus-plugin-content-blog/src/options.ts +++ b/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*\*\/\}/, rehypePlugins: [], remarkPlugins: [], + recmaPlugins: [], showReadingTime: true, blogTagsPostsComponent: '@theme/BlogTagsPostsPage', blogTagsListComponent: '@theme/BlogTagsListPage', @@ -93,6 +95,7 @@ const PluginOptionSchema = Joi.object({ 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), diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts index db43660088bf..7a6890329b65 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts +++ b/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, diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index 937f7f7fa9d0..c45c520ac5d0 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/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) => diff --git a/packages/docusaurus-plugin-content-docs/src/options.ts b/packages/docusaurus-plugin-content-docs/src/options.ts index 329341b5e5f7..4812e5dc4ad6 100644 --- a/packages/docusaurus-plugin-content-docs/src/options.ts +++ b/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 = { docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage', remarkPlugins: [], rehypePlugins: [], + recmaPlugins: [], beforeDefaultRemarkPlugins: [], beforeDefaultRehypePlugins: [], showLastUpdateTime: false, @@ -123,6 +125,7 @@ const OptionsSchema = Joi.object({ ), remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins), rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins), + recmaPlugins: RecmaPluginsSchema.default(DEFAULT_OPTIONS.recmaPlugins), beforeDefaultRemarkPlugins: RemarkPluginsSchema.default( DEFAULT_OPTIONS.beforeDefaultRemarkPlugins, ), diff --git a/packages/docusaurus-plugin-content-pages/src/index.ts b/packages/docusaurus-plugin-content-pages/src/index.ts index f32dd74b74c4..d974010a3a2f 100644 --- a/packages/docusaurus-plugin-content-pages/src/index.ts +++ b/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) => diff --git a/packages/docusaurus-plugin-content-pages/src/options.ts b/packages/docusaurus-plugin-content-pages/src/options.ts index 88c3201b3008..2ffda3e7c2fa 100644 --- a/packages/docusaurus-plugin-content-pages/src/options.ts +++ b/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({ 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, ), diff --git a/packages/docusaurus-utils-validation/src/index.ts b/packages/docusaurus-utils-validation/src/index.ts index 426e78db8caa..cbf2ce14bb1f 100644 --- a/packages/docusaurus-utils-validation/src/index.ts +++ b/packages/docusaurus-utils-validation/src/index.ts @@ -19,6 +19,7 @@ export { PluginIdSchema, RemarkPluginsSchema, RehypePluginsSchema, + RecmaPluginsSchema, AdmonitionsSchema, RouteBasePathSchema, URISchema, diff --git a/packages/docusaurus-utils-validation/src/validationSchemas.ts b/packages/docusaurus-utils-validation/src/validationSchemas.ts index 706eaf676f5e..0edd9de0b98a 100644 --- a/packages/docusaurus-utils-validation/src/validationSchemas.ts +++ b/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( diff --git a/project-words.txt b/project-words.txt index 0125953ec975..8b8a8f463f28 100644 --- a/project-words.txt +++ b/project-words.txt @@ -284,6 +284,8 @@ rachelnabors Ramón reactjs rearchitecture +recma +Recma recrawl redirections Redoc diff --git a/website/_dogfooding/dogfooding.config.ts b/website/_dogfooding/dogfooding.config.ts index d751ced7ec0a..8ba4f58b71c0 100644 --- a/website/_dogfooding/dogfooding.config.ts +++ b/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', diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx index 1521411dad78..c8931e4222c9 100644 --- a/website/docs/api/plugins/plugin-content-blog.mdx +++ b/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*\*\/\}/` | Truncate marker marking where the summary ends. | diff --git a/website/docs/api/plugins/plugin-content-docs.mdx b/website/docs/api/plugins/plugin-content-docs.mdx index 1a9dcc370758..295d228c11ff 100644 --- a/website/docs/api/plugins/plugin-content-docs.mdx +++ b/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. | diff --git a/website/docs/api/plugins/plugin-content-pages.mdx b/website/docs/api/plugins/plugin-content-pages.mdx index 266c929d5a14..03db1f4f1bf2 100644 --- a/website/docs/api/plugins/plugin-content-pages.mdx +++ b/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. | diff --git a/website/package.json b/website/package.json index d72599de5796..fafdd596227b 100644 --- a/website/package.json +++ b/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", diff --git a/yarn.lock b/yarn.lock index 1dea0ad4c8ea..f48936630928 100644 --- a/yarn.lock +++ b/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"