refactor(theme): split admonitions, make swizzle easier, better retrocompatibility (#7945)

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

website/docs/guides/markdown-features/markdown-features-admonitions.mdx

@@ -216,13 +216,13 @@ You can customize how each individual admonition type is rendered through [swizz
 ```jsx title="src/theme/Admonition.js"
 import React from 'react';
 import Admonition from '@theme-original/Admonition';
-import MyIcon from '@site/static/img/info.svg';
+import MyCustomNoteIcon from '@site/static/img/info.svg';
 
 export default function AdmonitionWrapper(props) {
   if (props.type !== 'info') {
-    return <Admonition {...props} />;
+    return <Admonition title="My Custom Admonition Title" {...props} />;
   }
-  return <Admonition icon={<MyIcon />} {...props} />;
+  return <Admonition icon={<MyCustomNoteIcon />} {...props} />;
 }
 ```
 
@@ -240,6 +240,7 @@ module.exports = {
           admonitions: {
             tag: ':::',
             keywords: ['note', 'tip', 'info', 'caution', 'danger'],
+            extendDefaults: true,
           },
         },
       },
@@ -248,9 +249,82 @@ module.exports = {
 };
 ```
 
-The plugin accepts two options:
+The plugin accepts the following options:
 
 - `tag`: The tag that encloses the admonition. Defaults to `:::`.
-- `keywords`: An array of keywords that can be used as the type for the admonition. Note that if you override this, the default values will not be applied.
+- `keywords`: An array of keywords that can be used as the type for the admonition.
+- `extendDefaults`: Should the provided options (such as `keywords`) be merged into the existing defaults. Defaults to `false`.
 
-The `keyword` will be passed as the `type` prop of the `Admonition` component. If you register more types than the default, you are also responsible for providing their implementation—including the container's style, icon, default title text, etc. You would usually need to [eject](../../swizzling.md#ejecting) the `@theme/Admonition` component, so you could re-use the same infrastructure as the other types.
+The `keyword` will be passed as the `type` prop of the `Admonition` component.
+
+### Custom admonition type components {#custom-admonition-type-components}
+
+By default, the theme doesn't know what do to with custom admonition keywords such as `:::my-custom-admonition`. It is your responsibility to map each admonition keyword to a React component so that the theme knows how to render them.
+
+If you registered a new admonition type `my-custom-admonition` via the following config:
+
+````js title="docusaurus.config.js"
+module.exports = {
+  // ...
+  presets: [
+    [
+      'classic',
+      {
+        // ...
+        docs: {
+          admonitions: {
+            tag: ':::',
+            keywords: ['my-custom-admonition'],
+            extendDefaults: true,
+          },
+        },
+      },
+    ],
+  ],
+};
+
+You can provide the corresponding React component for `:::my-custom-admonition` by creating the following file (unfortunately, since it's not a React component file, it's not swizzlable):
+
+```js title="src/theme/Admonition/Types.js"
+import React from 'react';
+import DefaultAdmonitionTypes from '@theme-original/Admonition/Types';
+
+function MyCustomAdmonition(props) {
+  return (
+    <div style={{border: 'solid red', padding: 10}}>
+      <h5 style={{color: 'blue', fontSize: 30}}>{props.title}</h5>
+      <div>{props.children}</div>
+    </div>
+  );
+}
+
+const AdmonitionTypes = {
+  ...DefaultAdmonitionTypes,
+
+  // Add all your custom admonition types here...
+  // You can also override the default ones if you want
+  'my-custom-admonition': MyCustomAdmonition,
+};
+
+export default AdmonitionTypes;
+````
+
+Now you can use your new admonition keyword in a Markdown file, and it will be parsed and rendered with your custom logic:
+
+```md
+:::my-custom-admonition Custom Admonition
+
+It works!
+
+:::
+```
+
+<BrowserWindow>
+
+:::my-custom-admonition Custom Admonition
+
+It works!
+
+:::
+
+</BrowserWindow>