facebook / facebook/docusaurus

Move remarkPlugins to markdown config

Open
#5,999 4 comments 1 reaction 0 assignees View on GitHub
domain: markdown feature
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-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](https://babeljs.io/docs/en/options#caller)):

```js
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](https://github.com/svg/svgo/tree/master#configuration). I.e. you would need to explicitly need to tell Docusaurus where to insert the default plugins:

```js
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:

```js
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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.