feat(mdx-loader): Remark plugin to report unused MDX / Markdown directives

packages/docusaurus-mdx-loader/src/processor.ts

@@ -15,6 +15,7 @@ import details from './remark/details';
 import head from './remark/head';
 import mermaid from './remark/mermaid';
 import transformAdmonitions from './remark/admonitions';
+import unusedDirectivesWarning from './remark/unusedDirectives';
 import codeCompatPlugin from './remark/mdx1Compat/codeCompatPlugin';
 import {getFormat} from './format';
 import type {MDXFrontMatter} from './frontMatter';
@@ -123,6 +124,7 @@ async function createProcessorFactory() {
       gfm,
       options.markdownConfig.mdx1Compat.comments ? comment : null,
       ...(options.remarkPlugins ?? []),
+      unusedDirectivesWarning,
     ].filter((plugin): plugin is MDXPlugin => Boolean(plugin));
 
     // codeCompatPlugin needs to be applied last after user-provided plugins

packages/docusaurus-mdx-loader/src/remark/unusedDirectives/__tests__/__snapshots__/index.test.ts.snap

@@ -0,0 +1,18 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`directives remark plugin default behavior for custom keyword 1`] = `
+"<admonition type="danger"><p>Take care of snowstorms...</p></admonition>
+<div><p>unused directive content</p></div>
+<p>:::NotAContainerDirective with a phrase after</p>
+<p>:::</p>
+<p>Phrase before :::NotAContainerDirective</p>
+<p>:::</p>"
+`;
+
+exports[`directives remark plugin default behavior for custom keyword 2`] = `
+[
+  [
+    "[WARNING] We found a potential error in your documentation unusedDirective "packages/docusaurus-mdx-loader/src/remark/unusedDirectives/__tests__/__fixtures__/containerDirectives.md":7:1",
+  ],
+]
+`;

packages/docusaurus-mdx-loader/src/remark/unusedDirectives/__tests__/index.test.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 remark2rehype from 'remark-rehype';
+import stringify from 'rehype-stringify';
+import vfile from 'to-vfile';
+import plugin from '../index';
+import admonition from '../../admonitions';
+
+const processFixture = async (name: string) => {
+  const {remark} = await import('remark');
+  const {default: directives} = await import('remark-directive');
+
+  const filePath = path.join(__dirname, '__fixtures__', `${name}.md`);
+  const file = await vfile.read(filePath);
+
+  const result = await remark()
+    .use(directives)
+    .use(admonition)
+    .use(plugin)
+    .use(remark2rehype)
+    .use(stringify)
+    .process(file);
+
+  return result.value;
+};
+
+describe('directives remark plugin', () => {
+  it('default behavior for custom keyword', async () => {
+    const consoleMock = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {});
+
+    const result = await processFixture('containerDirectives');
+
+    expect(result).toMatchSnapshot();
+
+    expect(consoleMock.mock.calls).toMatchSnapshot();
+  });
+});

packages/docusaurus-mdx-loader/src/remark/unusedDirectives/index.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 visit from 'unist-util-visit';
+import logger from '@docusaurus/logger';
+import {posixPath} from '@docusaurus/utils';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import type {Transformer, Processor, Parent} from 'unified';
+import type {
+  Directive,
+  // @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
+
+const directiveTypes = ['containerDirective', 'leafDirective', 'textDirective'];
+
+const plugin: Plugin = function plugin(this: Processor): Transformer {
+  return (tree, file) => {
+    const unusedDirectives: Array<{
+      name: string;
+      type: string;
+      position:
+        | {
+            line: number;
+            column: number;
+          }
+        | undefined;
+    }> = [];
+
+    visit<Parent>(tree, directiveTypes, (node: Directive) => {
+      if (!node.data) {
+        unusedDirectives.push({
+          name: node.name,
+          type: node.type,
+          position: node.position
+            ? {
+                line: node.position.start.line,
+                column: node.position.start.column,
+              }
+            : undefined,
+        });
+      }
+    });
+
+    if (unusedDirectives.length > 0) {
+      const warningMessage = unusedDirectives
+        .map((unusedDirective) => {
+          const positionMessage = unusedDirective.position
+            ? logger.interpolate`number=${unusedDirective.position.line}:number=${unusedDirective.position.column}`
+            : '';
+
+          const customPath = posixPath(path.relative(process.cwd(), file.path));
+
+          return logger.interpolate`We found a potential error in your documentation name=${unusedDirective.name} path=${customPath}:${positionMessage}`;
+        })
+        .join('\n');
+      logger.warn(warningMessage);
+    }
+  };
+};
+
+export default plugin;