Move remarkPlugins to markdown config

[Josh-Cena]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

Current plugin-level remark/rehype configuration should be replaced with a global configuration.

Has this been requested on Canny?

No

Motivation

After #5972 we will have a siteConfig.markdown field. It's time to populate it with more options.

API design

It will accept a function or an array (inspired by Babel's caller):

module.exports = {
  markdown: {
    // Note: this will disable default plugins, see below
    remarkPlugins: ({plugin}) => plugin.name === 'content-docs' ? [math] : [],
    rehypePlugins: [katex],
  }
}

Moreover, this API would allow us to override default plugins (#5450), inspired by SVGO's approach of using presets. I.e. you would need to explicitly need to tell Docusaurus where to insert the default plugins:

module.exports = {
  markdown: {
    // math is before the default plugins, like using the beforeDefaultRemarkPlugins we had before
    remarkPlugins: [math, 'docusaurus-remark-preset'],
    rehypePlugins: [katex],
  }
}

To disable a particular plugin or pass in options, do it as you expect:

module.exports = {
  markdown: {
    remarkPlugins: [[
      'docusaurus-remark-preset',
      {
        emoji: false,
        transformLinks: {ignore: /\.json/},
      },
    ]],
  }
}

I don't think it's necessary for us to insert extra plugins somewhere between default plugins, so treating them as a chunk is fine.

I also propose that we have more built-in plugins to be enabled, e.g. we can move npm2yarn to the preset. I also want to build another plugin that transforms style="color:red" to style={{color:'red'}} and class="foo" to className="foo" (i.e. make casual users happy)

Have you tried building it?

No

Self-service

• [X] I'd be willing to contribute this feature to Docusaurus myself.

[slorber]

Current plugin-level remark/rehype configuration should be replaced with a global configuration.

Do we really want to remove the existing plugin options? Maybe we can keep both?

Also worth taking into consideration: in the future, a plugin should be able to add global md plugins to your site. For example we should be able to create a docusaurus-plugin-math-equations (https://docusaurus.io/docs/markdown-features/math-equations). Not sure how the lifecycle would look like, when it will be called and how it would interact with the remarkPlugins functional form.

[Josh-Cena]

Do we really want to remove the existing plugin options? Maybe we can keep both?

Sure, it's just me getting tired of keeping two APIs that do the same. We can keep the legacy one work for some time (ideally removing it before the RC release), but they can't interop because there isn't a nice way to merge them.

docusaurus-plugin-math-equations

Umm, maybe we should have a preset instead, since we are already introducing the concept of remark/rehype presets?

I also thought about the "real global Markdown config", i.e. lifecycles, which is the crux of #4625. But after some pondering, I think plugins are one level higher than the MDX infrastructure. It just happens that all the three content plugins all use MDX for content loading—they could well use reStructuredText, LaTeX, or other markup/typesetting languages. We need to have a decent abstraction to not break the modularity of plugins.

With a more unified Markdown infrastructure, however, we will be able to do the file path => URL mapping between plugins (cf https://github.com/facebook/docusaurus/issues/3020#issuecomment-974638441). Maybe we can use the same idea (i.e. make plugins register global data that's usable on server-side)?