refactor(v2): async md image transformer + pathname protocol as an escape hatch (#3087)

* async md image transformer + pathname protocol as an escape hatch

* make error messages computer agnostic by using relative paths

* fix error message relative path

.eslintrc.js

@@ -80,6 +80,7 @@ module.exports = {
     'import/order': OFF,
     'import/prefer-default-export': OFF,
     'lines-between-class-members': OFF,
+    'no-lonely-if': WARNING,
     'no-use-before-define': [
       ERROR,
       {functions: false, classes: false, variables: true},

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

@@ -13,7 +13,7 @@ const matter = require('gray-matter');
 const stringifyObject = require('stringify-object');
 const slug = require('./remark/slug');
 const rightToc = require('./remark/rightToc');
-const relativePath = require('./remark/transformImage');
+const transformImage = require('./remark/transformImage');
 
 const DEFAULT_OPTIONS = {
   rehypePlugins: [],
@@ -31,7 +31,7 @@ module.exports = async function (fileString) {
       ...(reqOptions.beforeDefaultRemarkPlugins || []),
       ...DEFAULT_OPTIONS.remarkPlugins,
       [
-        relativePath,
+        transformImage,
         {staticDir: reqOptions.staticDir, filePath: this.resourcePath},
       ],
       ...(reqOptions.remarkPlugins || []),

packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__snapshots__/index.test.js.snap

@@ -1,6 +1,15 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`transform md images to <img /> 1`] = `
+exports[`transformImage plugin fail if image does not exist 1`] = `"Image packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/fixtures/img/doesNotExist.png used in packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/fixtures/fail.md not found."`;
+
+exports[`transformImage plugin fail if image url is absent 1`] = `"Markdown image url is mandatory. filePath=packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/fixtures/noUrl.md"`;
+
+exports[`transformImage plugin pathname protocol 1`] = `
+"![img](/img/unchecked.png)
+"
+`;
+
+exports[`transformImage plugin transform md images to <img /> 1`] = `
 "![img](https://example.com/img.png)
 
 <img  src={require(\\"!url-loader!./img.png\\").default}  />

packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/fixtures/fail.md

@@ -1 +1 @@
-![img](/img/post.png)
+![img](/img/doesNotExist.png)

packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/fixtures/noUrl.md

@@ -0,0 +1 @@
+![img]()

packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/fixtures/pathname.md

@@ -0,0 +1 @@
+![img](pathname:///img/unchecked.png)

packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/index.test.js

@@ -24,10 +24,16 @@ const processFixture = async (name, options) => {
   return result.toString();
 };
 
-test('fail if image donot exists', async () => {
-  expect(
+describe('transformImage plugin', () => {
+  test('fail if image does not exist', async () => {
+    await expect(
       processFixture('fail', {staticDir: join(__dirname, 'fixtures')}),
-  ).rejects.toBeInstanceOf(Error);
+    ).rejects.toThrowErrorMatchingSnapshot();
+  });
+  test('fail if image url is absent', async () => {
+    await expect(
+      processFixture('noUrl', {staticDir: join(__dirname, 'fixtures')}),
+    ).rejects.toThrowErrorMatchingSnapshot();
   });
 
   test('transform md images to <img />', async () => {
@@ -36,3 +42,11 @@ test('transform md images to <img />', async () => {
     });
     expect(result).toMatchSnapshot();
   });
+
+  test('pathname protocol', async () => {
+    const result = await processFixture('pathname', {
+      staticDir: join(__dirname, 'fixtures'),
+    });
+    expect(result).toMatchSnapshot();
+  });
+});

packages/docusaurus-mdx-loader/src/remark/transformImage/index.js

@@ -10,21 +10,55 @@ const path = require('path');
 const url = require('url');
 const fs = require('fs-extra');
 
-const plugin = (options) => {
-  const transformer = (root) => {
-    visit(root, 'image', (node) => {
-      if (!url.parse(node.url).protocol) {
-        if (!path.isAbsolute(node.url)) {
-          if (
-            !fs.existsSync(path.join(path.dirname(options.filePath), node.url))
-          ) {
+// Needed to throw errors with computer-agnostic path messages
+// Absolute paths are too dependant of user FS
+function toRelativePath(filePath) {
+  return path.relative(process.cwd(), filePath);
+}
+
+async function ensureImageFileExist(imagePath, sourceFilePath) {
+  const imageExists = await fs.exists(imagePath);
+  if (!imageExists) {
     throw new Error(
-              `Image ${path.join(
-                path.dirname(options.filePath),
-                node.url,
-              )} used in ${options.filePath} not found.`,
+      `Image ${toRelativePath(imagePath)} used in ${toRelativePath(
+        sourceFilePath,
+      )} not found.`,
     );
   }
+}
+
+async function processImageNode(node, {filePath, staticDir}) {
+  if (!node.url) {
+    throw new Error(
+      `Markdown image url is mandatory. filePath=${toRelativePath(filePath)}`,
+    );
+  }
+
+  const parsedUrl = url.parse(node.url);
+  if (parsedUrl.protocol) {
+    // 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,
+    // it's mostly to make next release less risky (2.0.0-alpha.59)
+    if (parsedUrl.protocol === 'pathname:') {
+      node.url = node.url.replace('pathname://', '');
+    } else {
+      // noop
+    }
+  }
+  // images without protocol
+  else if (path.isAbsolute(node.url)) {
+    // absolute paths are expected to exist in the static folder
+    const expectedImagePath = path.join(staticDir, node.url);
+    await ensureImageFileExist(expectedImagePath, filePath);
+  }
+  // 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);
+
     node.type = 'jsx';
     node.value = `<img ${node.alt ? `alt={"${node.alt}"}` : ''} ${
       node.url
@@ -33,6 +67,7 @@ const plugin = (options) => {
           }").default}`
         : ''
     } ${node.title ? `title={"${node.title}"}` : ''} />`;
+
     if (node.url) {
       delete node.url;
     }
@@ -42,17 +77,17 @@ const plugin = (options) => {
     if (node.title) {
       delete node.title;
     }
-        } else if (!fs.existsSync(path.join(options.staticDir, node.url))) {
-          throw new Error(
-            `Image ${path.join(options.staticDir, node.url)} used in ${
-              options.filePath
-            } not found.`,
-          );
   }
 }
-    });
-  };
 
+const plugin = (options) => {
+  const transformer = async (root) => {
+    const promises = [];
+    visit(root, 'image', (node) => {
+      promises.push(processImageNode(node, options));
+    });
+    await Promise.all(promises);
+  };
   return transformer;
 };
 

website/docs/markdown-features.mdx

@@ -951,7 +951,7 @@ Let's imagine the following file structure:
 /website/docs/assets/docusaurus-asset-example.xyz
 ```
 
-### Image assets:
+### Image assets
 
 You can use images by requiring them and using an image tag through MDX:
 
@@ -976,12 +976,7 @@ import myImageUrl from './assets/docusaurus-asset-example-banner.png';
 
 This results in displaying the image:
 
-<img
-  src={
-    require('!file-loader!./assets/docusaurus-asset-example-banner.png').default
-  }
-  style={{maxWidth: 300}}
-/>
+![](./assets/docusaurus-asset-example-banner.png)
 
 :::note