@docusaurus/mdx-loader 2.4.1 → 3.0.0-beta.0

package/src/remark/toc/index.ts

@@ -8,28 +8,42 @@
 import {parse, type ParserOptions} from '@babel/parser';
 import traverse from '@babel/traverse';
 import stringifyObject from 'stringify-object';
-import toString from 'mdast-util-to-string';
 import visit from 'unist-util-visit';
 import {toValue} from '../utils';
-
 import type {Identifier} from '@babel/types';
-import type {TOCItem} from '../..';
 import type {Node, Parent} from 'unist';
 import type {Heading, Literal} from 'mdast';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 
+// TODO as of April 2023, no way to import/re-export this ESM type easily :/
+// This might change soon, likely after TS 5.2
+// See https://github.com/microsoft/TypeScript/issues/49721#issuecomment-1517839391
+// import type {Plugin} from 'unified';
+type Plugin = any; // TODO fix this asap
+
+export type TOCItem = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+};
+
 const parseOptions: ParserOptions = {
   plugins: ['jsx'],
   sourceType: 'module',
 };
 
-const name = 'toc';
-
-const isImport = (child: Node): child is Literal => child.type === 'import';
+const isImport = (child: any): child is Literal =>
+  child.type === 'mdxjsEsm' && child.value.startsWith('import');
 const hasImports = (index: number) => index > -1;
-const isExport = (child: Node): child is Literal => child.type === 'export';
+const isExport = (child: any): child is Literal =>
+  child.type === 'mdxjsEsm' && child.value.startsWith('export');
+
+interface PluginOptions {
+  name?: string;
+}
 
