refactor: handle all admonitions via JSX component (#7152)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

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

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

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

@@ -63,7 +63,7 @@ describe('normalizeDocsPluginOptions', () => {
       breadcrumbs: true,
       showLastUpdateTime: true,
       showLastUpdateAuthor: true,
-      admonitions: {},
+      admonitions: false,
       includeCurrentVersion: false,
       disableVersioning: true,
       editCurrentVersion: true,
@@ -84,7 +84,6 @@ describe('normalizeDocsPluginOptions', () => {
     expect(testValidate(userOptions)).toEqual({
       ...defaultOptions,
       ...userOptions,
-      remarkPlugins: [...userOptions.remarkPlugins!, expect.any(Array)],
     });
   });
 
@@ -102,7 +101,6 @@ describe('normalizeDocsPluginOptions', () => {
     expect(testValidate(userOptions)).toEqual({
       ...defaultOptions,
       ...userOptions,
-      remarkPlugins: [...userOptions.remarkPlugins!, expect.any(Array)],
     });
   });
 
@@ -116,14 +114,14 @@ describe('normalizeDocsPluginOptions', () => {
     });
   });
 
-  it('rejects admonitions true', () => {
-    const admonitionsTrue: Options = {
-      admonitions: true,
-    };
+  it('rejects admonitions array', () => {
     expect(() =>
-      testValidate(admonitionsTrue),
+      testValidate({
+        // @ts-expect-error: rejected value
+        admonitions: [],
+      }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `""admonitions" contains an invalid value"`,
+      `""admonitions" does not look like a valid admonitions config"`,
     );
   });
 

packages/docusaurus-plugin-content-docs/src/deps.d.ts

@@ -1,13 +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.
- */
-
-declare module 'remark-admonitions' {
-  type Options = {[key: string]: unknown};
-
-  const plugin: (options?: Options) => void;
-  export = plugin;
-}

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

@@ -352,6 +352,7 @@ export default async function pluginContentDocs(
             {
               loader: require.resolve('@docusaurus/mdx-loader'),
               options: {
+                admonitions: options.admonitions,
                 remarkPlugins,
                 rehypePlugins,
                 beforeDefaultRehypePlugins,

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

@@ -14,7 +14,6 @@ import {
   URISchema,
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
-import admonitions from 'remark-admonitions';
 import {DefaultSidebarItemsGenerator} from './sidebars/generator';
 import {
   DefaultNumberPrefixParser,
@@ -42,7 +41,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   beforeDefaultRehypePlugins: [],
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
-  admonitions: {},
+  admonitions: true,
   includeCurrentVersion: true,
   disableVersioning: false,
   lastVersion: undefined,
@@ -123,9 +122,7 @@ const OptionsSchema = Joi.object<PluginOptions>({
   beforeDefaultRehypePlugins: RehypePluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
   ),
-  admonitions: Joi.alternatives()
-    .try(AdmonitionsSchema, Joi.boolean().invalid(true))
-    .default(DEFAULT_OPTIONS.admonitions),
+  admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
   showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime),
   showLastUpdateAuthor: Joi.bool().default(
     DEFAULT_OPTIONS.showLastUpdateAuthor,
@@ -167,11 +164,5 @@ export function validateOptions({
 
   const normalizedOptions = validate(OptionsSchema, options);
 
-  if (normalizedOptions.admonitions) {
-    normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
-      [admonitions, normalizedOptions.admonitions],
-    ]);
-  }
-
   return normalizedOptions;
 }

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

@@ -206,7 +206,6 @@ declare module '@docusaurus/plugin-content-docs' {
       docTagsListComponent: string;
       /** Root component of the generated category index page. */
       docCategoryGeneratedIndexComponent: string;
-      admonitions: {[key: string]: unknown};
       sidebarItemsGenerator: import('./sidebars/types').SidebarItemsGeneratorOption;
       /**
        * URL route for the tags section of your doc version. Will be appended to