refactor(mdx-loader): refactor mdx-loader, expose loader creation utils (#10450)

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

@@ -5,20 +5,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
 import {
   DEFAULT_PARSE_FRONT_MATTER,
-  escapePath,
   getFileLoaderUtils,
   getWebpackLoaderCompilerName,
 } from '@docusaurus/utils';
 import stringifyObject from 'stringify-object';
-import preprocessor from './preprocessor';
-import {validateMDXFrontMatter} from './frontMatter';
-import {createProcessorCached} from './processor';
+import {
+  compileToJSX,
+  createAssetsExportCode,
+  extractContentTitleData,
+  readMetadataPath,
+} from './utils';
+import type {
+  SimpleProcessors,
+  MDXOptions,
+  SimpleProcessorResult,
+} from './processor';
 import type {ResolveMarkdownLink} from './remark/resolveMarkdownLinks';
-import type {MDXOptions} from './processor';
 
 import type {MarkdownConfig} from '@docusaurus/types';
 import type {LoaderContext} from 'webpack';
@@ -43,98 +48,11 @@ export type Options = Partial<MDXOptions> & {
     metadata: {[key: string]: unknown};
   }) => {[key: string]: unknown};
   resolveMarkdownLink?: ResolveMarkdownLink;
+
+  // Will usually be created by "createMDXLoaderItem"
+  processors?: SimpleProcessors;
 };
 
-/**
- * When this throws, it generally means that there's no metadata file associated
- * with this MDX document. It can happen when using MDX partials (usually
- * starting with _). That's why it's important to provide the `isMDXPartial`
- * function in config
- */
-async function readMetadataPath(metadataPath: string) {
-  try {
-    return await fs.readFile(metadataPath, 'utf8');
-  } catch (err) {
-    logger.error`MDX loader can't read MDX metadata file path=${metadataPath}. Maybe the isMDXPartial option function was not provided?`;
-    throw err;
-  }
-}
-
-/**
- * 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")}`
- */
-function createAssetsExportCode({
-  assets,
-  inlineMarkdownAssetImageFileLoader,
-}: {
-  assets: unknown;
-  inlineMarkdownAssetImageFileLoader: 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}`;
-}
-
-// TODO temporary, remove this after v3.1?
-// Some plugin authors use our mdx-loader, despite it not being public API
-// see https://github.com/facebook/docusaurus/issues/8298
-function ensureMarkdownConfig(reqOptions: Options) {
-  if (!reqOptions.markdownConfig) {
-    throw new Error(
-      'Docusaurus v3+ requires MDX loader options.markdownConfig - plugin authors using the MDX loader should make sure to provide that option',
-    );
-  }
-}
-
-/**
- * data.contentTitle is set by the remark contentTitle plugin
- */
-function extractContentTitleData(data: {
-  [key: string]: unknown;
-}): string | undefined {
-  return data.contentTitle as string | undefined;
-}
-
 export async function mdxLoader(
   this: LoaderContext<Options>,
   fileContent: string,
@@ -144,59 +62,25 @@ export async function mdxLoader(
   const filePath = this.resourcePath;
   const options: Options = this.getOptions();
 
-  ensureMarkdownConfig(options);
-
   const {frontMatter} = await options.markdownConfig.parseFrontMatter({
     filePath,
     fileContent,
     defaultParseFrontMatter: DEFAULT_PARSE_FRONT_MATTER,
   });
-  const mdxFrontMatter = validateMDXFrontMatter(frontMatter.mdx);
-
-  const preprocessedContent = preprocessor({
-    fileContent,
-    filePath,
-    admonitions: options.admonitions,
-    markdownConfig: options.markdownConfig,
-  });
 
   const hasFrontMatter = Object.keys(frontMatter).length > 0;
 
-  const processor = await createProcessorCached({
-    filePath,
-    options,
-    mdxFrontMatter,
-  });
-
-  let result: {content: string; data: {[key: string]: unknown}};
+  let result: SimpleProcessorResult;
   try {
-    result = await processor.process({
-      content: preprocessedContent,
+    result = await compileToJSX({
+      fileContent,
       filePath,
       frontMatter,
+      options,
       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}`;
-
-    return callback(
-      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},
-      ),
-    );
+  } catch (error) {
+    return callback(error as Error);
   }
 
   const contentTitle = extractContentTitleData(result.data);