refactor: handle all admonitions via JSX component

packages/docusaurus-plugin-content-blog/package.json

@@ -29,7 +29,6 @@
     "fs-extra": "^10.0.1",
     "lodash": "^4.17.21",
     "reading-time": "^1.5.0",
-    "remark-admonitions": "^1.2.1",
     "tslib": "^2.3.1",
     "utility-types": "^3.10.0",
     "webpack": "^5.72.0"

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -6,7 +6,6 @@
  */
 
 import path from 'path';
-import admonitions from 'remark-admonitions';
 import {
   normalizeUrl,
   docuHash,
@@ -55,12 +54,6 @@ export default async function pluginContentBlog(
   context: LoadContext,
   options: PluginOptions,
 ): Promise<Plugin<BlogContent>> {
-  if (options.admonitions) {
-    options.remarkPlugins = options.remarkPlugins.concat([
-      [admonitions, options.admonitions],
-    ]);
-  }
-
   const {
     siteDir,
     siteConfig,

packages/docusaurus-plugin-content-docs/package.json

@@ -34,7 +34,6 @@
     "import-fresh": "^3.3.0",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
-    "remark-admonitions": "^1.2.1",
     "tslib": "^2.3.1",
     "utility-types": "^3.10.0",
     "webpack": "^5.72.0"

packages/docusaurus-plugin-content-docs/src/options.ts

@@ -17,7 +17,6 @@ import {GlobExcludeDefault} from '@docusaurus/utils';
 
 import type {OptionValidationContext} from '@docusaurus/types';
 import logger from '@docusaurus/logger';
-import admonitions from 'remark-admonitions';
 import {DefaultSidebarItemsGenerator} from './sidebars/generator';
 import {
   DefaultNumberPrefixParser,
@@ -168,11 +167,5 @@ export function validateOptions({
 
   const normalizedOptions = validate(OptionsSchema, options) as PluginOptions;
 
-  if (normalizedOptions.admonitions) {
-    normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
-      [admonitions, normalizedOptions.admonitions],
-    ]);
-  }
-
   return normalizedOptions;
 }

packages/docusaurus-plugin-content-pages/package.json

@@ -23,7 +23,6 @@
     "@docusaurus/utils": "2.0.0-beta.18",
     "@docusaurus/utils-validation": "2.0.0-beta.18",
     "fs-extra": "^10.0.1",
-    "remark-admonitions": "^1.2.1",
     "tslib": "^2.3.1",
     "webpack": "^5.72.0"
   },

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -22,7 +22,6 @@ import {
   parseMarkdownString,
 } from '@docusaurus/utils';
 import type {LoadContext, Plugin} from '@docusaurus/types';
-import admonitions from 'remark-admonitions';
 import {validatePageFrontMatter} from './frontMatter';
 
 import type {LoadedContent, PagesContentPaths} from './types';
@@ -39,11 +38,6 @@ export default async function pluginContentPages(
   context: LoadContext,
   options: PluginOptions,
 ): Promise<Plugin<LoadedContent | null>> {
-  if (options.admonitions) {
-    options.remarkPlugins = options.remarkPlugins.concat([
-      [admonitions, options.admonitions],
-    ]);
-  }
   const {
     siteConfig,
     siteDir,

packages/docusaurus-theme-classic/package.json

@@ -53,6 +53,8 @@
     "cross-env": "^7.0.3",
     "fs-extra": "^10.0.1",
     "react-test-renderer": "^17.0.2",
+    "rehype-stringify": "^8.0.0",
+    "remark-rehype": "^8.1.0",
     "utility-types": "^3.10.0"
   },
   "peerDependencies": {

packages/docusaurus-theme-classic/src/index.ts

@@ -15,6 +15,8 @@ import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations
 import type {Options} from '@docusaurus/theme-classic';
 import type webpack from 'webpack';
 
+import admonitions from './remark/admonitions';
+
 const requireFromDocusaurusCore = createRequire(
   require.resolve('@docusaurus/core/package.json'),
 );
@@ -151,22 +153,33 @@ export default function docusaurusThemeClassic(
       return modules;
     },
 
-    configureWebpack() {
+    configureWebpack(config: webpack.Configuration) {
       const prismLanguages = additionalLanguages
         .map((lang) => `prism-${lang}`)
         .join('|');
 
-      return {
-        plugins: [
-          // This allows better optimization by only bundling those components
-          // that the user actually needs, because the modules are dynamically
-          // required and can't be known during compile time.
-          new ContextReplacementPlugin(
-            /prismjs[\\/]components$/,
-            new RegExp(`^./(${prismLanguages})$`),
-          ),
-        ],
-      };
+      // This allows better optimization by only bundling those components
+      // that the user actually needs, because the modules are dynamically
+      // required and can't be known during compile time.
+      config.plugins?.push(
+        new ContextReplacementPlugin(
+          /prismjs[\\/]components$/,
+          new RegExp(`^./(${prismLanguages})$`),
+        ),
+      );
+
+      (config.module?.rules as webpack.RuleSetRule[])?.forEach((rule) => {
+        if (Array.isArray(rule.use)) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          rule?.use.forEach((useItem: any) => {
+            if (useItem.loader!.includes('docusaurus-mdx-loader')) {
+              useItem?.options.remarkPlugins.push(admonitions);
+            }
+          });
+        }
+      });
+
+      return {mergeStrategy: {'*': 'replace'}, ...config};
     },
 
     configurePostCss(postCssOptions) {

packages/docusaurus-theme-classic/src/remark/admonitions/__tests__/__snapshots__/index.test.ts.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`admonitions remark plugin base 1`] = `
+"<p>The blog feature enables you to deploy in no time a full-featured blog.</p>
+<admonition title="Sample Title" type="info"><p>Check the <a href="./api/plugins/plugin-content-blog.md">Blog Plugin API Reference documentation</a> for an exhaustive list of options.</p></admonition>
+<h2>Initial setup {#initial-setup}</h2>
+<p>To set up your site's blog, start by creating a <code>blog</code> directory.</p>
+<admonition type="tip"><p>Use the <strong><a href="introduction.md#fast-track">Fast Track</a></strong> to understand Docusaurus in <strong>5 minutes ⏱</strong>!</p><p>Use <strong><a href="https://docusaurus.new">docusaurus.new</a></strong> to test Docusaurus immediately in your browser!</p></admonition>"
+`;

packages/docusaurus-theme-classic/src/remark/admonitions/__tests__/index.test.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 remark from 'remark';
+import vfile from 'to-vfile';
+import plugin from '../index';
+import remark2rehype from 'remark-rehype';
+import stringify from 'rehype-stringify';
+
+const processFixture = async (name) => {
+  const filePath = path.join(__dirname, '__fixtures__', `${name}.md`);
+  const file = await vfile.read(filePath);
+
+  const result = await remark()
+    .use(plugin)
+    .use(remark2rehype)
+    .use(stringify)
+    .process(file);
+
+  return result.toString();
+};
+
+describe('admonitions remark plugin', () => {
+  it('base', async () => {
+    const result = await processFixture('base');
+    expect(result).toMatchSnapshot();
+  });
+});

packages/docusaurus-theme-classic/src/remark/admonitions/index.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+
+/* eslint-disable */
+
+import type {Transformer} from 'unified';
+import visit from 'unist-util-visit';
+
+const NEWLINE = '\n';
+
+const config = {
+  tag: ':::',
+  keywords: [
+    'secondary',
+    'info',
+    'success',
+    'danger',
+    'note',
+    'tip',
+    'warning',
+    'important',
+    'caution',
+  ],
+};
+
+function escapeRegExp(s: string): string {
+  return s.replace(new RegExp(`[-[\\]{}()*+?.\\\\^$|/]`, 'g'), '\\$&');
+}
+
+export default function plugin(this: any): Transformer {
+  const keywords = Object.values(config.keywords).map(escapeRegExp).join('|');
+  const tag = escapeRegExp(config.tag);
+  const regex = new RegExp(`${tag}(${keywords})(?: *(.*))?\n`);
+  const escapeTag = new RegExp(escapeRegExp(`\\${config.tag}`), 'g');
+
+  // the tokenizer is called on blocks to determine if there is an admonition present and create tags for it
+  function blockTokenizer(this: any, eat: any, value: string, silent: boolean) {
+    // stop if no match or match does not start at beginning of line
+    const match = regex.exec(value);
+    if (!match || match.index !== 0) return false;
+    // if silent return the match
+    if (silent) return true;
+
+    const now = eat.now();
+    const [opening, keyword, title] = match;
+    const food = [];
+    const content = [];
+
+    // consume lines until a closing tag
+    let idx = 0;
+    while ((idx = value.indexOf(NEWLINE)) !== -1) {
+      // grab this line and eat it
+      const next = value.indexOf(NEWLINE, idx + 1);
+      const line =
+        next !== -1 ? value.slice(idx + 1, next) : value.slice(idx + 1);
+      food.push(line);
+      value = value.slice(idx + 1);
+      // the closing tag is NOT part of the content
+      if (line.startsWith(config.tag)) break;
+      content.push(line);
+    }
+
+    // consume the processed tag and replace escape sequences
+    const contentString = content.join(NEWLINE).replace(escapeTag, config.tag);
+    const add = eat(opening + food.join(NEWLINE));
+
+    // parse the content in block mode
+    const exit = this.enterBlock();
+    const contentNodes = this.tokenizeBlock(contentString, now);
+    exit();
+
+    const element = {
+      type: 'admonitionHTML',
+      data: {
+        hName: 'admonition',
+        hProperties: {
+          title,
+          type: keyword,
+        },
+      },
+      children: contentNodes,
+    };
+
+    return add(element);
+  }
+
+  // add tokenizer to parser after fenced code blocks
+  const Parser = (this as any).Parser.prototype;
+  Parser.blockTokenizers.admonition = blockTokenizer;
+  Parser.blockMethods.splice(
+    Parser.blockMethods.indexOf('fencedCode') + 1,
+    0,
+    'admonition',
+  );
+  Parser.interruptParagraph.splice(
+    Parser.interruptParagraph.indexOf('fencedCode') + 1,
+    0,
+    ['admonition'],
+  );
+  Parser.interruptList.splice(
+    Parser.interruptList.indexOf('fencedCode') + 1,
+    0,
+    ['admonition'],
+  );
+  Parser.interruptBlockquote.splice(
+    Parser.interruptBlockquote.indexOf('fencedCode') + 1,
+    0,
+    ['admonition'],
+  );
+
+  return function transformer(tree) {
+    // escape everything except admonitionHTML nodes
+    // @ts-ignore FIXME
+    visit(
+      tree,
+      (node: any) => {
+        return node.type !== 'admonitionHTML';
+      },
+      function visitor(node: any) {
+        if (node.value) {
+          node.value = node.value.replace(escapeTag, config.tag);
+        }
+        return node;
+      },
+    );
+  };
+}