Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move remarkPlugins to markdown config #5999

Open
2 tasks done
Josh-Cena opened this issue Nov 24, 2021 · 2 comments
Open
2 tasks done

Move remarkPlugins to markdown config #5999

Josh-Cena opened this issue Nov 24, 2021 · 2 comments
Labels
apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee domain: markdown Related to Markdown parsing or syntax feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.
Milestone

Comments

@Josh-Cena
Copy link
Collaborator

Josh-Cena commented Nov 24, 2021

Have you 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

  • I'd be willing to contribute this feature to Docusaurus myself.
@Josh-Cena Josh-Cena added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: needs triage This issue has not been triaged by maintainers and removed status: needs triage This issue has not been triaged by maintainers labels Nov 24, 2021
@slorber
Copy link
Collaborator

slorber commented Nov 24, 2021

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
Copy link
Collaborator Author

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 #3020 (comment)). Maybe we can use the same idea (i.e. make plugins register global data that's usable on server-side)?

@Josh-Cena Josh-Cena added the status: blocked This issue is blocked by another issue or external dep and can't be pushed further. label Dec 15, 2021
@Josh-Cena Josh-Cena added this to the 2.0.0 milestone Dec 20, 2021
@Josh-Cena Josh-Cena modified the milestones: 2.0.0, 3.0.0 Apr 6, 2022
@Josh-Cena Josh-Cena added the domain: markdown Related to Markdown parsing or syntax label Apr 14, 2022
@slorber slorber added apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee and removed status: blocked This issue is blocked by another issue or external dep and can't be pushed further. labels Sep 25, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee domain: markdown Related to Markdown parsing or syntax feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.
Projects
None yet
Development

No branches or pull requests

2 participants