@docusaurus/mdx-loader 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/src/remark/toc/index.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 {parse, type ParserOptions} from '@babel/parser';
+import type {Identifier} from '@babel/types';
+import traverse from '@babel/traverse';
+import stringifyObject from 'stringify-object';
+import toString from 'mdast-util-to-string';
+import visit from 'unist-util-visit';
+import {toValue} from '../utils';
+
+import type {TOCItem} from '@docusaurus/types';
+import type {Node, Parent} from 'unist';
+import type {Heading, Literal} from 'mdast';
+import type {Transformer} from 'unified';
+
+const parseOptions: ParserOptions = {
+  plugins: ['jsx'],
+  sourceType: 'module',
+};
+
+const isImport = (child: Node): child is Literal => child.type === 'import';
+const hasImports = (index: number) => index > -1;
+const isExport = (child: Node): child is Literal => child.type === 'export';
+
+interface PluginOptions {
+  name?: string;
+}
+
+const isTarget = (child: Literal, name: string) => {
+  let found = false;
+  const ast = parse(child.value, parseOptions);
+  traverse(ast, {
+    VariableDeclarator: (path) => {
+      if ((path.node.id as Identifier).name === name) {
+        found = true;
+      }
+    },
+  });
+  return found;
+};
+
+const getOrCreateExistingTargetIndex = (children: Node[], name: string) => {
+  let importsIndex = -1;
+  let targetIndex = -1;
+
+  children.forEach((child, index) => {
+    if (isImport(child)) {
+      importsIndex = index;
+    } else if (isExport(child) && isTarget(child, name)) {
+      targetIndex = index;
+    }
+  });
+
+  if (targetIndex === -1) {
+    const target = {
+      default: false,
+      type: 'export',
+      value: `export const ${name} = [];`,
+    };
+
+    targetIndex = hasImports(importsIndex) ? importsIndex + 1 : 0;
+    children.splice(targetIndex, 0, target);
+  }
+
+  return targetIndex;
+};
+
+export default function plugin(options: PluginOptions = {}): Transformer {
+  const name = options.name || 'toc';
+
+  return (root) => {
+    const headings: TOCItem[] = [];
+
+    visit(root, 'heading', (child: Heading, _index, parent) => {
+      const value = toString(child);
+
+      // depth:1 headings are titles and not included in the TOC
+      if (parent !== root || !value || child.depth < 2) {
+        return;
+      }
+
+      headings.push({
+        value: toValue(child),
+        id: child.data!.id as string,
+        level: child.depth,
+      });
+    });
+    const {children} = root as Parent<Literal>;
+    const targetIndex = getOrCreateExistingTargetIndex(children, name);
+
+    if (headings && headings.length) {
+      children[targetIndex].value = `export const ${name} = ${stringifyObject(
+        headings,
+      )};`;
+    }
+  };
+}

package/src/remark/transformImage/index.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 {
+  toMessageRelativeFilePath,
+  posixPath,
+  escapePath,
+  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 {Transformer} from 'unified';
+import type {Image, Literal} from 'mdast';
+import logger from '@docusaurus/logger';
+
+const {
+  loaders: {inlineMarkdownImageFileLoader},
+} = getFileLoaderUtils();
+
+type PluginOptions = {
+  staticDirs: string[];
+  siteDir: string;
+};
+
+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 (err) {
+    logger.error`The image at path=${imagePath} can't be read correctly. Please ensure it's a valid image.
+${(err as Error).message}`;
+  }
+
+  Object.keys(jsxNode).forEach(
+    (key) => delete jsxNode[key as keyof typeof jsxNode],
+  );
+
+  (jsxNode as Literal).type = 'jsx';
+  jsxNode.value = `<img loading="lazy" ${alt}src={${src}}${title}${width}${height} />`;
+}
+
+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), imagePath);
+  await ensureImageFileExist(imageFilePath, filePath);
+  return imageFilePath;
+}
+
+async function processImageNode(node: Image, context: Context) {
+  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(node, imagePath, context.filePath);
+}
+
+export default function plugin(options: PluginOptions): Transformer {
+  return async (root, vfile) => {
+    const promises: Promise<void>[] = [];
+    visit(root, 'image', (node: Image) => {
+      promises.push(
+        processImageNode(node, {...options, filePath: vfile.path!}),
+      );
+    });
+    await Promise.all(promises);
+  };
+}

package/src/remark/transformLinks/index.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 {
+  toMessageRelativeFilePath,
+  posixPath,
+  escapePath,
+  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 {stringifyContent} from '../utils';
+import type {Transformer} from 'unified';
+import type {Link, Literal} from 'mdast';
+
+const {
+  loaders: {inlineMarkdownLinkFileLoader},
+} = getFileLoaderUtils();
+
+type PluginOptions = {
+  staticDirs: string[];
+  siteDir: string;
+};
+
+type Context = PluginOptions & {
+  filePath: string;
+};
+
+// transform the link node to a jsx link with a require() call
+function toAssetRequireNode(node: Link, assetPath: string, filePath: string) {
+  const jsxNode = node as Literal & Partial<Link>;
+  let relativeAssetPath = posixPath(
+    path.relative(path.dirname(filePath), assetPath),
+  );
+  // 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)}"` : '';
+
+  Object.keys(jsxNode).forEach(
+    (key) => delete jsxNode[key as keyof typeof jsxNode],
+  );
+
+  (jsxNode as Literal).type = 'jsx';
+  jsxNode.value = `<a target="_blank" href={${href}}${title}>${children}</a>`;
+}
+
+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(node: Link, context: Context) {
+  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)?.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(parsedUrl.pathname, context);
+  if (assetPath) {
+    toAssetRequireNode(node, assetPath, context.filePath);
+  }
+}
+
+export default function plugin(options: PluginOptions): Transformer {
+  return async (root, vfile) => {
+    const promises: Promise<void>[] = [];
+    visit(root, 'link', (node: Link) => {
+      promises.push(processLinkNode(node, {...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,37 @@
+/**
+ * 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.js

@@ -1,104 +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);
-
-  // By default, will remove the markdown title from the content
-  const {content} = parseMarkdownContentTitle(contentWithTitle, {
-    keepContentTitle: reqOptions.keepContentTitle,
-  });
-
-  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 = `export const frontMatter = ${stringifyObject(frontMatter)};`;
-
-  // 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);
-};