@docusaurus/mdx-loader 3.0.0-rc.0 → 3.0.0

package/src/remark/toc/index.ts

@@ -8,13 +8,16 @@
 import {parse, type ParserOptions} from '@babel/parser';
 import traverse from '@babel/traverse';
 import stringifyObject from 'stringify-object';
-import visit from 'unist-util-visit';
 import {toValue} from '../utils';
 import type {Identifier} from '@babel/types';
 import type {Node, Parent} from 'unist';
 import type {Heading, Literal} from 'mdast';
 // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
+import type {
+  MdxjsEsm,
+  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+} from 'mdast-util-mdx';
 
 // TODO as of April 2023, no way to import/re-export this ESM type easily :/
 // TODO upgrade to TS 5.3
@@ -88,6 +91,8 @@ const plugin: Plugin = function plugin(
 
   return async (root) => {
     const {toString} = await import('mdast-util-to-string');
+    const {visit} = await import('unist-util-visit');
+
     const headings: TOCItem[] = [];
 
     visit(root, 'heading', (child: Heading) => {
@@ -100,11 +105,12 @@ const plugin: Plugin = function plugin(
 
       headings.push({
         value: toValue(child, toString),
-        id: child.data!.id as string,
+        id: child.data!.id!,
         level: child.depth,
       });
     });
-    const {children} = root as Parent<Literal>;
+
+    const {children} = root as Parent;
     const targetIndex = await getOrCreateExistingTargetIndex(children, name);
 
     if (headings?.length) {
@@ -115,7 +121,7 @@ const plugin: Plugin = function plugin(
 
 export default plugin;
 
-async function createExportNode(name: string, object: any) {
+async function createExportNode(name: string, object: any): Promise<MdxjsEsm> {
   const {valueToEstree} = await import('estree-util-value-to-estree');
 
   return {

package/src/remark/transformImage/index.ts

@@ -16,11 +16,10 @@ import {
   getFileLoaderUtils,
   findAsyncSequential,
 } from '@docusaurus/utils';
-import visit from 'unist-util-visit';
 import escapeHtml from 'escape-html';
 import sizeOf from 'image-size';
 import logger from '@docusaurus/logger';
-import {assetRequireAttributeValue} from '../utils';
+import {assetRequireAttributeValue, transformNode} from '../utils';
 // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
@@ -110,14 +109,12 @@ ${(err as Error).message}`;
     }
   }
 
-  Object.keys(jsxNode).forEach(
-    (key) => delete jsxNode[key as keyof typeof jsxNode],
-  );
-
-  jsxNode.type = 'mdxJsxTextElement';
-  jsxNode.name = 'img';
-  jsxNode.attributes = attributes;
-  jsxNode.children = [];
+  transformNode(jsxNode, {
+    type: 'mdxJsxTextElement',
+    name: 'img',
+    attributes,
+    children: [],
+  });
 }
 
 async function ensureImageFileExist(imagePath: string, sourceFilePath: string) {
@@ -194,6 +191,8 @@ async function processImageNode(target: Target, context: Context) {
 
 export default function plugin(options: PluginOptions): Transformer {
   return async (root, vfile) => {
+    const {visit} = await import('unist-util-visit');
+
     const promises: Promise<void>[] = [];
     visit(root, 'image', (node: Image, index, parent) => {
       promises.push(

package/src/remark/transformLinks/index.ts

@@ -15,9 +15,8 @@ import {
   getFileLoaderUtils,
   findAsyncSequential,
 } from '@docusaurus/utils';
-import visit from 'unist-util-visit';
 import escapeHtml from 'escape-html';
-import {assetRequireAttributeValue} from '../utils';
+import {assetRequireAttributeValue, transformNode} from '../utils';
 // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
@@ -90,14 +89,12 @@ async function toAssetRequireNode(
 
   const {children} = node;
 
-  Object.keys(jsxNode).forEach(
-    (key) => delete jsxNode[key as keyof typeof jsxNode],
-  );
-
-  jsxNode.type = 'mdxJsxTextElement';
-  jsxNode.name = 'a';
-  jsxNode.attributes = attributes;
-  jsxNode.children = children;
+  transformNode(jsxNode, {
+    type: 'mdxJsxTextElement',
+    name: 'a',
+    attributes,
+    children,
+  });
 }
 
 async function ensureAssetFileExist(assetPath: string, sourceFilePath: string) {
@@ -177,6 +174,8 @@ async function processLinkNode(target: Target, context: Context) {
 
 export default function plugin(options: PluginOptions): Transformer {
   return async (root, vfile) => {
+    const {visit} = await import('unist-util-visit');
+
     const promises: Promise<void>[] = [];
     visit(root, 'link', (node: Link, index, parent) => {
       promises.push(

package/src/remark/unusedDirectives/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 path from 'path';
+import process from 'process';
+import logger from '@docusaurus/logger';
+import {posixPath} from '@docusaurus/utils';
+import {transformNode} from '../utils';
+
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import type {Transformer, Processor, Parent} from 'unified';
+import type {
+  Directives,
+  TextDirective,
+  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+} from 'mdast-util-directive';
+
+// TODO as of April 2023, no way to import/re-export this ESM type easily :/
+// This might change soon, likely after TS 5.2
+// See https://github.com/microsoft/TypeScript/issues/49721#issuecomment-1517839391
+// import type {Plugin} from 'unified';
+type Plugin = any; // TODO fix this asap
+
+type DirectiveType = Directives['type'];
+
+const directiveTypes: DirectiveType[] = [
+  'containerDirective',
+  'leafDirective',
+  'textDirective',
+];
+
+const directivePrefixMap: {[key in DirectiveType]: string} = {
+  textDirective: ':',
+  leafDirective: '::',
+  containerDirective: ':::',
+};
+
+function formatDirectiveName(directive: Directives) {
+  const prefix = directivePrefixMap[directive.type];
+  if (!prefix) {
+    throw new Error(
+      `unexpected, no prefix found for directive of type ${directive.type}`,
+    );
+  }
+  // To simplify we don't display the eventual label/props of directives
+  return `${prefix}${directive.name}`;
+}
+
+function formatDirectivePosition(directive: Directives): string | undefined {
+  return directive.position?.start
+    ? logger.interpolate`number=${directive.position.start.line}:number=${directive.position.start.column}`
+    : undefined;
+}
+
+function formatUnusedDirectiveMessage(directive: Directives) {
+  const name = formatDirectiveName(directive);
+  const position = formatDirectivePosition(directive);
+
+  return `- ${name} ${position ? `(${position})` : ''}`;
+}
+
+function formatUnusedDirectivesMessage({
+  directives,
+  filePath,
+}: {
+  directives: Directives[];
+  filePath: string;
+}): string {
+  const supportUrl = 'https://github.com/facebook/docusaurus/pull/9394';
+  const customPath = posixPath(path.relative(process.cwd(), filePath));
+  const warningTitle = logger.interpolate`Docusaurus found ${directives.length} unused Markdown directives in file path=${customPath}`;
+  const customSupportUrl = logger.interpolate`url=${supportUrl}`;
+  const warningMessages = directives
+    .map(formatUnusedDirectiveMessage)
+    .join('\n');
+
+  return `${warningTitle}
+${warningMessages}
+Your content might render in an unexpected way. Visit ${customSupportUrl} to find out why and how to fix it.`;
+}
+
+function logUnusedDirectivesWarning({
+  directives,
+  filePath,
+}: {
+  directives: Directives[];
+  filePath: string;
+}) {
+  if (directives.length > 0) {
+    const message = formatUnusedDirectivesMessage({
+      directives,
+      filePath,
+    });
+    logger.warn(message);
+  }
+}
+
+function isTextDirective(directive: Directives): directive is TextDirective {
+  return directive.type === 'textDirective';
+}
+
+// A simple text directive is one without any label/props
+function isSimpleTextDirective(
+  directive: Directives,
+): directive is TextDirective {
+  if (isTextDirective(directive)) {
+    // Attributes in MDAST = Directive props
+    const hasAttributes =
+      directive.attributes && Object.keys(directive.attributes).length > 0;
+    // Children in MDAST = Directive label
+    const hasChildren = directive.children.length > 0;
+    return !hasAttributes && !hasChildren;
+  }
+  return false;
+}
+
+function transformSimpleTextDirectiveToString(textDirective: Directives) {
+  transformNode(textDirective, {
+    type: 'text',
+    value: `:${textDirective.name}`, // We ignore label/props on purpose here
+  });
+}
+
+function isUnusedDirective(directive: Directives) {
+  // If directive data is set (notably hName/hProperties set by admonitions)
+  // this usually means the directive has been handled by another plugin
+  return !directive.data;
+}
+
+const plugin: Plugin = function plugin(this: Processor): Transformer {
+  return async (tree, file) => {
+    const {visit} = await import('unist-util-visit');
+
+    const unusedDirectives: Directives[] = [];
+
+    visit<Parent, DirectiveType[]>(
+      tree,
+      directiveTypes,
+      (directive: Directives) => {
+        // If directive data is set (hName/hProperties set by admonitions)
+        // this usually means the directive has been handled by another plugin
+        if (isUnusedDirective(directive)) {
+          if (isSimpleTextDirective(directive)) {
+            transformSimpleTextDirectiveToString(directive);
+          } else {
+            unusedDirectives.push(directive);
+          }
+        }
+      },
+    );
+
+    // We only enable these warnings for the client compiler
+    // This avoids emitting duplicate warnings in prod mode
+    // Note: the client compiler is used in both dev/prod modes
+    if (file.data.compilerName === 'client') {
+      logUnusedDirectivesWarning({
+        directives: unusedDirectives,
+        filePath: file.path,
+      });
+    }
+  };
+};
+
+export default plugin;

package/src/remark/utils/index.ts

@@ -6,7 +6,7 @@
  */
 
 import escapeHtml from 'escape-html';
-import type {Parent} from 'unist';
+import type {Parent, Node} from 'unist';
 import type {PhrasingContent, Heading} from 'mdast';
 import type {
   MdxJsxAttribute,
@@ -15,6 +15,27 @@ import type {
   // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 } from 'mdast-util-mdx';
 
+/**
+ * Util to transform one node type to another node type
+ * The input node is mutated in place
+ * @param node the node to mutate
+ * @param newNode what the original node should become become
+ */
+export function transformNode<NewNode extends Node>(
+  node: Node,
+  newNode: NewNode,
+): NewNode {
+  Object.keys(node).forEach((key) => {
+    // @ts-expect-error: unsafe but ok
+    delete node[key];
+  });
+  Object.keys(newNode).forEach((key) => {
+    // @ts-expect-error: unsafe but ok
+    node[key] = newNode[key];
+  });
+  return node as NewNode;
+}
+
 export function stringifyContent(
   node: Parent,
   toString: (param: unknown) => string, // TODO weird but works
@@ -53,7 +74,7 @@ function mdxJsxTextElementToHtml(
 }
 
 export function toValue(
-  node: PhrasingContent | Heading,
+  node: PhrasingContent | Heading | MdxJsxTextElement,
   toString: (param: unknown) => string, // TODO weird but works
 ): string {
   switch (node.type) {

package/src/types.d.mts

@@ -0,0 +1,34 @@
+/**
+ * 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 type {WebpackCompilerName} from '@docusaurus/utils';
+
+declare module 'vfile' {
+  /*
+  This map registers the type of the data key of a VFile (TypeScript type).
+  This type can be augmented to register custom data types.
+  See https://github.com/vfile/vfile#datamap
+   */
+  interface DataMap {
+    frontMatter: {[key: string]: unknown};
+    compilerName: WebpackCompilerName;
+    contentTitle?: string;
+  }
+}
+
+declare module 'unist' {
+  interface Data {
+    hName?: string;
+    hProperties?: Record<string, unknown>;
+  }
+}
+
+declare module 'mdast' {
+  interface HeadingData {
+    id?: string;
+  }
+}