mirror of
https://github.com/facebook/docusaurus.git
synced 2025-07-25 04:28:07 +02:00
refactor(theme): split admonitions, make swizzle easier, better retrocompatibility (#7945)
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
This commit is contained in:
parent
f1415525c0
commit
6f63ffe0a3
32 changed files with 914 additions and 236 deletions
|
@ -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[];
|
||||
|
|
|
@ -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> <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>"
|
||||
`;
|
||||
|
|
|
@ -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();
|
||||
});
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue