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

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

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

@@ -53,7 +53,7 @@ export type MDXPlugin =
   [Plugin<any[]>, any] | Plugin<any[]>;
 
 export type MDXOptions = {
-  admonitions: boolean | AdmonitionOptions;
+  admonitions: boolean | Partial<AdmonitionOptions>;
   remarkPlugins: MDXPlugin[];
   rehypePlugins: MDXPlugin[];
   beforeDefaultRemarkPlugins: MDXPlugin[];

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

@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`admonitions remark plugin base 1`] = `
+exports[`admonitions remark plugin add custom keyword 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>
@@ -11,11 +11,9 @@ exports[`admonitions remark plugin base 1`] = `
 <p>++++</p>"
 `;
 
-exports[`admonitions remark plugin custom keywords 1`] = `
+exports[`admonitions remark plugin base 1`] = `
 "<p>The blog feature enables you to deploy in no time a full-featured blog.</p>
-<p>:::info Sample Title</p>
-<p>Check the <a href="./api/plugins/plugin-content-blog.md">Blog Plugin API Reference documentation</a> for an exhaustive list of options.</p>
-<p>:::</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>
@@ -38,7 +36,33 @@ exports[`admonitions remark plugin custom tag 1`] = `
 <admonition type="tip"><p>Admonition with different syntax</p></admonition>"
 `;
 
+exports[`admonitions remark plugin default behavior for custom keyword 1`] = `
+"<p>The blog feature enables you to deploy in no time a full-featured blog.</p>
+<p>:::info Sample Title</p>
+<p>Check the <a href="./api/plugins/plugin-content-blog.md">Blog Plugin API Reference documentation</a> for an exhaustive list of options.</p>
+<p>:::</p>
+<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>
+<p>++++tip</p>
+<p>Admonition with different syntax</p>
+<p>++++</p>"
+`;
+
 exports[`admonitions remark plugin interpolation 1`] = `
 "<p>Test admonition with interpolated title/body</p>
 <admonition type="tip"><mdxAdmonitionTitle>My <code>interpolated</code> <strong>title</strong> &#x3C;button style={{color: "red"}} onClick={() => alert("click")}>test</mdxAdmonitionTitle><p><code>body</code> <strong>interpolated</strong> content</p></admonition>"
 `;
+
+exports[`admonitions remark plugin replace custom keyword 1`] = `
+"<p>The blog feature enables you to deploy in no time a full-featured blog.</p>
+<p>:::info Sample Title</p>
+<p>Check the <a href="./api/plugins/plugin-content-blog.md">Blog Plugin API Reference documentation</a> for an exhaustive list of options.</p>
+<p>:::</p>
+<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>
+<p>++++tip</p>
+<p>Admonition with different syntax</p>
+<p>++++</p>"
+`;

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

@@ -36,13 +36,34 @@ describe('admonitions remark plugin', () => {
     expect(result).toMatchSnapshot();
   });
 
-  it('custom keywords', async () => {
-    const result = await processFixture('base', {keywords: ['tip']});
+  it('default behavior for custom keyword', async () => {
+    const result = await processFixture('base', {
+      keywords: ['tip'],
+      // extendDefaults: false, // By default we don't extend
+    });
+    expect(result).toMatchSnapshot();
+  });
+
+  it('add custom keyword', async () => {
+    const result = await processFixture('base', {
+      keywords: ['tip'],
+      extendDefaults: true,
+    });
+    expect(result).toMatchSnapshot();
+  });
+
+  it('replace custom keyword', async () => {
+    const result = await processFixture('base', {
+      keywords: ['tip'],
+      extendDefaults: false,
+    });
     expect(result).toMatchSnapshot();
   });
 
   it('custom tag', async () => {
-    const result = await processFixture('base', {tag: '++++'});
+    const result = await processFixture('base', {
+      tag: '++++',
+    });
     expect(result).toMatchSnapshot();
   });
 

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

@@ -11,9 +11,14 @@ import type {Literal} from 'mdast';
 
 const NEWLINE = '\n';
 
+// TODO not ideal option shape
+// First let upgrade to MDX 2.0
+// Maybe we'll want to provide different tags for different admonition types?
+// Also maybe rename "keywords" to "types"?
 export type AdmonitionOptions = {
   tag: string;
   keywords: string[];
+  extendDefaults: boolean;
 };
 
 export const DefaultAdmonitionOptions: AdmonitionOptions = {
@@ -29,6 +34,7 @@ export const DefaultAdmonitionOptions: AdmonitionOptions = {
     'important',
     'caution',
   ],
+  extendDefaults: false, // TODO make it true by default: breaking change
 };
 
 function escapeRegExp(s: string): string {
@@ -36,9 +42,20 @@ function escapeRegExp(s: string): string {
 }
 
 function normalizeOptions(
-  options: Partial<AdmonitionOptions>,
+  providedOptions: Partial<AdmonitionOptions>,
 ): AdmonitionOptions {
-  return {...DefaultAdmonitionOptions, ...options};
+  const options = {...DefaultAdmonitionOptions, ...providedOptions};
+
+  // By default it makes more sense to append keywords to the default ones
+  // Adding custom keywords is more common than disabling existing ones
+  if (options.extendDefaults) {
+    options.keywords = [
+      ...DefaultAdmonitionOptions.keywords,
+      ...options.keywords,
+    ];
+  }
+
+  return options;
 }
 
 // This string value does not matter much