@docusaurus/mdx-loader 2.0.0-beta.138b4c997 → 2.0.0-beta.14

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

@@ -5,34 +5,42 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const {parse} = require('@babel/parser');
-const traverse = require('@babel/traverse').default;
-const stringifyObject = require('stringify-object');
-const search = require('./search');
+import {parse, ParserOptions} from '@babel/parser';
+import type {Identifier} from '@babel/types';
+import traverse from '@babel/traverse';
+import stringifyObject from 'stringify-object';
+import search from './search';
+import type {Plugin, Transformer} from 'unified';
+import type {Node, Parent} from 'unist';
+import type {Literal} from 'mdast';
 
-const parseOptions = {
+const parseOptions: ParserOptions = {
   plugins: ['jsx'],
   sourceType: 'module',
 };
-const isImport = (child) => child.type === 'import';
-const hasImports = (index) => index > -1;
-const isExport = (child) => child.type === 'export';
 
-const isTarget = (child, name) => {
+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.name === name) {
+      if ((path.node.id as Identifier).name === name) {
         found = true;
       }
     },
   });
-
   return found;
 };
 
-const getOrCreateExistingTargetIndex = (children, name) => {
+const getOrCreateExistingTargetIndex = (children: Node[], name: string) => {
   let importsIndex = -1;
   let targetIndex = -1;
 
@@ -58,12 +66,12 @@ const getOrCreateExistingTargetIndex = (children, name) => {
   return targetIndex;
 };
 
-const plugin = (options = {}) => {
+const plugin: Plugin<[PluginOptions?]> = (options = {}) => {
   const name = options.name || 'toc';
 
-  const transformer = (node) => {
+  const transformer: Transformer = (node) => {
     const headings = search(node);
-    const {children} = node;
+    const {children} = node as Parent<Literal>;
     const targetIndex = getOrCreateExistingTargetIndex(children, name);
 
     if (headings && headings.length) {
@@ -76,4 +84,4 @@ const plugin = (options = {}) => {
   return transformer;
 };
 
-module.exports = plugin;
+export default plugin;

package/src/remark/toc/search.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 toString from 'mdast-util-to-string';
+import visit, {Visitor} from 'unist-util-visit';
+import {toValue} from '../utils';
+import type {TOCItem} from '@docusaurus/types';
+import type {Node} from 'unist';
+import type {Heading} from 'mdast';
+
+// Intermediate interface for TOC algorithm
+interface SearchItem {
+  node: TOCItem;
+  level: number;
+  parentIndex: number;
+}
+
+/**
+ *
+ * Generate a TOC AST from the raw Markdown contents
+ */
+export default function search(node: Node): TOCItem[] {
+  const headings: SearchItem[] = [];
+
+  const visitor: Visitor<Heading> = (child, _index, parent) => {
+    const value = toString(child);
+
+    // depth:1 headings are titles and not included in the TOC
+    if (parent !== node || !value || child.depth < 2) {
+      return;
+    }
+
+    headings.push({
+      node: {
+        value: toValue(child),
+        id: child.data!.id as string,
+        children: [],
+        level: child.depth,
+      },
+      level: child.depth,
+      parentIndex: -1,
+    });
+  };
+
+  visit(node, 'heading', visitor);
+
+  // Keep track of which previous index would be the current heading's direcy 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
+  // indices 0 and 1 will remain unused.
+  const prevIndexForLevel = Array(7).fill(-1);
+
+  headings.forEach((curr, currIndex) => {
+    // take the last seen index for each ancestor level. the highest
+    // index will be the direct ancestor of the current heading.
+    const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
+    curr.parentIndex = Math.max(...ancestorLevelIndexes);
+    // mark that curr.level was last seen at the current index
+    prevIndexForLevel[curr.level] = currIndex;
+  });
+
+  const rootNodeIndexes: number[] = [];
+
+  // For a given parentIndex, add each Node into that parent's `children` array
+  headings.forEach((heading, i) => {
+    if (heading.parentIndex >= 0) {
+      headings[heading.parentIndex].node.children.push(heading.node);
+    } else {
+      rootNodeIndexes.push(i);
+    }
+  });
+
+  const toc = headings
+    .filter((_, k) => rootNodeIndexes.includes(k)) // only return root nodes
+    .map((heading) => heading.node); // only return Node, no metadata
+  return toc;
+}

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

@@ -5,26 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const visit = require('unist-util-visit');
-const path = require('path');
-const url = require('url');
-const fs = require('fs-extra');
-const escapeHtml = require('escape-html');
-const {getFileLoaderUtils} = require('@docusaurus/core/lib/webpack/utils');
-const {
+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 {
   posixPath,
   escapePath,
   toMessageRelativeFilePath,
-} = require('@docusaurus/utils');
+  getFileLoaderUtils,
+} from '@docusaurus/utils';
+import type {Plugin, Transformer} from 'unified';
+import type {Image, Literal} from 'mdast';
 
 const {
   loaders: {inlineMarkdownImageFileLoader},
 } = getFileLoaderUtils();
 
-const createJSX = (node, pathUrl) => {
+interface PluginOptions {
+  filePath: string;
+  staticDirs: string[];
+}
+
+const createJSX = (node: Image, pathUrl: string) => {
   const jsxNode = node;
-  jsxNode.type = 'jsx';
-  jsxNode.value = `<img ${node.alt ? `alt={"${escapeHtml(node.alt)}"} ` : ''}${
+  (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,
@@ -33,7 +42,7 @@ const createJSX = (node, pathUrl) => {
   }${node.title ? ` title="${escapeHtml(node.title)}"` : ''} />`;
 
   if (jsxNode.url) {
-    delete jsxNode.url;
+    delete (jsxNode as Partial<Image>).url;
   }
   if (jsxNode.alt) {
     delete jsxNode.alt;
@@ -43,7 +52,7 @@ const createJSX = (node, pathUrl) => {
   }
 };
 
-async function ensureImageFileExist(imagePath, sourceFilePath) {
+async function ensureImageFileExist(imagePath: string, sourceFilePath: string) {
   const imageExists = await fs.pathExists(imagePath);
   if (!imageExists) {
     throw new Error(
@@ -54,7 +63,26 @@ async function ensureImageFileExist(imagePath, sourceFilePath) {
   }
 }
 
-async function processImageNode(node, {filePath, staticDir}) {
+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;
+    }
+  }
+  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,
+) {
   if (!node.url) {
     throw new Error(
       `Markdown image URL is mandatory in "${toMessageRelativeFilePath(
@@ -71,16 +99,16 @@ async function processImageNode(node, {filePath, staticDir}) {
     // 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);
-    createJSX(node, posixPath(expectedImagePath));
+    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
@@ -92,10 +120,10 @@ async function processImageNode(node, {filePath, staticDir}) {
   }
 }
 
-const plugin = (options) => {
-  const transformer = async (root) => {
-    const promises = [];
-    visit(root, 'image', (node) => {
+const plugin: Plugin<[PluginOptions]> = (options) => {
+  const transformer: Transformer = async (root) => {
+    const promises: Promise<void>[] = [];
+    visit(root, 'image', (node: Image) => {
       promises.push(processImageNode(node, options));
     });
     await Promise.all(promises);
@@ -103,4 +131,4 @@ const plugin = (options) => {
   return transformer;
 };
 
-module.exports = plugin;
+export default plugin;

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

@@ -5,25 +5,36 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const {
+import {
   toMessageRelativeFilePath,
   posixPath,
   escapePath,
-} = require('@docusaurus/utils');
-
-const visit = require('unist-util-visit');
-const path = require('path');
-const url = require('url');
-const fs = require('fs-extra');
-const escapeHtml = require('escape-html');
-const {toValue} = require('../utils');
-const {getFileLoaderUtils} = require('@docusaurus/core/lib/webpack/utils');
+  getFileLoaderUtils,
+} 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 {Plugin, Transformer} from 'unified';
+import type {Link, Literal} from 'mdast';
 
 const {
   loaders: {inlineMarkdownLinkFileLoader},
 } = getFileLoaderUtils();
+const hashRegex = /#.*$/;
+
+interface PluginOptions {
+  filePath: string;
+  staticDirs: string[];
+  siteDir: string;
+}
 
-async function ensureAssetFileExist(fileSystemAssetPath, sourceFilePath) {
+async function ensureAssetFileExist(
+  fileSystemAssetPath: string,
+  sourceFilePath: string,
+) {
   const assetExists = await fs.pathExists(fileSystemAssetPath);
   if (!assetExists) {
     throw new Error(
@@ -35,12 +46,21 @@ async function ensureAssetFileExist(fileSystemAssetPath, sourceFilePath) {
 }
 
 // transform the link node to a jsx link with a require() call
-function toAssetRequireNode({node, filePath, requireAssetPath}) {
-  /* eslint-disable no-param-reassign */
-
+function toAssetRequireNode({
+  node,
+  filePath,
+  requireAssetPath,
+}: {
+  node: Link;
+  filePath: string;
+  requireAssetPath: string;
+}) {
   let relativeRequireAssetPath = posixPath(
     path.relative(path.dirname(filePath), requireAssetPath),
   );
+  const hash = hashRegex.test(node.url)
+    ? node.url.substr(node.url.indexOf('#'))
+    : '';
 
   // nodejs does not like require("assets/file.pdf")
   relativeRequireAssetPath = relativeRequireAssetPath.startsWith('.')
@@ -49,19 +69,24 @@ function toAssetRequireNode({node, filePath, requireAssetPath}) {
 
   const href = `require('${inlineMarkdownLinkFileLoader}${escapePath(
     relativeRequireAssetPath,
-  )}').default`;
-  const children = (node.children || []).map((n) => toValue(n)).join('');
-  const title = node.title ? `title="${escapeHtml(node.title)}"` : '';
-
-  node.type = 'jsx';
-  node.value = `<a target="_blank" href={${href}}${title}>${children}</a>`;
+  )}').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, staticDir, filePath}) {
-  const assetPath = node.url;
+async function convertToAssetLinkIfNeeded(
+  node: Link,
+  {filePath, siteDir, staticDirs}: PluginOptions,
+) {
+  const assetPath = node.url.replace(hashRegex, '');
 
   const hasSiteAlias = assetPath.startsWith('@site/');
   const hasAssetLikeExtension =
@@ -73,7 +98,7 @@ async function convertToAssetLinkIfNeeded({node, staticDir, filePath}) {
     return;
   }
 
-  function toAssetLinkNode(requireAssetPath) {
+  function toAssetLinkNode(requireAssetPath: string) {
     toAssetRequireNode({
       node,
       filePath,
@@ -82,7 +107,6 @@ async function convertToAssetLinkIfNeeded({node, staticDir, filePath}) {
   }
 
   if (assetPath.startsWith('@site/')) {
-    const siteDir = path.join(staticDir, '..');
     const fileSystemAssetPath = path.join(
       siteDir,
       assetPath.replace('@site/', ''),
@@ -90,9 +114,13 @@ async function convertToAssetLinkIfNeeded({node, staticDir, filePath}) {
     await ensureAssetFileExist(fileSystemAssetPath, filePath);
     toAssetLinkNode(fileSystemAssetPath);
   } else if (path.isAbsolute(assetPath)) {
-    const fileSystemAssetPath = path.join(staticDir, assetPath);
-    if (await fs.pathExists(fileSystemAssetPath)) {
-      toAssetLinkNode(fileSystemAssetPath);
+    // 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;
+      }
     }
   } else {
     const fileSystemAssetPath = path.join(path.dirname(filePath), assetPath);
@@ -102,17 +130,15 @@ async function convertToAssetLinkIfNeeded({node, staticDir, filePath}) {
   }
 }
 
-async function processLinkNode({node, _index, _parent, filePath, staticDir}) {
+async function processLinkNode(node: Link, options: PluginOptions) {
   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] && node.children[0].value) || '?';
-    const line =
-      (node.position && node.position.start && node.position.start.line) || '?';
+    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(
-        filePath,
+        options.filePath,
       )}" file (title: ${title}, line: ${line}).`,
     );
   }
@@ -122,22 +148,18 @@ async function processLinkNode({node, _index, _parent, filePath, staticDir}) {
     return;
   }
 
-  await convertToAssetLinkIfNeeded({
-    node,
-    staticDir,
-    filePath,
-  });
+  await convertToAssetLinkIfNeeded(node, options);
 }
 
-const plugin = (options) => {
-  const transformer = async (root) => {
-    const promises = [];
-    visit(root, 'link', (node, index, parent) => {
-      promises.push(processLinkNode({node, index, parent, ...options}));
+const plugin: Plugin<[PluginOptions]> = (options) => {
+  const transformer: Transformer = async (root) => {
+    const promises: Promise<void>[] = [];
+    visit(root, 'link', (node: Link) => {
+      promises.push(processLinkNode(node, options));
     });
     await Promise.all(promises);
   };
   return transformer;
 };
 
-module.exports = plugin;
+export default plugin;

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

@@ -5,24 +5,26 @@
  * 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
 // See https://github.com/facebook/docusaurus/pull/4278
-function plugin() {
-  const transformer = (root) => {
-    visit(root, 'code', (node, _index, parent) => {
+function plugin(this: Processor): Transformer {
+  const transformer: Transformer = (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,
         );
       }
     });
@@ -31,4 +33,4 @@ function plugin() {
   return transformer;
 }
 
-module.exports = plugin;
+export default plugin;

package/src/remark/utils/index.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 {StaticPhrasingContent, Heading} from 'mdast';
+
+export function stringifyContent(node: Parent): string {
+  return ((node.children || []) as StaticPhrasingContent[])
+    .map(toValue)
+    .join('');
+}
+
+export function toValue(node: StaticPhrasingContent | Heading): string {
+  if (node && node.type) {
+    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>`;
+      default:
+    }
+  }
+
+  return toString(node);
+}

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);
-};