@docusaurus/mdx-loader 2.0.0-beta.fbdeefcac → 2.0.0-rc.1

package/src/remark/transformImage/index.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 path from 'path';
+import url from 'url';
+import fs from 'fs-extra';
+import {promisify} from 'util';
+import logger from '@docusaurus/logger';
+import {
+  toMessageRelativeFilePath,
+  posixPath,
+  escapePath,
+  getFileLoaderUtils,
+  findAsyncSequential,
+} from '@docusaurus/utils';
+import visit from 'unist-util-visit';
+import escapeHtml from 'escape-html';
+import sizeOf from 'image-size';
+import type {Transformer} from 'unified';
+import type {Parent} from 'unist';
+import type {Image, Literal} from 'mdast';
+
+const {
+  loaders: {inlineMarkdownImageFileLoader},
+} = getFileLoaderUtils();
+
+export type PluginOptions = {
+  staticDirs: string[];
+  siteDir: string;
+};
+
+type Context = PluginOptions & {
+  filePath: string;
+};
+
+type Target = [node: Image, index: number, parent: Parent];
+
+async function toImageRequireNode(
+  [node, index, parent]: Target,
+  imagePath: string,
+  filePath: string,
+) {
+  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 (err) {
+    // Workaround for https://github.com/yarnpkg/berry/pull/3889#issuecomment-1034469784
+    // TODO remove this check once fixed in Yarn PnP
+    if (!process.versions.pnp) {
+      logger.warn`The image at path=${imagePath} can't be read correctly. Please ensure it's a valid image.
+${(err as Error).message}`;
+    }
+  }
+
+  const jsxNode: Literal = {
+    type: 'jsx',
+    value: `<img ${alt}src={${src}}${title}${width}${height} />`,
+  };
+
+  parent.children.splice(index, 1, jsxNode);
+}
+
+async function ensureImageFileExist(imagePath: string, sourceFilePath: string) {
+  const imageExists = await fs.pathExists(imagePath);
+  if (!imageExists) {
+    throw new Error(
+      `Image ${toMessageRelativeFilePath(
+        imagePath,
+      )} used in ${toMessageRelativeFilePath(sourceFilePath)} not found.`,
+    );
+  }
+}
+
+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;
+  }
+  // Relative paths are resolved against the source file's folder.
+  const imageFilePath = path.join(
+    path.dirname(filePath),
+    decodeURIComponent(imagePath),
+  );
+  await ensureImageFileExist(imageFilePath, filePath);
+  return imageFilePath;
+}
+
+async function processImageNode(target: Target, context: Context) {
+  const [node] = target;
+  if (!node.url) {
+    throw new Error(
+      `Markdown image URL is mandatory in "${toMessageRelativeFilePath(
+        context.filePath,
+      )}" file`,
+    );
+  }
+
+  const parsedUrl = url.parse(node.url);
+  if (parsedUrl.protocol || !parsedUrl.pathname) {
+    // pathname:// is an escape hatch, in case user does not want her images to
+    // be converted to require calls going through webpack loader
+    if (parsedUrl.protocol === 'pathname:') {
+      node.url = node.url.replace('pathname://', '');
+    }
+    return;
+  }
+
+  // We try to convert image urls without protocol to images with require calls
+  // going through webpack ensures that image assets exist at build time
+  const imagePath = await getImageAbsolutePath(parsedUrl.pathname, context);
+  await toImageRequireNode(target, imagePath, context.filePath);
+}
+
+export default function plugin(options: PluginOptions): Transformer {
+  return async (root, vfile) => {
+    const promises: Promise<void>[] = [];
+    visit(root, 'image', (node: Image, index, parent) => {
+      promises.push(
+        processImageNode([node, index, parent!], {
+          ...options,
+          filePath: vfile.path!,
+        }),
+      );
+    });
+    await Promise.all(promises);
+  };
+}

