refactor: handle all admonitions via JSX component #7152
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -15,6 +15,9 @@ import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations | |
| import type {Options} from '@docusaurus/theme-classic'; | ||
| import type webpack from 'webpack'; | ||
|
|
||
| import admonitions from './remark/admonitions'; | ||
| import type {MDXOptions} from '@docusaurus/mdx-loader'; | ||
|
|
||
| const requireFromDocusaurusCore = createRequire( | ||
| require.resolve('@docusaurus/core/package.json'), | ||
| ); | ||
|
|
@@ -151,22 +154,38 @@ export default function docusaurusThemeClassic( | |
| return modules; | ||
| }, | ||
|
|
||
| configureWebpack(config) { | ||
| const prismLanguages = additionalLanguages | ||
| .map((lang) => `prism-${lang}`) | ||
| .join('|'); | ||
|
|
||
| // This allows better optimization by only bundling those components | ||
| // that the user actually needs, because the modules are dynamically | ||
| // required and can't be known during compile time. | ||
| config.plugins?.push( | ||
| new ContextReplacementPlugin( | ||
| /prismjs[\\/]components$/, | ||
| new RegExp(`^./(${prismLanguages})$`), | ||
| ), | ||
| ); | ||
|
|
||
| config.module?.rules?.forEach((rule) => { | ||
|
There was a problem hiding this comment. 🤪 not a fan of this Maybe we could just add an mdx-loader "admonitions" option on which we'd just forward the plugin options (if we keep them?) I know it's not ideal to add everything to mdx-loader but it's probably a good-enough temporary solution until we figure out something better There was a problem hiding this comment. As I explained above, the idea was for the theme to provide admonitions functionality, so the remark plugin should add from the theme. That's why I suggested to implement a simplified lifecycle hook to solve only this issue for now. There was a problem hiding this comment. you can make the loader provide an optional "admonitions" feature that the theme would enable it's less flexible but would definitively work without needing any extra lifecycle, giving us time to figure out a good API for that lifecycle. If we can avoid introducing temporary experimental public apis that's better There was a problem hiding this comment.
Do you mean move the admonitions plugin to the mdx-loader or something else? There was a problem hiding this comment. Yes, for now, you can move the admonition plugin to mdx loader and pass an |
||
| if (typeof rule !== 'string' && Array.isArray(rule.use)) { | ||
| rule.use.forEach((useItem) => { | ||
| if ( | ||
| typeof useItem !== 'string' && | ||
| 'loader' in useItem && | ||
| useItem.loader?.includes('docusaurus-mdx-loader') | ||
| ) { | ||
| useItem.options ??= {}; | ||
| (useItem.options as MDXOptions).remarkPlugins ??= []; | ||
| (useItem.options as MDXOptions).remarkPlugins.push(admonitions); | ||
|
There was a problem hiding this comment. We need to support custom admonitions as we previously did. We have users heavily using them. There was a problem hiding this comment. agree 👍 can you show example sites using custom admonitions and the configs used? There was a problem hiding this comment. There was a problem hiding this comment. @Josh-Cena I think we should also study how changes in this PR will look like after MDX 2 and https://github.com/remarkjs/remark-directive I don't think the current API for admonition customization will stay as is, and instead we'll do customizations through swizzle? So maybe we can already do the breaking change today if it's already planned anyway 🤷♂️ |
||
| } | ||
| }); | ||
| } | ||
| }); | ||
|
|
||
| return {mergeStrategy: {'*': 'replace'}, ...config}; | ||
| }, | ||
|
|
||
| configurePostCss(postCssOptions) { | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| // Jest Snapshot v1, https://goo.gl/fbAQLP | ||
|
|
||
| exports[`admonitions remark plugin base 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> | ||
| <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>" | ||
| `; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| /** | ||
| * 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. | ||
| */ | ||
|
|
||
| import path from 'path'; | ||
| import remark from 'remark'; | ||
| import vfile from 'to-vfile'; | ||
| import plugin from '../index'; | ||
| import remark2rehype from 'remark-rehype'; | ||
| import stringify from 'rehype-stringify'; | ||
|
|
||
| const processFixture = async (name) => { | ||
| const filePath = path.join(__dirname, '__fixtures__', `${name}.md`); | ||
| const file = await vfile.read(filePath); | ||
|
|
||
| const result = await remark() | ||
| .use(plugin) | ||
| .use(remark2rehype) | ||
| .use(stringify) | ||
| .process(file); | ||
|
|
||
| return result.toString(); | ||
| }; | ||
|
|
||
| describe('admonitions remark plugin', () => { | ||
| it('base', async () => { | ||
| const result = await processFixture('base'); | ||
| expect(result).toMatchSnapshot(); | ||
| }); | ||
| }); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is removed, but admonitions remains in schema + default value
We want to still allow custom admonitions? Are custom admonitions configured globally or per plugin?
Do we want to do a breaking change and add a custom error message, or try to keep retro-compatibility?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should keep this here for the time being, but when we eventually have a centralized
markdown.remarkPluginsconfig (#5999) I'd like to move it there. Note that I also want to haveadmonitionsas part of the default MDX loader preset, so it can be configured as part of thedocusaurus-remark-preset.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Josh-Cena I agree we should keep the options there, at least for now
The problem is that the provided options do not make sense anymore
https://github.com/lorikrell/gamerchic/blob/ec6e1595a51b7e65538262dd9308fb7517e42f9f/docusaurus.config.js#L359
Now the options should look like:
And custom styling/svg should be applied by swizzling the admonition component.
@lex111 it's worth supporting that to ensure that the above site config have a way to upgrade Docusaurus without losing its custom admonitions
We also need to add option schema changes so that it prints a clear error message when user is trying to use the "old" customizations format