@docusaurus/mdx-loader 2.0.0-beta.2 → 2.0.0-beta.20

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

@@ -7,30 +7,30 @@
 
 /* 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) */
 
-const {parseMarkdownHeadingId} = require('@docusaurus/utils');
-const visit = require('unist-util-visit');
-const toString = require('mdast-util-to-string');
-const slugs = require('github-slugger')();
+import {parseMarkdownHeadingId, createSlugger} from '@docusaurus/utils';
+import visit from 'unist-util-visit';
+import mdastToString from 'mdast-util-to-string';
+import type {Transformer} from 'unified';
+import type {Heading, Text} from 'mdast';
 
-function headings() {
-  const transformer = (ast) => {
-    slugs.reset();
-
-    function visitor(headingNode) {
-      const data = headingNode.data || (headingNode.data = {}); // eslint-disable-line
-      const properties = data.hProperties || (data.hProperties = {});
+export default function plugin(): Transformer {
+  return (root) => {
+    const slugs = createSlugger();
+    visit(root, 'heading', (headingNode: Heading) => {
+      const data = headingNode.data || (headingNode.data = {});
+      const properties = (data.hProperties || (data.hProperties = {})) as {
+        id: string;
+      };
       let {id} = properties;
 
       if (id) {
-        id = slugs.slug(id, true);
+        id = slugs.slug(id, {maintainCase: true});
       } else {
         const headingTextNodes = headingNode.children.filter(
           ({type}) => !['html', 'jsx'].includes(type),
         );
-        const heading = toString(
-          headingTextNodes.length > 0
-            ? {children: headingTextNodes}
-            : headingNode,
+        const heading = mdastToString(
+          headingTextNodes.length > 0 ? headingTextNodes : headingNode,
         );
 
         // Support explicit heading IDs
@@ -40,10 +40,12 @@ function headings() {
 
         if (parsedHeading.id) {
           // When there's an id, it is always in the last child node
-          // Sometimes heading is in multiple "parts" (** syntax creates a child node):
+          // Sometimes heading is in multiple "parts" (** syntax creates a child
+          // node):
           // ## part1 *part2* part3 {#id}
-          const lastNode =
-            headingNode.children[headingNode.children.length - 1];
+          const lastNode = headingNode.children[
+            headingNode.children.length - 1
+          ] as Text;
 
           if (headingNode.children.length > 1) {
             const lastNodeText = parseMarkdownHeadingId(lastNode.value).text;
@@ -63,12 +65,6 @@ function headings() {
 
       data.id = id;
       properties.id = id;
-    }
-
-    visit(ast, 'heading', visitor);
+    });
   };
-
-  return transformer;
 }
-
-module.exports = headings;

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 '../..';
+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';
+
+type 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.length) {
+      children[targetIndex]!.value = `export const ${name} = ${stringifyObject(
+        headings,
+      )};`;
+    }
+  };
+}

package/src/remark/transformImage/index.ts

@@ -0,0 +1,167 @@
+/**
+ * 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) {
+    // 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}`;
+    }
+  }
+
+  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) {
+    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(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,152 @@
+/**
+ * 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;
+};
+
+/**
+ * Transforms the link node to a JSX `<a>` element 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(
+    decodeURIComponent(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,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[];
-}