feat: upgrade to MDX v2

.eslintrc.js

@@ -372,7 +372,8 @@ module.exports = {
     // We don't provide any escape hatches for this rule. Rest siblings and
     // function placeholder params are always ignored, and any other unused
     // locals must be justified with a disable comment.
-    '@typescript-eslint/no-unused-vars': [ERROR, {ignoreRestSiblings: true}],
+    // TODO revert to error + add varsIgnorePattern _ prefix
+    '@typescript-eslint/no-unused-vars': [WARNING, {ignoreRestSiblings: true}],
     '@typescript-eslint/prefer-optional-chain': ERROR,
     '@docusaurus/no-html-links': ERROR,
     '@docusaurus/prefer-docusaurus-heading': ERROR,

.stylelintignore

@@ -13,3 +13,5 @@ packages/docusaurus-*/lib/*
 packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/
 website/static/katex/katex.min.css
+
+jest/vendor

jest.config.mjs

@@ -80,6 +80,19 @@ export default {
       '@docusaurus/plugin-content-docs/src/client/index.ts',
 
     '@testing-utils/(.*)': '<rootDir>/jest/utils/$1.ts',
+
+    // MDX packages are ESM-only and it is a pain to use in Jest
+    // So we use them in Jest tests as CJS versions
+    // see https://mdxjs.com/docs/troubleshooting-mdx/#problems-integrating-mdx
+    '^@mdx-js/mdx$': '<rootDir>/jest/vendor/@[email protected]',
+    '^remark$': '<rootDir>/jest/vendor/[email protected]',
+    '^remark-mdx$': '<rootDir>/jest/vendor/[email protected]',
+    '^remark-directive$': '<rootDir>/jest/vendor/[email protected]',
+    '^remark-gfm$': '<rootDir>/jest/vendor/[email protected]',
+    '^estree-util-value-to-estree$':
+      '<rootDir>/jest/vendor/[email protected]',
+    '^mdast-util-to-string$':
+      '<rootDir>/jest/vendor/[email protected]',
   },
   snapshotSerializers: [
     '<rootDir>/jest/snapshotPathNormalizer.ts',

jest/deps.d.ts

@@ -13,13 +13,6 @@ declare module 'to-vfile' {
   export function read(path: string, encoding?: string): Promise<VFile>;
 }
 
-declare module 'remark-mdx' {
-  import type {Plugin} from 'unified';
-
-  const mdx: Plugin;
-  export = mdx;
-}
-
 declare module 'remark-rehype';
 
 declare module 'rehype-stringify';

package.json

@@ -54,12 +54,12 @@
     "test": "jest",
     "test:build:website": "./admin/scripts/test-release.sh",
     "watch": "yarn lerna run --parallel watch",
-    "clear": "(yarn workspace website clear || echo 'Failure while running docusaurus clear') && yarn lerna exec --ignore docusaurus yarn rimraf lib",
+    "clear": "(yarn workspace website clear || echo 'Failure while running docusaurus clear') && yarn rimraf test-website && yarn rimraf test-website-in-workspace && yarn lerna exec --ignore docusaurus yarn rimraf lib",
     "test:baseUrl": "yarn build:website:baseUrl && yarn serve:website:baseUrl",
     "lock:update": "npx --yes yarn-deduplicate"
   },
   "dependencies": {
-    "unified": "^9.2.2"
+    "unified": "^10.1.2"
   },
   "devDependencies": {
     "@crowdin/cli": "^3.9.1",

packages/create-docusaurus/templates/classic-typescript/package.json

@@ -17,7 +17,7 @@
   "dependencies": {
     "@docusaurus/core": "^3.0.0-alpha.0",
     "@docusaurus/preset-classic": "^3.0.0-alpha.0",
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^2.1.5",
     "clsx": "^1.2.1",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",

packages/create-docusaurus/templates/classic/package.json

@@ -16,7 +16,7 @@
   "dependencies": {
     "@docusaurus/core": "^3.0.0-alpha.0",
     "@docusaurus/preset-classic": "^3.0.0-alpha.0",
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^2.1.5",
     "clsx": "^1.2.1",
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",

packages/create-docusaurus/templates/facebook/package.json

@@ -20,7 +20,7 @@
   "dependencies": {
     "@docusaurus/core": "^3.0.0-alpha.0",
     "@docusaurus/preset-classic": "^3.0.0-alpha.0",
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^2.1.5",
     "clsx": "^1.2.1",
     "react": "^17.0.2",
     "react-dom": "^17.0.2"

packages/docusaurus-mdx-loader/package.json

@@ -22,16 +22,23 @@
     "@babel/traverse": "^7.20.12",
     "@docusaurus/logger": "^3.0.0-alpha.0",
     "@docusaurus/utils": "^3.0.0-alpha.0",
-    "@mdx-js/mdx": "^1.6.22",
+    "@docusaurus/utils-validation": "^3.0.0-alpha.0",
+    "@mdx-js/mdx": "^2.1.5",
     "escape-html": "^1.0.3",
+    "estree-util-value-to-estree": "^2.1.0",
     "file-loader": "^6.2.0",
     "fs-extra": "^11.1.0",
+    "hastscript": "^7.1.0",
     "image-size": "^1.0.2",
-    "mdast-util-to-string": "^2.0.0",
+    "mdast-util-to-string": "^3.0.0",
+    "mdast-util-mdx": "^2.0.0",
+    "remark-comment": "^1.0.0",
+    "remark-gfm": "^3.0.1",
+    "remark-directive": "^2.0.1",
     "remark-emoji": "^2.2.0",
     "stringify-object": "^3.3.0",
     "tslib": "^2.4.1",
-    "unified": "^9.2.2",
+    "unified": "^10.1.2",
     "unist-util-visit": "^2.0.3",
     "url-loader": "^4.1.1",
     "webpack": "^5.75.0"
@@ -43,8 +50,8 @@
     "@types/stringify-object": "^3.3.1",
     "@types/unist": "^2.0.6",
     "rehype-stringify": "^8.0.0",
-    "remark": "^12.0.1",
-    "remark-mdx": "^1.6.21",
+    "remark": "^14.0.2",
+    "remark-mdx": "^2.1.5",
     "remark-rehype": "^8.1.0",
     "to-vfile": "^6.1.0",
     "unist-builder": "^2.0.3",

packages/docusaurus-mdx-loader/src/__tests__/frontMatter.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import escapeStringRegexp from 'escape-string-regexp';
+import {
+  validateMDXFrontMatter,
+  DefaultMDXFrontMatter,
+  type MDXFrontMatter,
+} from '../frontMatter';
+
+function testField(params: {
+  prefix: string;
+  validFrontMatters: MDXFrontMatter[];
+  convertibleFrontMatter?: [
+    ConvertibleFrontMatter: {[key: string]: unknown},
+    ConvertedFrontMatter: MDXFrontMatter,
+  ][];
+  invalidFrontMatters?: [
+    InvalidFrontMatter: {[key: string]: unknown},
+    ErrorMessage: string,
+  ][];
+}) {
+  // eslint-disable-next-line jest/require-top-level-describe
+  test(`[${params.prefix}] accept valid values`, () => {
+    params.validFrontMatters.forEach((frontMatter) => {
+      expect(validateMDXFrontMatter(frontMatter)).toEqual(frontMatter);
+    });
+  });
+
+  // eslint-disable-next-line jest/require-top-level-describe
+  test(`[${params.prefix}] convert valid values`, () => {
+    params.convertibleFrontMatter?.forEach(
+      ([convertibleFrontMatter, convertedFrontMatter]) => {
+        expect(validateMDXFrontMatter(convertibleFrontMatter)).toEqual(
+          convertedFrontMatter,
+        );
+      },
+    );
+  });
+
+  // eslint-disable-next-line jest/require-top-level-describe
+  test(`[${params.prefix}] throw error for values`, () => {
+    params.invalidFrontMatters?.forEach(([frontMatter, message]) => {
+      try {
+        validateMDXFrontMatter(frontMatter);
+        throw new Error(
+          `MDX front matter is expected to be rejected, but was accepted successfully:\n ${JSON.stringify(
+            frontMatter,
+            null,
+            2,
+          )}`,
+        );
+      } catch (err) {
+        // eslint-disable-next-line jest/no-conditional-expect
+        expect((err as Error).message).toMatch(
+          new RegExp(escapeStringRegexp(message)),
+        );
+      }
+    });
+  });
+}
+
+describe('MDX front matter schema', () => {
+  it('accepts empty object', () => {
+    const frontMatter: Partial<MDXFrontMatter> = {};
+    expect(validateMDXFrontMatter(frontMatter)).toEqual(DefaultMDXFrontMatter);
+  });
+
+  it('accepts undefined object', () => {
+    expect(validateMDXFrontMatter(undefined)).toEqual(DefaultMDXFrontMatter);
+  });
+
+  it('rejects unknown field', () => {
+    const frontMatter = {abc: '1'};
+    expect(() =>
+      validateMDXFrontMatter(frontMatter),
+    ).toThrowErrorMatchingInlineSnapshot(`""abc" is not allowed"`);
+  });
+});
+
+describe('validateDocFrontMatter format', () => {
+  testField({
+    prefix: 'format',
+    validFrontMatters: [{format: 'md'}, {format: 'mdx'}],
+    invalidFrontMatters: [
+      [{format: 'xdm'}, '"format" must be one of [md, mdx, detect]'],
+    ],
+  });
+});

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

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  JoiFrontMatter as Joi,
+  validateFrontMatter,
+} from '@docusaurus/utils-validation';
+
+export type MDXFrontMatter = {
+  format: 'md' | 'mdx' | 'detect';
+};
+
+export const DefaultMDXFrontMatter: MDXFrontMatter = {
+  format: 'detect',
+};
+
+const MDXFrontMatterSchema = Joi.object<MDXFrontMatter>({
+  format: Joi.string()
+    .equal('md', 'mdx', 'detect')
+    .default(DefaultMDXFrontMatter.format),
+}).default(DefaultMDXFrontMatter);
+
+export function validateMDXFrontMatter(frontMatter: unknown): MDXFrontMatter {
+  return validateFrontMatter(frontMatter, MDXFrontMatterSchema, {
+    allowUnknown: false,
+  });
+}

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

@@ -7,13 +7,11 @@
 
 import {mdxLoader} from './loader';
 
+import type {TOCItem as TOCItemImported} from './remark/toc';
+
 export default mdxLoader;
 
-export type TOCItem = {
-  readonly value: string;
-  readonly id: string;
-  readonly level: number;
-};
+export type TOCItem = TOCItemImported;
 
 export type LoadedMDXContent<FrontMatter, Metadata, Assets = undefined> = {
   /** As verbatim declared in the MDX document. */