@docusaurus/mdx-loader 2.0.0-beta.7babfe036 → 2.0.0-beta.8

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

@@ -5,25 +5,35 @@
  * 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');
+} 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 {getFileLoaderUtils} from '@docusaurus/core/lib/webpack/utils';
+import type {Plugin, Transformer} from 'unified';
+import type {Link, Literal} from 'mdast';
 
 const {
   loaders: {inlineMarkdownLinkFileLoader},
 } = getFileLoaderUtils();
+const hashRegex = /#.*$/;
+
+interface PluginOptions {
+  filePath: string;
+  staticDir: 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 +45,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 +68,25 @@ 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,
+  staticDir,
+  filePath,
+}: {node: Link} & 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,
@@ -102,14 +127,16 @@ async function convertToAssetLinkIfNeeded({node, staticDir, filePath}) {
   }
 }
 
-async function processLinkNode({node, _index, _parent, filePath, staticDir}) {
+async function processLinkNode({
+  node,
+  filePath,
+  staticDir,
+}: {node: Link} & 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,
@@ -122,22 +149,18 @@ async function processLinkNode({node, _index, _parent, filePath, staticDir}) {
     return;
   }
 
-  await convertToAssetLinkIfNeeded({
-    node,
-    staticDir,
-    filePath,
-  });
+  await convertToAssetLinkIfNeeded({node, staticDir, filePath});
 }
 
-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/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+
+declare module '@docusaurus/mdx-loader' {
+  type RemarkOrRehypePlugin =
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    [Function, Record<string, unknown>] | Function;
+  export type RemarkAndRehypePluginOptions = {
+    remarkPlugins: RemarkOrRehypePlugin[];
+    rehypePlugins: RemarkOrRehypePlugin[];
+    beforeDefaultRemarkPlugins: RemarkOrRehypePlugin[];
+    beforeDefaultRehypePlugins: RemarkOrRehypePlugin[];
+  };
+}
+
+// TODO Types provided by MDX 2.0 https://github.com/mdx-js/mdx/blob/main/packages/mdx/types/index.d.ts
+declare module '@mdx-js/mdx' {
+  import type {Plugin, Processor} from 'unified';
+
+  namespace mdx {
+    interface Options {
+      filepath?: string;
+      skipExport?: boolean;
+      wrapExport?: string;
+      remarkPlugins?: Plugin[];
+      rehypePlugins?: Plugin[];
+    }
+
+    function sync(content: string, options?: Options): string;
+    function createMdxAstCompiler(options?: Options): Processor;
+    function createCompiler(options?: Options): Processor;
+  }
+  function mdx(content: string, options?: mdx.Options): Promise<string>;
+
+  export default mdx;
+}

package/tsconfig.json

@@ -1,9 +1,10 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "allowJs": true,
-    "noEmit": true,
-    "noImplicitAny": false
+    "incremental": true,
+    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "rootDir": "src",
+    "outDir": "lib"
   },
   "include": ["src/"]
 }

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

package/src/remark/toc/search.js

@@ -1,73 +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.
- */
-
-// @ts-check
-
-const toString = require('mdast-util-to-string');
-const visit = require('unist-util-visit');
-// Destructuring require tslib
-// eslint-disable-next-line prefer-destructuring
-const toValue = require('../utils').toValue;
-
-/** @typedef {import('@docusaurus/types').TOCItem} TOC */
-/** @typedef {import('unist').Node} Node */
-
-/**
- * @typedef {Object} StringValuedNode
- * @property {string} type
- * @property {string} value
- * @property {number} depth
- * @property {Object} data
- * @property {StringValuedNode[]} children
- */
-
-// Visit all headings. We `slug` all headings (to account for
-// duplicates), but only take h2 and h3 headings.
-/**
- * @param {StringValuedNode} node
- * @returns {TOC[]}
- */
-function search(node) {
-  /** @type {TOC[]} */
-  const headings = [];
-  let current = -1;
-  let currentDepth = 0;
-
-  /**
-   * @param {StringValuedNode} child
-   * @param {number} index
-   * @param {Node | undefined} parent
-   * @returns {void}
-   */
-  const onHeading = (child, index, parent) => {
-    const value = toString(child);
-
-    if (parent !== node || !value || child.depth > 3 || child.depth < 2) {
-      return;
-    }
-
-    const entry = {
-      value: toValue(child),
-      id: child.data.id,
-      children: [],
-    };
-
-    if (!headings.length || currentDepth >= child.depth) {
-      headings.push(entry);
-      current += 1;
-      currentDepth = child.depth;
-    } else {
-      headings[current].children.push(entry);
-    }
-  };
-
-  visit(node, 'heading', onHeading);
-
-  return headings;
-}
-
-module.exports = search;

package/src/remark/utils/index.js

@@ -1,39 +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 escapeHtml = require('escape-html');
-const toString = require('mdast-util-to-string');
-
-/**
- * @param {StringValuedNode | undefined} node
- * @returns {string}
- */
-function toValue(node) {
-  if (node && node.type) {
-    switch (node.type) {
-      case 'text':
-        return escapeHtml(node.value);
-      case 'heading':
-        return node.children.map(toValue).join('');
-      case 'inlineCode':
-        return `<code>${escapeHtml(node.value)}</code>`;
-      case 'emphasis':
-        return `<em>${node.children.map(toValue).join('')}</em>`;
-      case 'strong':
-        return `<strong>${node.children.map(toValue).join('')}</strong>`;
-      case 'delete':
-        return `<del>${node.children.map(toValue).join('')}</del>`;
-      default:
-    }
-  }
-
-  return toString(node);
-}
-
-module.exports = {
-  toValue,
-};