package/src/remark/transformLinks/index.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 path from 'path';
+import url from 'url';
+import fs from 'fs-extra';
+import {
+  toMessageRelativeFilePath,
+  posixPath,
+  escapePath,
+  getFileLoaderUtils,
+  findAsyncSequential,
+} from '@docusaurus/utils';
+import visit from 'unist-util-visit';
+import escapeHtml from 'escape-html';
+import {stringifyContent} from '../utils';
+import type {Transformer} from 'unified';
+import type {Parent} from 'unist';
+import type {Link, Literal} from 'mdast';
+
+const {
+  loaders: {inlineMarkdownLinkFileLoader},
+} = getFileLoaderUtils();
+
+export type PluginOptions = {
+  staticDirs: string[];
+  siteDir: string;
+};
+
+type Context = PluginOptions & {
+  filePath: string;
+};
+
+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,
+  assetPath: string,
+  filePath: string,
+) {
+  // require("assets/file.pdf") means requiring from a package called assets
+  const relativeAssetPath = `./${posixPath(
+    path.relative(path.dirname(filePath), assetPath),
+  )}`;
+
+  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)}"` : '';
+
+  const jsxNode: Literal = {
+    type: 'jsx',
+    value: `<a target="_blank" href={${href}}${title}>${children}</a>`,
+  };
+
+  parent.children.splice(index, 1, jsxNode);
+}
+
+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 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)) {
+    const assetFilePath = await findAsyncSequential(
+      staticDirs.map((dir) => path.join(dir, assetPath)),
+      fs.pathExists,
+    );
+    if (assetFilePath) {
+      return assetFilePath;
+    }
+  } else {
+    const assetFilePath = path.join(path.dirname(filePath), assetPath);
+    if (await fs.pathExists(assetFilePath)) {
+      return assetFilePath;
+    }
+  }
+  return null;
+}
+
+async function processLinkNode(target: Target, context: Context) {
+  const [node] = target;
+  if (!node.url) {
+    // Try to improve error feedback
+    // see https://github.com/facebook/docusaurus/issues/3309#issuecomment-690371675
+    const title =
+      node.title ?? (node.children[0] as Literal | undefined)?.value ?? '?';
+    const line = node.position?.start.line ?? '?';
+    throw new Error(
+      `Markdown link URL is mandatory in "${toMessageRelativeFilePath(
+        context.filePath,
+      )}" file (title: ${title}, line: ${line}).`,
+    );
+  }
+
+  const parsedUrl = url.parse(node.url);
+  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;
+  }
+
+  const assetPath = await getAssetAbsolutePath(
+    decodeURIComponent(parsedUrl.pathname),
+    context,
+  );
+  if (assetPath) {
+    toAssetRequireNode(target, assetPath, context.filePath);
+  }
+}
+
+export default function plugin(options: PluginOptions): Transformer {
+  return async (root, vfile) => {
+    const promises: Promise<void>[] = [];
+    visit(root, 'link', (node: Link, index, parent) => {
+      promises.push(
+        processLinkNode([node, index, parent!], {
+          ...options,
+          filePath: vfile.path!,
+        }),
+      );
+    });
+    await Promise.all(promises);
+  };
+}

package/src/remark/unwrapMdxCodeBlocks/{index.js → index.ts}

