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

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
This commit is contained in:
Sébastien Lorber 2022-09-07 17:49:44 +02:00 committed by GitHub
parent f1415525c0
commit 6f63ffe0a3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
32 changed files with 914 additions and 236 deletions

View file

@ -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[];

View file

@ -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>"
`;

View file

@ -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();
});

View file

@ -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