@docusaurus/mdx-loader 3.5.2 → 3.6.0

package/src/remark/transformLinks/index.ts

@@ -12,8 +12,8 @@ import {
   toMessageRelativeFilePath,
   posixPath,
   escapePath,
-  getFileLoaderUtils,
   findAsyncSequential,
+  getFileLoaderUtils,
 } from '@docusaurus/utils';
 import escapeHtml from 'escape-html';
 import {assetRequireAttributeValue, transformNode} from '../utils';
@@ -24,10 +24,6 @@ import type {MdxJsxTextElement} from 'mdast-util-mdx';
 import type {Parent} from 'unist';
 import type {Link, Literal} from 'mdast';
 
-const {
-  loaders: {inlineMarkdownLinkFileLoader},
-} = getFileLoaderUtils();
-
 type PluginOptions = {
   staticDirs: string[];
   siteDir: string;
@@ -35,6 +31,7 @@ type PluginOptions = {
 
 type Context = PluginOptions & {
   filePath: string;
+  inlineMarkdownLinkFileLoader: string;
 };
 
 type Target = [node: Link, index: number, parent: Parent];
@@ -45,7 +42,7 @@ type Target = [node: Link, index: number, parent: Parent];
 async function toAssetRequireNode(
   [node]: Target,
   assetPath: string,
-  filePath: string,
+  context: Context,
 ) {
   // MdxJsxTextElement => see https://github.com/facebook/docusaurus/pull/8288#discussion_r1125871405
   const jsxNode = node as unknown as MdxJsxTextElement;
@@ -53,7 +50,7 @@ async function toAssetRequireNode(
 
   // require("assets/file.pdf") means requiring from a package called assets
   const relativeAssetPath = `./${posixPath(
-    path.relative(path.dirname(filePath), assetPath),
+    path.relative(path.dirname(context.filePath), assetPath),
   )}`;
 
   const parsedUrl = url.parse(node.url);
@@ -65,7 +62,9 @@ async function toAssetRequireNode(
     path.extname(relativeAssetPath) === '.json'
       ? `${relativeAssetPath.replace('.json', '.raw')}!=`
       : ''
-  }${inlineMarkdownLinkFileLoader}${escapePath(relativeAssetPath) + search}`;
+  }${context.inlineMarkdownLinkFileLoader}${
+    escapePath(relativeAssetPath) + search
+  }`;
 
   attributes.push({
     type: 'mdxJsxAttribute',
@@ -196,7 +195,7 @@ async function processLinkNode(target: Target, context: Context) {
     context,
   );
   if (assetPath) {
-    await toAssetRequireNode(target, assetPath, context.filePath);
+    await toAssetRequireNode(target, assetPath, context);
   }
 }
 
@@ -204,14 +203,19 @@ export default function plugin(options: PluginOptions): Transformer {
   return async (root, vfile) => {
     const {visit} = await import('unist-util-visit');
 
+    const fileLoaderUtils = getFileLoaderUtils(
+      vfile.data.compilerName === 'server',
+    );
+    const context: Context = {
+      ...options,
+      filePath: vfile.path!,
+      inlineMarkdownLinkFileLoader:
+        fileLoaderUtils.loaders.inlineMarkdownLinkFileLoader,
+    };
+
     const promises: Promise<void>[] = [];
     visit(root, 'link', (node: Link, index, parent) => {
-      promises.push(
-        processLinkNode([node, index, parent!], {
-          ...options,
-          filePath: vfile.path!,
-        }),
-      );
+      promises.push(processLinkNode([node, index, parent!], context));
     });
     await Promise.all(promises);
   };

package/src/remark/unusedDirectives/index.ts

@@ -155,6 +155,7 @@ const plugin: Plugin = function plugin(this: Processor): Transformer {
     // We only enable these warnings for the client compiler
     // This avoids emitting duplicate warnings in prod mode
     // Note: the client compiler is used in both dev/prod modes
+    // Also: the client compiler is what gets used when using crossCompilerCache
     if (file.data.compilerName === 'client') {
       logUnusedDirectivesWarning({
         directives: unusedDirectives,

package/src/types.d.mts

@@ -28,7 +28,9 @@ declare module 'unist' {
 }
 
 declare module 'mdast' {
-  interface HeadingData {
+  interface Data {
     id?: string;
+    hName?: string;
+    hProperties?: Record<string, unknown>;
   }
 }

package/src/utils.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 logger from '@docusaurus/logger';
+import {escapePath, type WebpackCompilerName} from '@docusaurus/utils';
+import {getProcessor, type SimpleProcessorResult} from './processor';
+import {validateMDXFrontMatter} from './frontMatter';
+import preprocessor from './preprocessor';
+import type {Options} from './options';
+
+/**
+ * Converts assets an object with Webpack require calls code.
+ * This is useful for mdx files to reference co-located assets using relative
+ * paths. Those assets should enter the Webpack assets pipeline and be hashed.
+ * For now, we only handle that for images and paths starting with `./`:
+ *
+ * `{image: "./myImage.png"}` => `{image: require("./myImage.png")}`
+ */
+export function createAssetsExportCode({
+  assets,
+  inlineMarkdownAssetImageFileLoader,
+}: {
+  assets: unknown;
+  inlineMarkdownAssetImageFileLoader: string;
+}): string {
+  if (
+    typeof assets !== 'object' ||
+    !assets ||
+    Object.keys(assets).length === 0
+  ) {
+    return 'undefined';
+  }
+
+  // TODO implementation can be completed/enhanced
+  function createAssetValueCode(assetValue: unknown): string | undefined {
+    if (Array.isArray(assetValue)) {
+      const arrayItemCodes = assetValue.map(
+        (item: unknown) => createAssetValueCode(item) ?? 'undefined',
+      );
+      return `[${arrayItemCodes.join(', ')}]`;
+    }
+    // Only process string values starting with ./
+    // We could enhance this logic and check if file exists on disc?
+    if (typeof assetValue === 'string' && assetValue.startsWith('./')) {
+      // TODO do we have other use-cases than image assets?
+      // Probably not worth adding more support, as we want to move to Webpack 5 new asset system (https://github.com/facebook/docusaurus/pull/4708)
+      return `require("${inlineMarkdownAssetImageFileLoader}${escapePath(
+        assetValue,
+      )}").default`;
+    }
+    return undefined;
+  }
+
+  const assetEntries = Object.entries(assets);
+
+  const codeLines = assetEntries
+    .map(([key, value]: [string, unknown]) => {
+      const assetRequireCode = createAssetValueCode(value);
+      return assetRequireCode ? `"${key}": ${assetRequireCode},` : undefined;
+    })
+    .filter(Boolean);
+
+  return `{\n${codeLines.join('\n')}\n}`;
+}
+
+/**
+ * data.contentTitle is set by the remark contentTitle plugin
+ */
+export function extractContentTitleData(data: {
+  [key: string]: unknown;
+}): string | undefined {
+  return data.contentTitle as string | undefined;
+}
+
+export async function compileToJSX({
+  filePath,
+  fileContent,
+  frontMatter,
+  options,
+  compilerName,
+}: {
+  filePath: string;
+  fileContent: string;
+  frontMatter: Record<string, unknown>;
+  options: Options;
+  compilerName: WebpackCompilerName;
+}): Promise<SimpleProcessorResult> {
+  const preprocessedFileContent = preprocessor({
+    fileContent,
+    filePath,
+    admonitions: options.admonitions,
+    markdownConfig: options.markdownConfig,
+  });
+
+  const mdxFrontMatter = validateMDXFrontMatter(frontMatter.mdx);
+
+  const processor = await getProcessor({
+    filePath,
+    options,
+    mdxFrontMatter,
+  });
+
+  try {
+    return await processor.process({
+      content: preprocessedFileContent,
+      filePath,
+      frontMatter,
+      compilerName,
+    });
+  } catch (errorUnknown) {
+    const error = errorUnknown as Error;
+
+    // MDX can emit errors that have useful extra attributes
+    const errorJSON = JSON.stringify(error, null, 2);
+    const errorDetails =
+      errorJSON === '{}'
+        ? // regular JS error case: print stacktrace
+          error.stack ?? 'N/A'
+        : // MDX error: print extra attributes + stacktrace
+          `${errorJSON}\n${error.stack}`;
+
+    throw new Error(
+      `MDX compilation failed for file ${logger.path(filePath)}\nCause: ${
+        error.message
+      }\nDetails:\n${errorDetails}`,
+      // TODO error cause doesn't seem to be used by Webpack stats.errors :s
+      {cause: error},
+    );
+  }
+}
+
+// TODO Docusaurus v4, remove temporary polyfill when upgrading to Node 22+
+export interface PromiseWithResolvers<T> {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: any) => void;
+}
+// TODO Docusaurus v4, remove temporary polyfill when upgrading to Node 22+
+export function promiseWithResolvers<T>(): PromiseWithResolvers<T> {
+  // @ts-expect-error: it's fine
+  const out: PromiseWithResolvers<T> = {};
+  out.promise = new Promise((resolve, reject) => {
+    out.resolve = resolve;
+    out.reject = reject;
+  });
+  return out;
+}