feat(v2): Extract npm2yarn plugin #3469

fanny · 2020-09-21T11:33:03Z

Motivation

I would like to extract our npm2yarn plugin to the mdx loader. Why am I doing this? A couple of months ago, I tried to implement the plugin in CRA they demonstrated interest in use the plugin, and other users like react-navigation are using as well. But doing as a copy-paste version from ours.

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)
yarn test

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

docusaurus-bot · 2020-09-21T11:37:33Z

Deploy preview for docusaurus-2 ready!

Built with commit 0a98a6e

https://deploy-preview-3469--docusaurus-2.netlify.app

lex111

Not sure if we really should include this feature in the core. This is a pretty specific thing. 🤔
Wouldn't it be better if this is published as an npm package outside of Docusaurus core?

fanny · 2020-09-21T20:59:32Z

The feature of tabs is ours. I don't know if it's still valuable outside.

lex111 · 2020-09-21T21:43:37Z

Not exactly, because the tabs are feature of a theme, not the core. For this reason, it is best to place this tabs extension in a separate npm package.

fanny · 2020-09-21T21:48:49Z

Like a docusaurus plugin outside of the core, right?

But why? I'm trying to understand your idea

lex111 · 2020-09-21T21:58:33Z

Like a docusaurus plugin outside of the core, right?

Yep, it is sort of a separation of concerns, plus we only ship what is really need (basic things). 2020-09-22 0:49 GMT+03:00, Fanny <notifications@github.com>:

…

Like a docusaurus plugin outside of the core, right? But why? I'm trying to understand your idea -- You are receiving this because you commented. Reply to this email directly or view it on GitHub: #3469 (comment)

fanny · 2020-09-23T23:53:13Z

Sounds good. I'll wait @slorber return from PTO, to receive a final feedback.

slorber · 2020-09-28T15:03:49Z

As we are based on JS, React, MDX etc, it's probably ok to include features slightly biased to JS usage, as many docusaurus sites document frontend projects, as long as it does not harm or add too much clutter for other documentation usecases. This usecase seems fine to me.

Maintaining a plugin that we use on Docusaurus site outside of Docusaurus repo can be annoying, as it adds friction for maintenance and refactorings, particularly if the owner (Fanny?) becomes inactive for some reason.

@lex111 is right that tabs is a theme feature, so adding this plugin by default in core (I mean mdx loader) seems bad. We are lucky that both classic and bootstrap themes support tabs so CI does not fail, but if community builds a theme without tabs, this plugin would make the site fail. Maybe we should add the ability for a theme to register global remark/rehype plugins? Not sure how this can be done properly.

