@docusaurus/mdx-loader 2.0.0-beta.13 → 2.0.0-beta.15

package/src/index.ts

@@ -7,7 +7,7 @@
 
 import {readFile} from 'fs-extra';
 import mdx from '@mdx-js/mdx';
-import chalk from 'chalk';
+import logger from '@docusaurus/logger';
 import emoji from 'remark-emoji';
 import {
   parseFrontMatter,
@@ -124,12 +124,17 @@ export default async function mdxLoader(
     remarkPlugins: [
       ...(reqOptions.beforeDefaultRemarkPlugins || []),
       ...DEFAULT_OPTIONS.remarkPlugins,
-      [transformImage, {staticDirs: reqOptions.staticDirs, filePath}],
+      [
+        transformImage,
+        {
+          staticDirs: reqOptions.staticDirs,
+          siteDir: reqOptions.siteDir,
+        },
+      ],
       [
         transformLinks,
         {
           staticDirs: reqOptions.staticDirs,
-          filePath,
           siteDir: reqOptions.siteDir,
         },
       ],
@@ -151,7 +156,7 @@ export default async function mdxLoader(
   }
 
   // MDX partials are MDX files starting with _ or in a folder starting with _
-  // Partial are not expected to have an associated metadata file or frontmatter
+  // Partial are not expected to have an associated metadata file or front matter
   const isMDXPartial = options.isMDXPartial && options.isMDXPartial(filePath);
   if (isMDXPartial && hasFrontMatter) {
     const errorMessage = `Docusaurus MDX partial files should not contain FrontMatter.
@@ -164,7 +169,7 @@ ${JSON.stringify(frontMatter, null, 2)}`;
       if (shouldError) {
         return callback(new Error(errorMessage));
       } else {
-        console.warn(chalk.yellow(errorMessage));
+        logger.warn(errorMessage);
       }
     }
   }

package/src/remark/headings/index.ts

@@ -8,7 +8,7 @@
 /* Based on remark-slug (https://github.com/remarkjs/remark-slug) and gatsby-remark-autolink-headers (https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-remark-autolink-headers) */
 
 import {parseMarkdownHeadingId, createSlugger} from '@docusaurus/utils';
-import visit, {Visitor} from 'unist-util-visit';
+import visit, {type Visitor} from 'unist-util-visit';
 import toString from 'mdast-util-to-string';
 import type {Transformer} from 'unified';
 import type {Parent} from 'unist';

package/src/remark/toc/index.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {parse, ParserOptions} from '@babel/parser';
+import {parse, type ParserOptions} from '@babel/parser';
 import type {Identifier} from '@babel/types';
 import traverse from '@babel/traverse';
 import stringifyObject from 'stringify-object';

package/src/remark/toc/search.ts

@@ -6,7 +6,7 @@
  */
 
 import toString from 'mdast-util-to-string';
-import visit, {Visitor} from 'unist-util-visit';
+import visit from 'unist-util-visit';
 import {toValue} from '../utils';
 import type {TOCItem} from '@docusaurus/types';
 import type {Node} from 'unist';
@@ -26,7 +26,7 @@ interface SearchItem {
 export default function search(node: Node): TOCItem[] {
   const headings: SearchItem[] = [];
 
-  const visitor: Visitor<Heading> = (child, _index, parent) => {
+  visit(node, 'heading', (child: Heading, _index, parent) => {
     const value = toString(child);
 
     // depth:1 headings are titles and not included in the TOC
@@ -44,11 +44,9 @@ export default function search(node: Node): TOCItem[] {
       level: child.depth,
       parentIndex: -1,
     });
-  };
-
-  visit(node, 'heading', visitor);
+  });
 
-  // Keep track of which previous index would be the current heading's direcy parent.
+  // Keep track of which previous index would be the current heading's direct parent.
   // Each entry <i> is the last index of the `headings` array at heading level <i>.
   // We will modify these indices as we iterate through all headings.
   // e.g. if an ### H3 was last seen at index 2, then prevIndexForLevel[3] === 2

package/src/remark/transformImage/index.ts

@@ -5,53 +5,80 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import visit from 'unist-util-visit';
-import path from 'path';
-import url from 'url';
-import fs from 'fs-extra';
-import escapeHtml from 'escape-html';
 import {
+  toMessageRelativeFilePath,
   posixPath,
   escapePath,
-  toMessageRelativeFilePath,
   getFileLoaderUtils,
+  findAsyncSequential,
 } from '@docusaurus/utils';
+import visit from 'unist-util-visit';
+import path from 'path';
+import url from 'url';
+import fs from 'fs-extra';
+import escapeHtml from 'escape-html';
+import sizeOf from 'image-size';
+import {promisify} from 'util';
 import type {Plugin, Transformer} from 'unified';
 import type {Image, Literal} from 'mdast';
+import logger from '@docusaurus/logger';
 
 const {
   loaders: {inlineMarkdownImageFileLoader},
 } = getFileLoaderUtils();
 
-interface PluginOptions {
-  filePath: string;
+type PluginOptions = {
   staticDirs: string[];
-}
+  siteDir: string;
+};
 
-const createJSX = (node: Image, pathUrl: string) => {
-  const jsxNode = node;
-  (jsxNode as unknown as Literal).type = 'jsx';
-  (jsxNode as unknown as Literal).value = `<img ${
-    node.alt ? `alt={"${escapeHtml(node.alt)}"} ` : ''
-  }${
-    node.url
-      ? `src={require("${inlineMarkdownImageFileLoader}${escapePath(
-          pathUrl,
-        )}").default}`
-      : ''
-  }${node.title ? ` title="${escapeHtml(node.title)}"` : ''} />`;
-
-  if (jsxNode.url) {
-    delete (jsxNode as Partial<Image>).url;
-  }
-  if (jsxNode.alt) {
-    delete jsxNode.alt;
-  }
-  if (jsxNode.title) {
-    delete jsxNode.title;
-  }
+type Context = PluginOptions & {
+  filePath: string;
 };
 
+async function toImageRequireNode(
+  node: Image,
+  imagePath: string,
+  filePath: string,
+) {
+  const jsxNode = node as Literal & Partial<Image>;
+  let relativeImagePath = posixPath(
+    path.relative(path.dirname(filePath), imagePath),
+  );
+  relativeImagePath = `./${relativeImagePath}`;
+
+  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}${
+    escapePath(relativeImagePath) + search
+  }").default${hash ? ` + '${hash}'` : ''}`;
+  const title = node.title ? ` title="${escapeHtml(node.title)}"` : '';
+  let width = '';
+  let height = '';
+  try {
+    const size = (await promisify(sizeOf)(imagePath))!;
+    if (size.width) {
+      width = ` width="${size.width}"`;
+    }
+    if (size.height) {
+      height = ` height="${size.height}"`;
+    }
+  } catch (e) {
+    logger.error`The image at path=${imagePath} can't be read correctly. Please ensure it's a valid image.
+${(e as Error).message}`;
+  }
+
+  Object.keys(jsxNode).forEach(
+    (key) => delete jsxNode[key as keyof typeof jsxNode],
+  );
+
+  (jsxNode as Literal).type = 'jsx';
+  jsxNode.value = `<img ${alt}src={${src}}${title}${width}${height} />`;
+}
+
 async function ensureImageFileExist(imagePath: string, sourceFilePath: string) {
   const imageExists = await fs.pathExists(imagePath);
   if (!imageExists) {
@@ -63,36 +90,53 @@ async function ensureImageFileExist(imagePath: string, sourceFilePath: string) {
   }
 }
 
-async function findImage(possiblePaths: string[], sourceFilePath: string) {
-  // eslint-disable-next-line no-restricted-syntax
-  for (const possiblePath of possiblePaths) {
-    if (await fs.pathExists(possiblePath)) {
-      return possiblePath;
+async function getImageAbsolutePath(
+  imagePath: string,
+  {siteDir, filePath, staticDirs}: Context,
+) {
+  if (imagePath.startsWith('@site/')) {
+    const imageFilePath = path.join(siteDir, imagePath.replace('@site/', ''));
+    await ensureImageFileExist(imageFilePath, filePath);
+    return imageFilePath;
+  } else if (path.isAbsolute(imagePath)) {
+    // absolute paths are expected to exist in the static folder
+    const possiblePaths = staticDirs.map((dir) => path.join(dir, imagePath));
+    const imageFilePath = await findAsyncSequential(
+      possiblePaths,
+      fs.pathExists,
+    );
+    if (!imageFilePath) {
+      throw new Error(
+        `Image ${possiblePaths
+          .map((p) => toMessageRelativeFilePath(p))
+          .join(' or ')} used in ${toMessageRelativeFilePath(
+          filePath,
+        )} not found.`,
+      );
     }
+    return imageFilePath;
+  }
+  // We try to convert image urls without protocol to images with require calls
+  // going through webpack ensures that image assets exist at build time
+  else {
+    // relative paths are resolved against the source file's folder
+    const imageFilePath = path.join(path.dirname(filePath), imagePath);
+    await ensureImageFileExist(imageFilePath, filePath);
+    return imageFilePath;
   }
-  throw new Error(
-    `Image ${possiblePaths
-      .map((p) => toMessageRelativeFilePath(p))
-      .join(' or ')} used in ${toMessageRelativeFilePath(
-      sourceFilePath,
-    )} not found.`,
-  );
 }
 
-async function processImageNode(
-  node: Image,
-  {filePath, staticDirs}: PluginOptions,
-) {
+async function processImageNode(node: Image, context: Context) {
   if (!node.url) {
     throw new Error(
       `Markdown image URL is mandatory in "${toMessageRelativeFilePath(
-        filePath,
+        context.filePath,
       )}" file`,
     );
   }
 
   const parsedUrl = url.parse(node.url);
-  if (parsedUrl.protocol) {
+  if (parsedUrl.protocol || !parsedUrl.pathname) {
     // pathname:// is an escape hatch,
     // in case user does not want his images to be converted to require calls going through webpack loader
     // we don't have to document this for now,
@@ -100,31 +144,20 @@ async function processImageNode(
     if (parsedUrl.protocol === 'pathname:') {
       node.url = node.url.replace('pathname://', '');
     }
+    return;
   }
-  // images without protocol
-  else if (path.isAbsolute(node.url)) {
-    // absolute paths are expected to exist in the static folder
-    const possibleImagePaths = staticDirs.map((dir) =>
-      path.join(dir, node.url),
-    );
-    const imagePath = await findImage(possibleImagePaths, filePath);
-    createJSX(node, posixPath(imagePath));
-  }
-  // We try to convert image urls without protocol to images with require calls
-  // going through webpack ensures that image assets exist at build time
-  else {
-    // relative paths are resolved against the source file's folder
-    const expectedImagePath = path.join(path.dirname(filePath), node.url);
-    await ensureImageFileExist(expectedImagePath, filePath);
-    createJSX(node, node.url.startsWith('./') ? node.url : `./${node.url}`);
-  }
+
+  const imagePath = await getImageAbsolutePath(parsedUrl.pathname, context);
+  await toImageRequireNode(node, imagePath, context.filePath);
 }
 
 const plugin: Plugin<[PluginOptions]> = (options) => {
-  const transformer: Transformer = async (root) => {
+  const transformer: Transformer = async (root, vfile) => {
     const promises: Promise<void>[] = [];
     visit(root, 'image', (node: Image) => {
-      promises.push(processImageNode(node, options));
+      promises.push(
+        processImageNode(node, {...options, filePath: vfile.path!}),
+      );
     });
     await Promise.all(promises);
   };

package/src/remark/transformLinks/index.ts

@@ -10,6 +10,7 @@ import {
   posixPath,
   escapePath,
   getFileLoaderUtils,
+  findAsyncSequential,
 } from '@docusaurus/utils';
 import visit from 'unist-util-visit';
 import path from 'path';
@@ -23,114 +24,87 @@ import type {Link, Literal} from 'mdast';
 const {
   loaders: {inlineMarkdownLinkFileLoader},
 } = getFileLoaderUtils();
-const hashRegex = /#.*$/;
 
-interface PluginOptions {
-  filePath: string;
+type PluginOptions = {
   staticDirs: string[];
   siteDir: string;
-}
+};
 
-async function ensureAssetFileExist(
-  fileSystemAssetPath: string,
-  sourceFilePath: string,
-) {
-  const assetExists = await fs.pathExists(fileSystemAssetPath);
-  if (!assetExists) {
-    throw new Error(
-      `Asset ${toMessageRelativeFilePath(
-        fileSystemAssetPath,
-      )} used in ${toMessageRelativeFilePath(sourceFilePath)} not found.`,
-    );
-  }
-}
+type Context = PluginOptions & {
+  filePath: string;
+};
 
 // transform the link node to a jsx link with a require() call
-function toAssetRequireNode({
-  node,
-  filePath,
-  requireAssetPath,
-}: {
-  node: Link;
-  filePath: string;
-  requireAssetPath: string;
-}) {
-  let relativeRequireAssetPath = posixPath(
-    path.relative(path.dirname(filePath), requireAssetPath),
+function toAssetRequireNode(node: Link, assetPath: string, filePath: string) {
+  const jsxNode = node as Literal & Partial<Link>;
+  let relativeAssetPath = posixPath(
+    path.relative(path.dirname(filePath), assetPath),
   );
-  const hash = hashRegex.test(node.url)
-    ? node.url.substr(node.url.indexOf('#'))
-    : '';
-
-  // nodejs does not like require("assets/file.pdf")
-  relativeRequireAssetPath = relativeRequireAssetPath.startsWith('.')
-    ? relativeRequireAssetPath
-    : `./${relativeRequireAssetPath}`;
-
-  const href = `require('${inlineMarkdownLinkFileLoader}${escapePath(
-    relativeRequireAssetPath,
-  )}').default${hash ? ` + '${hash}'` : ''}`;
+  // require("assets/file.pdf") means requiring from a package called assets
+  relativeAssetPath = `./${relativeAssetPath}`;
+
+  const parsedUrl = url.parse(node.url);
+  const hash = parsedUrl.hash ?? '';
+  const search = parsedUrl.search ?? '';
+
+  const href = `require('${
+    // 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)}"` : '';
 
-  (node as unknown as Literal).type = 'jsx';
-  (
-    node as unknown as Literal
-  ).value = `<a target="_blank" href={${href}}${title}>${children}</a>`;
-}
-
-// If the link looks like an asset link, we'll link to the asset,
-// and use a require("assetUrl") (using webpack url-loader/file-loader)
-// instead of navigating to such link
-async function convertToAssetLinkIfNeeded(
-  node: Link,
-  {filePath, siteDir, staticDirs}: PluginOptions,
-) {
-  const assetPath = node.url.replace(hashRegex, '');
-
-  const hasSiteAlias = assetPath.startsWith('@site/');
-  const hasAssetLikeExtension =
-    path.extname(assetPath) && !assetPath.match(/#|.md|.mdx|.html/);
-
-  const looksLikeAssetLink = hasSiteAlias || hasAssetLikeExtension;
+  Object.keys(jsxNode).forEach(
+    (key) => delete jsxNode[key as keyof typeof jsxNode],
+  );
 
-  if (!looksLikeAssetLink) {
-    return;
-  }
+  (jsxNode as Literal).type = 'jsx';
+  jsxNode.value = `<a target="_blank" href={${href}}${title}>${children}</a>`;
+}
 
-  function toAssetLinkNode(requireAssetPath: string) {
-    toAssetRequireNode({
-      node,
-      filePath,
-      requireAssetPath,
-    });
+async function ensureAssetFileExist(assetPath: string, sourceFilePath: string) {
+  const assetExists = await fs.pathExists(assetPath);
+  if (!assetExists) {
+    throw new Error(
+      `Asset ${toMessageRelativeFilePath(
+        assetPath,
+      )} used in ${toMessageRelativeFilePath(sourceFilePath)} not found.`,
+    );
   }
+}
 
+async function getAssetAbsolutePath(
+  assetPath: string,
+  {siteDir, filePath, staticDirs}: Context,
+) {
   if (assetPath.startsWith('@site/')) {
-    const fileSystemAssetPath = path.join(
-      siteDir,
-      assetPath.replace('@site/', ''),
-    );
-    await ensureAssetFileExist(fileSystemAssetPath, filePath);
-    toAssetLinkNode(fileSystemAssetPath);
+    const assetFilePath = path.join(siteDir, assetPath.replace('@site/', ''));
+    // The @site alias is the only way to believe that the user wants an asset.
+    // Everything else can just be a link URL
+    await ensureAssetFileExist(assetFilePath, filePath);
+    return assetFilePath;
   } else if (path.isAbsolute(assetPath)) {
-    // eslint-disable-next-line no-restricted-syntax
-    for (const staticDir of staticDirs) {
-      const fileSystemAssetPath = path.join(staticDir, assetPath);
-      if (await fs.pathExists(fileSystemAssetPath)) {
-        toAssetLinkNode(fileSystemAssetPath);
-        return;
-      }
+    const assetFilePath = await findAsyncSequential(
+      staticDirs.map((dir) => path.join(dir, assetPath)),
+      fs.pathExists,
+    );
+    if (assetFilePath) {
+      return assetFilePath;
     }
   } else {
-    const fileSystemAssetPath = path.join(path.dirname(filePath), assetPath);
-    if (await fs.pathExists(fileSystemAssetPath)) {
-      toAssetLinkNode(fileSystemAssetPath);
+    const assetFilePath = path.join(path.dirname(filePath), assetPath);
+    if (await fs.pathExists(assetFilePath)) {
+      return assetFilePath;
     }
   }
+  return null;
 }
 
-async function processLinkNode(node: Link, options: PluginOptions) {
+async function processLinkNode(node: Link, context: Context) {
   if (!node.url) {
     // try to improve error feedback
     // see https://github.com/facebook/docusaurus/issues/3309#issuecomment-690371675
@@ -138,24 +112,35 @@ async function processLinkNode(node: Link, options: PluginOptions) {
     const line = node?.position?.start?.line || '?';
     throw new Error(
       `Markdown link URL is mandatory in "${toMessageRelativeFilePath(
-        options.filePath,
+        context.filePath,
       )}" file (title: ${title}, line: ${line}).`,
     );
   }
 
   const parsedUrl = url.parse(node.url);
-  if (parsedUrl.protocol) {
+  if (parsedUrl.protocol || !parsedUrl.pathname) {
+    // Don't process pathname:// here, it's used by the <Link> component
+    return;
+  }
+  const hasSiteAlias = parsedUrl.pathname.startsWith('@site/');
+  const hasAssetLikeExtension =
+    path.extname(parsedUrl.pathname) &&
+    !parsedUrl.pathname.match(/\.(?:mdx?|html)(?:#|$)/);
+  if (!hasSiteAlias && !hasAssetLikeExtension) {
     return;
   }
 
-  await convertToAssetLinkIfNeeded(node, options);
+  const assetPath = await getAssetAbsolutePath(parsedUrl.pathname, context);
+  if (assetPath) {
+    toAssetRequireNode(node, assetPath, context.filePath);
+  }
 }
 
 const plugin: Plugin<[PluginOptions]> = (options) => {
-  const transformer: Transformer = async (root) => {
+  const transformer: Transformer = async (root, vfile) => {
     const promises: Promise<void>[] = [];
     visit(root, 'link', (node: Link) => {
-      promises.push(processLinkNode(node, options));
+      promises.push(processLinkNode(node, {...options, filePath: vfile.path!}));
     });
     await Promise.all(promises);
   };