-const isTarget = (child: Literal) => {
+const isTarget = (child: Literal, name: string) => {
   let found = false;
   const ast = parse(child.value, parseOptions);
   traverse(ast, {
@@ -42,24 +56,23 @@ const isTarget = (child: Literal) => {
   return found;
 };
 
-const getOrCreateExistingTargetIndex = (children: Node[]) => {
+const getOrCreateExistingTargetIndex = async (
+  children: Node[],
+  name: string,
+) => {
   let importsIndex = -1;
   let targetIndex = -1;
 
   children.forEach((child, index) => {
     if (isImport(child)) {
       importsIndex = index;
-    } else if (isExport(child) && isTarget(child)) {
+    } else if (isExport(child) && isTarget(child, name)) {
       targetIndex = index;
     }
   });
 
   if (targetIndex === -1) {
-    const target = {
-      default: false,
-      type: 'export',
-      value: `export const ${name} = [];`,
-    };
+    const target = await createExportNode(name, []);
 
     targetIndex = hasImports(importsIndex) ? importsIndex + 1 : 0;
     children.splice(targetIndex, 0, target);
@@ -68,31 +81,72 @@ const getOrCreateExistingTargetIndex = (children: Node[]) => {
   return targetIndex;
 };
 
-export default function plugin(): Transformer {
-  return (root) => {
+const plugin: Plugin = function plugin(
+  options: PluginOptions = {},
+): Transformer {
+  const name = options.name || 'toc';
+
+  return async (root) => {
+    const {toString} = await import('mdast-util-to-string');
     const headings: TOCItem[] = [];
 
-    visit(root, 'heading', (child: Heading, index, parent) => {
+    visit(root, 'heading', (child: Heading) => {
       const value = toString(child);
 
-      // depth: 1 headings are titles and not included in the TOC
-      if (parent !== root || !value || child.depth < 2) {
+      // depth:1 headings are titles and not included in the TOC
+      if (!value || child.depth < 2) {
         return;
       }
 
       headings.push({
-        value: toValue(child),
+        value: toValue(child, toString),
         id: child.data!.id as string,
         level: child.depth,
       });
     });
     const {children} = root as Parent<Literal>;
-    const targetIndex = getOrCreateExistingTargetIndex(children);
+    const targetIndex = await getOrCreateExistingTargetIndex(children, name);
 
-    if (headings.length) {
-      children[targetIndex]!.value = `export const ${name} = ${stringifyObject(
-        headings,
-      )};`;
+    if (headings?.length) {
+      children[targetIndex] = await createExportNode(name, headings);
     }
   };
+};
+
+export default plugin;
+
+async function createExportNode(name: string, object: any) {
+  const {valueToEstree} = await import('estree-util-value-to-estree');
+
+  return {
+    type: 'mdxjsEsm',
+    value: `export const ${name} = ${stringifyObject(object)}`,
+    data: {
+      estree: {
+        type: 'Program',
+        body: [
+          {
+            type: 'ExportNamedDeclaration',
+            declaration: {
+              type: 'VariableDeclaration',
+              declarations: [
+                {
+                  type: 'VariableDeclarator',
+                  id: {
+                    type: 'Identifier',
+                    name,
+                  },
+                  init: valueToEstree(object),
+                },
+              ],
+              kind: 'const',
+            },
+            specifiers: [],
+            source: null,
+          },
+        ],
+        sourceType: 'module',
+      },
+    },
+  };
 }

package/src/remark/transformImage/index.ts

@@ -9,7 +9,6 @@ import path from 'path';
 import url from 'url';
 import fs from 'fs-extra';
 import {promisify} from 'util';
-import logger from '@docusaurus/logger';
 import {
   toMessageRelativeFilePath,
   posixPath,
@@ -20,15 +19,20 @@ import {
 import visit from 'unist-util-visit';
 import escapeHtml from 'escape-html';
 import sizeOf from 'image-size';
+import logger from '@docusaurus/logger';
+import {assetRequireAttributeValue} from '../utils';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import type {MdxJsxTextElement} from 'mdast-util-mdx';
+import type {Image} from 'mdast';
 import type {Parent} from 'unist';
-import type {Image, Literal} from 'mdast';
 
 const {
   loaders: {inlineMarkdownImageFileLoader},
 } = getFileLoaderUtils();
 
-export type PluginOptions = {
+type PluginOptions = {
   staticDirs: string[];
   siteDir: string;
 };
@@ -40,10 +44,14 @@ type Context = PluginOptions & {
 type Target = [node: Image, index: number, parent: Parent];
 
 async function toImageRequireNode(
-  [node, index, parent]: Target,
+  [node]: Target,
   imagePath: string,
   filePath: string,
 ) {
+  // MdxJsxTextElement => see https://github.com/facebook/docusaurus/pull/8288#discussion_r1125871405
+  const jsxNode = node as unknown as MdxJsxTextElement;
+  const attributes: MdxJsxTextElement['attributes'] = [];
+
   let relativeImagePath = posixPath(
     path.relative(path.dirname(filePath), imagePath),
   );
@@ -52,21 +60,46 @@ async function toImageRequireNode(
   const parsedUrl = url.parse(node.url);
   const hash = parsedUrl.hash ?? '';
   const search = parsedUrl.search ?? '';
-
-  const alt = node.alt ? `alt={"${escapeHtml(node.alt)}"} ` : '';
-  const src = `require("${inlineMarkdownImageFileLoader}${
+  const requireString = `${inlineMarkdownImageFileLoader}${
     escapePath(relativeImagePath) + search
-  }").default${hash ? ` + '${hash}'` : ''}`;
-  const title = node.title ? ` title="${escapeHtml(node.title)}"` : '';
-  let width = '';
-  let height = '';
+  }`;
+  if (node.alt) {
+    attributes.push({
+      type: 'mdxJsxAttribute',
+      name: 'alt',
+      value: escapeHtml(node.alt),
+    });
+  }
+
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'src',
+    value: assetRequireAttributeValue(requireString, hash),
+  });
+
+  if (node.title) {
+    attributes.push({
+      type: 'mdxJsxAttribute',
+      name: 'title',
+      value: escapeHtml(node.title),
+    });
+  }
+
   try {
     const size = (await promisify(sizeOf)(imagePath))!;
     if (size.width) {
-      width = ` width="${size.width}"`;
+      attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'width',
+        value: String(size.width),
+      });
     }
     if (size.height) {
-      height = ` height="${size.height}"`;
+      attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'height',
+        value: String(size.height),
+      });
     }
   } catch (err) {
     // Workaround for https://github.com/yarnpkg/berry/pull/3889#issuecomment-1034469784
@@ -77,12 +110,14 @@ ${(err as Error).message}`;
     }
   }
 
-  const jsxNode: Literal = {
-    type: 'jsx',
-    value: `<img ${alt}src={${src}}${title}${width}${height} />`,
-  };
+  Object.keys(jsxNode).forEach(
+    (key) => delete jsxNode[key as keyof typeof jsxNode],
+  );
 
-  parent.children.splice(index, 1, jsxNode);
+  jsxNode.type = 'mdxJsxTextElement';
+  jsxNode.name = 'img';
+  jsxNode.attributes = attributes;
+  jsxNode.children = [];
 }
 
 async function ensureImageFileExist(imagePath: string, sourceFilePath: string) {
@@ -122,7 +157,7 @@ async function getImageAbsolutePath(
     }
     return imageFilePath;
   }
-  // Relative paths are resolved against the source file's folder.
+  // relative paths are resolved against the source file's folder
   const imageFilePath = path.join(
     path.dirname(filePath),
     decodeURIComponent(imagePath),

package/src/remark/transformLinks/index.ts

@@ -17,8 +17,11 @@ import {
 } from '@docusaurus/utils';
 import visit from 'unist-util-visit';
 import escapeHtml from 'escape-html';
-import {stringifyContent} from '../utils';
+import {assetRequireAttributeValue} from '../utils';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import type {MdxJsxTextElement} from 'mdast-util-mdx';
 import type {Parent} from 'unist';
 import type {Link, Literal} from 'mdast';
 
@@ -26,7 +29,7 @@ const {
   loaders: {inlineMarkdownLinkFileLoader},
 } = getFileLoaderUtils();
 
-export type PluginOptions = {
+type PluginOptions = {
   staticDirs: string[];
   siteDir: string;
 };
@@ -40,11 +43,15 @@ type Target = [node: Link, index: number, parent: Parent];
 /**
  * Transforms the link node to a JSX `<a>` element with a `require()` call.
  */
-function toAssetRequireNode(
-  [node, index, parent]: Target,
+async function toAssetRequireNode(
+  [node]: Target,
   assetPath: string,
   filePath: string,
 ) {
+  // MdxJsxTextElement => see https://github.com/facebook/docusaurus/pull/8288#discussion_r1125871405
+  const jsxNode = node as unknown as MdxJsxTextElement;
+  const attributes: MdxJsxTextElement['attributes'] = [];
+
   // require("assets/file.pdf") means requiring from a package called assets
   const relativeAssetPath = `./${posixPath(
     path.relative(path.dirname(filePath), assetPath),
@@ -54,23 +61,43 @@ function toAssetRequireNode(
   const hash = parsedUrl.hash ?? '';
   const search = parsedUrl.search ?? '';
 
-  const href = `require('${
+  const requireString = `${
     // A hack to stop Webpack from using its built-in loader to parse JSON
     path.extname(relativeAssetPath) === '.json'
       ? `${relativeAssetPath.replace('.json', '.raw')}!=`
       : ''
-  }${inlineMarkdownLinkFileLoader}${
-    escapePath(relativeAssetPath) + search
-  }').default${hash ? ` + '${hash}'` : ''}`;
-  const children = stringifyContent(node);
-  const title = node.title ? ` title="${escapeHtml(node.title)}"` : '';
-
-  const jsxNode: Literal = {
-    type: 'jsx',
-    value: `<a target="_blank" href={${href}}${title}>${children}</a>`,
-  };
+  }${inlineMarkdownLinkFileLoader}${escapePath(relativeAssetPath) + search}`;
+
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'target',
+    value: '_blank',
+  });
+
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'href',
+    value: assetRequireAttributeValue(requireString, hash),
+  });
+
+  if (node.title) {
+    attributes.push({
+      type: 'mdxJsxAttribute',
+      name: 'title',
+      value: escapeHtml(node.title),
+    });
+  }
+
+  const {children} = node;
+
+  Object.keys(jsxNode).forEach(
+    (key) => delete jsxNode[key as keyof typeof jsxNode],
+  );
 
-  parent.children.splice(index, 1, jsxNode);
+  jsxNode.type = 'mdxJsxTextElement';
+  jsxNode.name = 'a';
+  jsxNode.attributes = attributes;
+  jsxNode.children = children;
 }
 
 async function ensureAssetFileExist(assetPath: string, sourceFilePath: string) {
@@ -144,7 +171,7 @@ async function processLinkNode(target: Target, context: Context) {
     context,
   );
   if (assetPath) {
-    toAssetRequireNode(target, assetPath, context.filePath);
+    await toAssetRequireNode(target, assetPath, context.filePath);
   }
 }
 

package/src/remark/utils/index.ts

@@ -6,31 +6,130 @@
  */
 
 import escapeHtml from 'escape-html';
-import toString from 'mdast-util-to-string';
 import type {Parent} from 'unist';
 import type {PhrasingContent, Heading} from 'mdast';
+import type {
+  MdxJsxAttribute,
+  MdxJsxAttributeValueExpression,
+  MdxJsxTextElement,
+  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+} from 'mdast-util-mdx';
 
-export function stringifyContent(node: Parent): string {
-  return (node.children as PhrasingContent[]).map(toValue).join('');
+export function stringifyContent(
+  node: Parent,
+  toString: (param: unknown) => string, // TODO weird but works
+): string {
+  return (node.children as PhrasingContent[])
+    .map((item) => toValue(item, toString))
+    .join('');
 }
 
-export function toValue(node: PhrasingContent | Heading): string {
+// TODO This is really a workaround, and not super reliable
+// For now we only support serializing tagName, className and content
+// Can we implement the TOC with real JSX nodes instead of html strings later?
+function mdxJsxTextElementToHtml(
+  element: MdxJsxTextElement,
+  toString: (param: unknown) => string, // TODO weird but works
+): string {
+  const tag = element.name;
+
+  const attributes = element.attributes.filter(
+    (child): child is MdxJsxAttribute => child.type === 'mdxJsxAttribute',
+  );
+
+  const classAttribute =
+    attributes.find((attr) => attr.name === 'className') ??
+    attributes.find((attr) => attr.name === 'class');
+
+  const classAttributeString = classAttribute
+    ? `class="${escapeHtml(String(classAttribute.value))}"`
+    : ``;
+
+  const allAttributes = classAttributeString ? ` ${classAttributeString}` : '';
+
+  const content = stringifyContent(element, toString);
+
+  return `<${tag}${allAttributes}>${content}</${tag}>`;
+}
+
+export function toValue(
+  node: PhrasingContent | Heading,
+  toString: (param: unknown) => string, // TODO weird but works
+): string {
   switch (node.type) {
+    case 'mdxJsxTextElement': {
+      return mdxJsxTextElementToHtml(node as MdxJsxTextElement, toString);
+    }
     case 'text':
       return escapeHtml(node.value);
     case 'heading':
-      return stringifyContent(node);
+      return stringifyContent(node, toString);
     case 'inlineCode':
       return `<code>${escapeHtml(node.value)}</code>`;
     case 'emphasis':
-      return `<em>${stringifyContent(node)}</em>`;
+      return `<em>${stringifyContent(node, toString)}</em>`;
     case 'strong':
-      return `<strong>${stringifyContent(node)}</strong>`;
+      return `<strong>${stringifyContent(node, toString)}</strong>`;
     case 'delete':
-      return `<del>${stringifyContent(node)}</del>`;
+      return `<del>${stringifyContent(node, toString)}</del>`;
     case 'link':
-      return stringifyContent(node);
+      return stringifyContent(node, toString);
     default:
       return toString(node);
   }
 }
+
+export function assetRequireAttributeValue(
+  requireString: string,
+  hash: string,
+): MdxJsxAttributeValueExpression {
+  return {
+    type: 'mdxJsxAttributeValueExpression',
+    value: `require("${requireString}").default${hash && ` + '${hash}'`}`,
+    data: {
+      estree: {
+        type: 'Program',
+        body: [
+          {
+            type: 'ExpressionStatement',
+            expression: {
+              type: 'BinaryExpression',
+              left: {
+                type: 'MemberExpression',
+                object: {
+                  type: 'CallExpression',
+                  callee: {
+                    type: 'Identifier',
+                    name: 'require',
+                  },
+                  arguments: [
+                    {
+                      type: 'Literal',
+                      value: requireString,
+                      raw: `"${requireString}"`,
+                    },
+                  ],
+                  optional: false,
+                },
+                property: {
+                  type: 'Identifier',
+                  name: 'default',
+                },
+                computed: false,
+                optional: false,
+              },
+              operator: '+',
+              right: {
+                type: 'Literal',
+                value: hash,
+                raw: `"${hash}"`,
+              },
+            },
+          },
+        ],
+        sourceType: 'module',
+        comments: [],
+      },
+    },
+  };
+}

package/lib/remark/unwrapMdxCodeBlocks/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/remark/unwrapMdxCodeBlocks/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAC,WAAW,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AASpD,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,CAe3D"}

package/lib/remark/unwrapMdxCodeBlocks/index.js

@@ -1,29 +0,0 @@
-"use strict";
-/**
- * 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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-const unist_util_visit_1 = tslib_1.__importDefault(require("unist-util-visit"));
-// This plugin is mostly to help integrating Docusaurus with translation systems
-// that do not support well MDX embedded JSX syntax (like Crowdin).
-// We wrap the JSX syntax in code blocks so that translation tools don't mess up
-// with the markup, but the JSX inside such code blocks should still be
-// evaluated as JSX
-// See https://github.com/facebook/docusaurus/pull/4278
-function plugin() {
-    return (root) => {
-        (0, unist_util_visit_1.default)(root, 'code', (node, index, parent) => {
-            if (node.lang === 'mdx-code-block') {
-                const newChildren = this.parse(node.value).children;
-                // Replace the mdx code block by its content, parsed
-                parent.children.splice(parent.children.indexOf(node), 1, ...newChildren);
-            }
-        });
-    };
-}
-exports.default = plugin;
-//# sourceMappingURL=index.js.map

package/lib/remark/unwrapMdxCodeBlocks/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/remark/unwrapMdxCodeBlocks/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,gFAAqC;AAIrC,gFAAgF;AAChF,mEAAmE;AACnE,gFAAgF;AAChF,uEAAuE;AACvE,mBAAmB;AACnB,uDAAuD;AACvD,SAAwB,MAAM;IAC5B,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,IAAA,0BAAK,EAAC,IAAI,EAAE,MAAM,EAAE,CAAC,IAAU,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YAChD,IAAI,IAAI,CAAC,IAAI,KAAK,gBAAgB,EAAE;gBAClC,MAAM,WAAW,GAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAY,CAAC,QAAQ,CAAC;gBAEhE,oDAAoD;gBACpD,MAAO,CAAC,QAAQ,CAAC,MAAM,CACrB,MAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAC9B,CAAC,EACD,GAAG,WAAW,CACf,CAAC;aACH;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAfD,yBAeC"}

package/src/deps.d.ts

@@ -1,31 +0,0 @@
-/**
- * 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.
- */
-
-// TODO Types provided by MDX 2.0 https://github.com/mdx-js/mdx/blob/main/packages/mdx/types/index.d.ts
-declare module '@mdx-js/mdx' {
-  import type {Processor, Plugin} from 'unified';
-
-  type MDXPlugin =
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [Plugin<any[]>, any] | Plugin<any[]>;
-
-  type Options = {
-    filepath?: string;
-    skipExport?: boolean;
-    wrapExport?: string;
-    remarkPlugins?: MDXPlugin[];
-    rehypePlugins?: MDXPlugin[];
-  };
-
-  export function sync(content: string, options?: Options): string;
-  export function createMdxAstCompiler(options?: Options): Processor;
-  export function createCompiler(options?: Options): Processor;
-  export default function mdx(
-    content: string,
-    options?: Options,
-  ): Promise<string>;
-}

package/src/remark/unwrapMdxCodeBlocks/index.ts

@@ -1,33 +0,0 @@
-/**
- * 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 visit from 'unist-util-visit';
-import type {Transformer, Processor} from 'unified';
-import type {Code, Parent} from 'mdast';
-
-// This plugin is mostly to help integrating Docusaurus with translation systems
-// that do not support well MDX embedded JSX syntax (like Crowdin).
-// We wrap the JSX syntax in code blocks so that translation tools don't mess up
-// with the markup, but the JSX inside such code blocks should still be
-// evaluated as JSX
-// See https://github.com/facebook/docusaurus/pull/4278
-export default function plugin(this: Processor): Transformer {
-  return (root) => {
-    visit(root, 'code', (node: Code, index, parent) => {
-      if (node.lang === 'mdx-code-block') {
-        const newChildren = (this.parse(node.value) as Parent).children;
-
-        // Replace the mdx code block by its content, parsed
-        parent!.children.splice(
-          parent!.children.indexOf(node),
-          1,
-          ...newChildren,
-        );
-      }
-    });
-  };
-}