@@ -5,30 +5,29 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const visit = require('unist-util-visit');
+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
+// 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() {
-  const transformer = (root) => {
-    visit(root, 'code', (node, _index, parent) => {
+export default function plugin(this: Processor): Transformer {
+  return (root) => {
+    visit(root, 'code', (node: Code, index, parent) => {
       if (node.lang === 'mdx-code-block') {
-        const newChildrens = this.parse(node.value).children;
+        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),
+        parent!.children.splice(
+          parent!.children.indexOf(node),
           1,
-          ...newChildrens,
+          ...newChildren,
         );
       }
     });
   };
-
-  return transformer;
 }
-
-module.exports = plugin;

package/src/remark/utils/index.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 escapeHtml from 'escape-html';
+import toString from 'mdast-util-to-string';
+import type {Parent} from 'unist';
+import type {PhrasingContent, Heading} from 'mdast';
+
+export function stringifyContent(node: Parent): string {
+  return (node.children as PhrasingContent[]).map(toValue).join('');
+}
+
+export function toValue(node: PhrasingContent | Heading): string {
+  switch (node.type) {
+    case 'text':
+      return escapeHtml(node.value);
+    case 'heading':
+      return stringifyContent(node);
+    case 'inlineCode':
+      return `<code>${escapeHtml(node.value)}</code>`;
+    case 'emphasis':
+      return `<em>${stringifyContent(node)}</em>`;
+    case 'strong':
+      return `<strong>${stringifyContent(node)}</strong>`;
+    case 'delete':
+      return `<del>${stringifyContent(node)}</del>`;
+    case 'link':
+      return stringifyContent(node);
+    default:
+      return toString(node);
+  }
+}

package/src/index.d.ts

@@ -1,19 +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.
- */
-
-type RemarkOrRehypePlugin =
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  [Function, Record<string, unknown>] | Function;
-
-declare function docusaurusMdxLoader(fileString: string): string;
-
-export interface RemarkAndRehypePluginOptions {
-  remarkPlugins: RemarkOrRehypePlugin[];
-  rehypePlugins: string[];
-  beforeDefaultRemarkPlugins: RemarkOrRehypePlugin[];
-  beforeDefaultRehypePlugins: RemarkOrRehypePlugin[];
-}

package/src/index.js

@@ -1,107 +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.
- */
-
-const {readFile} = require('fs-extra');
-const mdx = require('@mdx-js/mdx');
-const emoji = require('remark-emoji');
-const {
-  parseFrontMatter,
-  parseMarkdownContentTitle,
-} = require('@docusaurus/utils');
-const stringifyObject = require('stringify-object');
-const headings = require('./remark/headings');
-const toc = require('./remark/toc');
-const unwrapMdxCodeBlocks = require('./remark/unwrapMdxCodeBlocks');
-const transformImage = require('./remark/transformImage');
-const transformLinks = require('./remark/transformLinks');
-
-const DEFAULT_OPTIONS = {
-  rehypePlugins: [],
-  remarkPlugins: [unwrapMdxCodeBlocks, emoji, headings, toc],
-};
-
-module.exports = async function docusaurusMdxLoader(fileString) {
-  const callback = this.async();
-
-  const reqOptions = this.getOptions() || {};
-
-  const {frontMatter, content: contentWithTitle} = parseFrontMatter(fileString);
-
-  const {content, contentTitle} = parseMarkdownContentTitle(contentWithTitle, {
-    removeContentTitle: reqOptions.removeContentTitle,
-  });
-
-  const hasFrontMatter = Object.keys(frontMatter).length > 0;
-
-  const options = {
-    ...reqOptions,
-    remarkPlugins: [
-      ...(reqOptions.beforeDefaultRemarkPlugins || []),
-      ...DEFAULT_OPTIONS.remarkPlugins,
-      [
-        transformImage,
-        {staticDir: reqOptions.staticDir, filePath: this.resourcePath},
-      ],
-      [
-        transformLinks,
-        {staticDir: reqOptions.staticDir, filePath: this.resourcePath},
-      ],
-      ...(reqOptions.remarkPlugins || []),
-    ],
-    rehypePlugins: [
-      ...(reqOptions.beforeDefaultRehypePlugins || []),
-      ...DEFAULT_OPTIONS.rehypePlugins,
-
-      ...(reqOptions.rehypePlugins || []),
-    ],
-    filepath: this.resourcePath,
-  };
-  let result;
-
-  try {
-    result = await mdx(content, options);
-  } catch (err) {
-    return callback(err);
-  }
-
-  let exportStr = ``;
-  exportStr += `\nexport const frontMatter = ${stringifyObject(frontMatter)};`;
-  exportStr += `\nexport const contentTitle = ${stringifyObject(
-    contentTitle,
-  )};`;
-
-  // Read metadata for this MDX and export it.
-  if (options.metadataPath && typeof options.metadataPath === 'function') {
-    const metadataPath = options.metadataPath(this.resourcePath);
-
-    if (metadataPath) {
-      // Add as dependency of this loader result so that we can
-      // recompile if metadata is changed.
-      this.addDependency(metadataPath);
-      const metadata = await readFile(metadataPath, 'utf8');
-      exportStr += `\nexport const metadata = ${metadata};`;
-    }
-  }
-
-  if (
-    options.forbidFrontMatter &&
-    typeof options.forbidFrontMatter === 'function'
-  ) {
-    if (options.forbidFrontMatter(this.resourcePath) && hasFrontMatter) {
-      return callback(new Error(`Front matter is forbidden in this file`));
-    }
-  }
-  const code = `
-  import React from 'react';
-  import { mdx } from '@mdx-js/react';
-
-  ${exportStr}
-  ${result}
-  `;
-
-  return callback(null, code);
-};