However this feature is already opt-in due to its specific syntax '''bash npm2yarn, so I guess it's pretty safe to make it global, despite not working with all possible future themes. To fail, user would have to choose a theme that has no tabs support + use the specific npm2yarn code block syntax (unlikely).

What I suggest is that we publish the plugin as @docusaurus/remark-plugin-npm2yarn, document it as an optional plugin that the user would have to add to the remarkPlugins array if he wants npm/yarn tabs support if its theme support it (likely to be true), instead of enabling it by default in mdx loader.

Later, we could look for a way to enable this plugin by default on classic/bootstrap presets/themes, as we know in such case that it is safe to use.

What do you think?

fanny · 2020-10-01T11:21:53Z

What I suggest is that we publish the plugin as @docusaurus/remark-plugin-npm2yarn, document it as an optional plugin that the user would have to add to the remarkPlugins array if he wants npm/yarn tabs support if its theme support it (likely to be true), instead of enabling it by default in mdx loader.

I agree with you, I didn't think in the possibility that the tabs feature couldn't used. That said, this option, seems secure for me.

slorber · 2020-10-12T17:18:02Z

Hi @fanny

Do you want to work on the changes we agreed on, or can I finish and merge your PR?

fanny · 2020-10-12T17:22:43Z

Hey, I can finish. I was waiting for @lex111 comments.

lex111 · 2020-10-12T19:46:06Z

@fanny apologies for the silence on this. Of course @slorber's suggestion is just great, let's do so!

slorber

Almost good, just an important details 🤪 this does not work.

You didn't actually use the plugin you just created, because you still use the local site plugin in the config:

remarkPlugins: [require('./src/plugins/remark-npm2yarn')],

We should remove this local plugin, and change the config to use the new remark plugin:

remarkPlugins: ["@docusaurus/remark-plugin-npm2yarn"],

(maybe require() is still required, don't know)

Without a new lifecycle like getRemarkPlugins or something, we currently don't have a way to make a docusaurus plugin provide a remark plugin that will be used for all other plugins reading markdown files.

I suggest to keep it simple for now (and publish a remark plugin, not a docusaurus plugin), but in the future we'd rather figure out such an API, so that adding "@docusaurus/plugin-npm2yarn" would enable the npm2yarn feature for all plugins (docs, pages, blog...).

slorber · 2020-10-14T12:41:07Z

packages/docusaurus-remark-plugin-npm2yarn/src/index.js

+  return {
+    name: 'docusaurus-remark-plugin-npm2yarn',
+    getClientModules() {
+      return [path.resolve(__dirname, './npm2yarn/index.js')];


I don't think this will work in practice.

We currently don't have any lifecycle method to add a remark plugin to the mdx loader in a generic way.

For now, this package should be a simple remark plugin, not a docusaurus plugin (until we figure this out). We'll use it in the conf by providing it in the remark plugin array.

slorber · 2020-10-14T12:48:00Z

packages/docusaurus-remark-plugin-npm2yarn/package.json

+    "license": "MIT",
+    "dependencies": {
+      "npm-to-yarn": "^1.0.0-2",
+      "@docusaurus/mdx-loader": "2.0.0-alpha.65"


probably not needed

fanny · 2020-10-14T14:54:25Z

Ops, I understood wrong, so in this case, could you finish? I don't know if I will have time

slorber · 2020-10-15T15:24:37Z

sure, will do that :)

slorber · 2020-10-15T17:24:16Z

ready to merge, thanks ;)

hamzahamidi · 2020-10-15T15:38:55Z

packages/docusaurus-mdx-loader/package.json

@@ -17,6 +17,7 @@
    "@docusaurus/utils": "2.0.0-alpha.65",
    "@mdx-js/mdx": "^1.5.8",
    "@mdx-js/react": "^1.5.8",
+    "npm-to-yarn": "^1.0.0-2",


Is this really needed for docusaurus-mdx-loader ?

thanks, not needed :)
do you want to submit a PR?

fanny added 2 commits September 20, 2020 20:05

chore(v2): add dependency

45df6a3

test(v2): Add npm2yarn tests

a8077a8

fanny requested a review from yangshun as a code owner September 21, 2020 11:33

facebook-github-bot added the CLA Signed Signed Facebook CLA label Sep 21, 2020

fanny mentioned this pull request Sep 21, 2020

docs & plugin: Add support npm2yarn facebook/create-react-app#9122

Open

lex111 reviewed Sep 21, 2020

View reviewed changes

slorber added the pr: new feature This PR adds a new API or behavior. label Sep 28, 2020

slorber mentioned this pull request Sep 28, 2020

feat: improve the npm/yarn installation instruction react-navigation/react-navigation.github.io#693

Merged

feat(v2): Move npm2yarn to a new remark plugin

46c6c63

fanny requested a review from slorber as a code owner October 13, 2020 11:57

slorber requested changes Oct 14, 2020

View reviewed changes

slorber reviewed Oct 14, 2020

View reviewed changes

slorber added 2 commits October 15, 2020 17:25

Merge branch 'master' into fanny/extract-npm2yarn-plugin

fe7507f

remark npm2yarn plugin => ready to release

0a98a6e

slorber merged commit 4760e12 into master Oct 15, 2020

hamzahamidi reviewed Oct 15, 2020

View reviewed changes

hamzahamidi mentioned this pull request Oct 15, 2020

chore(v2): Remove unused deps from docusaurus-mdx-loader #3595

Merged

slorber deleted the fanny/extract-npm2yarn-plugin branch August 17, 2021 17:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): Extract npm2yarn plugin #3469

feat(v2): Extract npm2yarn plugin #3469

fanny commented Sep 21, 2020 •

edited

docusaurus-bot commented Sep 21, 2020 •

edited

lex111 left a comment

fanny commented Sep 21, 2020 •

edited

lex111 commented Sep 21, 2020

fanny commented Sep 21, 2020

lex111 commented Sep 21, 2020 via email

fanny commented Sep 23, 2020

slorber commented Sep 28, 2020 •

edited

fanny commented Oct 1, 2020

slorber commented Oct 12, 2020

fanny commented Oct 12, 2020

lex111 commented Oct 12, 2020

slorber left a comment

slorber Oct 14, 2020

slorber Oct 14, 2020

fanny commented Oct 14, 2020

slorber commented Oct 15, 2020

slorber commented Oct 15, 2020

hamzahamidi Oct 15, 2020

slorber Oct 15, 2020

hamzahamidi Oct 15, 2020

feat(v2): Extract npm2yarn plugin #3469

feat(v2): Extract npm2yarn plugin #3469

Conversation

fanny commented Sep 21, 2020 • edited

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

docusaurus-bot commented Sep 21, 2020 • edited

lex111 left a comment

Choose a reason for hiding this comment

fanny commented Sep 21, 2020 • edited

lex111 commented Sep 21, 2020

fanny commented Sep 21, 2020

lex111 commented Sep 21, 2020 via email

fanny commented Sep 23, 2020

slorber commented Sep 28, 2020 • edited

fanny commented Oct 1, 2020

slorber commented Oct 12, 2020

fanny commented Oct 12, 2020

lex111 commented Oct 12, 2020

slorber left a comment

Choose a reason for hiding this comment

slorber Oct 14, 2020

Choose a reason for hiding this comment

slorber Oct 14, 2020

Choose a reason for hiding this comment

fanny commented Oct 14, 2020

slorber commented Oct 15, 2020

slorber commented Oct 15, 2020

hamzahamidi Oct 15, 2020

Choose a reason for hiding this comment

slorber Oct 15, 2020

Choose a reason for hiding this comment

hamzahamidi Oct 15, 2020

Choose a reason for hiding this comment

fanny commented Sep 21, 2020 •

edited

docusaurus-bot commented Sep 21, 2020 •

edited

fanny commented Sep 21, 2020 •

edited

slorber commented Sep 28, 2020 •

edited