docs(v2): display yarn and npm command on website (#2037)

* docs(v2): display yarn and npm command on website

* more

* fix div cannot be descendant p

website/docs/advanced-plugins.md

@@ -204,8 +204,8 @@ The default [Google Analytics](https://developers.google.com/analytics/devguides
 
 **Installation**
 
-```shell
+```bash npm2yarn
-$ npm install --save @docusaurus/plugin-google-analytics
+npm install --save @docusaurus/plugin-google-analytics
 ```
 
 **Configuration**
@@ -228,8 +228,8 @@ The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/
 
 **Installation**
 
-```shell
+```bash npm2yarn
-$ npm install --save @docusaurus/plugin-google-gtag
+npm install --save @docusaurus/plugin-google-gtag
 ```
 
 **Configuration**
@@ -268,7 +268,7 @@ module.exports = {
 
 Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder)
 
-```sh
+```bash npm2yarn
 npm install --save @docusaurus/plugin-ideal-image
 ```
 
@@ -302,7 +302,7 @@ import thumbnail from './path/to/img.png';
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. |
-| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). You may also declare a default `sizes` array in the loader options in your `webpack.config.js`. |
+| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up).|
 | `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) |
 | `min` | `integer` |  | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. |
 | `max` | `integer` |  | See `min` above |

website/docs/cli.md

@@ -67,7 +67,7 @@ Compiles your site for production.
 Swizzle any Docusaurus Theme components with your own component with `docusaurus swizzle`.
 
 ```shell
-$ docusaurus swizzle <themeName> [componentName] [siteDir]
+docusaurus swizzle <themeName> [componentName] [siteDir]
 ```
 
 **params**

website/docs/deployment.md

@@ -5,8 +5,8 @@ title: Deployment
 
 To build the static files of your website for production, run:
 
-```bash
+```bash npm2yarn
-npm build
+npm run build
 ```
 
 Once it finishes, you should see the production build under the `build/` directory.

website/docs/installation.md

@@ -73,9 +73,9 @@ my-website
 
 To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest changes.
 
-```bash
+```bash npm2yarn
 cd my-website
-npm start
+npm run start
 ```
 
 By default, a browser window will open at http://localhost:3000.
@@ -86,8 +86,8 @@ Congratulations! You have just created your first Docusaurus site! Browse around
 
 Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:
 
-```bash
+```bash npm2yarn
-npm build
+npm run build
 ```
 
 and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Now](https://zeit.co/now) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.md) for more details.

website/docs/markdown-features.mdx

@@ -305,8 +305,8 @@ You can create an interactive coding editor with the `@docusaurus/theme-live-cod
 
 First, add the plugin to your package.
 
-```bash
+```bash npm2yarn
-npm i @docusaurus/theme-live-codeblock
+npm install --save @docusaurus/theme-live-codeblock
 ```
 
 You will also need to add the plugin to your `docusaurus.config.js`.
@@ -420,9 +420,6 @@ The following example is how you can have multi-language code tabs in your docs.
 
 And you will get the following:
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 <Tabs
   defaultValue="js"
   values={[

website/docs/migrating-from-v1-to-v2.md

@@ -392,8 +392,8 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
 
 `website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
 
-```bash
+```bash npm2yarn
-yarn swizzle @docusaurus/theme-classic Footer
+npm run swizzle @docusaurus/theme-classic Footer
 ```
 
 This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, you may then edit this component for customization.

website/docs/presets.md

@@ -9,7 +9,7 @@ Presets are collections of plugins and themes.
 
 A preset is usually a npm package, so you install them like other npm packages using npm.
 
-```bash
+```bash npm2yarn
 npm install --save docusaurus-preset-name
 ```
 

website/docs/search.md

@@ -34,16 +34,16 @@ themeConfig: {
 
 If you prefer to customize Algolia's search bar React component, swizzle the `SearchBar` component in `@docusaurus/theme-search-algolia`:
 
-```bash
+```bash npm2yarn
-yarn swizzle @docusaurus/theme-search-algolia SearchBar
+npm run swizzle @docusaurus/theme-search-algolia SearchBar
 ```
 
 ## Using your own search
 
 To use your own search, swizzle the `SearchBar` component in `@docusaurus/theme-classic`
 
-```bash
+```bash npm2yarn
-yarn swizzle @docusaurus/theme-classic SearchBar
+npm run swizzle @docusaurus/theme-classic SearchBar
 ```
 
 This will create a `src/themes/SearchBar` file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own `SearchBar` component now.

website/docs/using-plugins.md

@@ -12,7 +12,7 @@ In this doc, we talk about how to use plugins with Docusaurus' official plugins.
 
 A plugin is usually a npm package, so you install them like other npm packages using npm.
 
-```bash
+```bash npm2yarn
 npm install --save docusaurus-plugin-name
 ```
 

website/docs/using-themes.md

@@ -75,18 +75,20 @@ The content plugin remains the same and the only thing you need to change is the
 
 ## Swizzling theme components
 
+> ⚠️ We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.
+
 Docusaurus Themes' components are designed to be replaceable. To make it easier for you, we created a command for you to replace theme components called `swizzle`.
 
 To swizzle a component for a theme, run the following command in your doc site:
 
 ```shell
-$ docusaurus swizzle [theme name] [component name]
+docusaurus swizzle <theme name> [component name]
 ```
 
 As an example, to swizzle the `<Footer />` component in `@docusaurus/theme-classic` for your site, run:
 
-```shell
+```bash npm2yarn
-$ npm swizzle @docusaurus/theme-classic Footer
+npm run swizzle @docusaurus/theme-classic Footer
 ```
 
 This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme.

website/docusaurus.config.js

@@ -39,6 +39,7 @@ module.exports = {
             'https://github.com/facebook/docusaurus/edit/master/website/',
           showLastUpdateAuthor: true,
           showLastUpdateTime: true,
+          remarkPlugins: [require('./src/plugins/remark-npm2yarn')],
         },
         blog: {
           path: '../website-1.x/blog',

website/src/plugins/remark-npm2yarn.js

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// This is a very naive implementation of converting npm commands to yarn commands
+// Works well for our use case since we only use either 'npm install', or 'npm run <something>'
+// Its impossible to convert it right since some commands at npm are not available in yarn and vice/versa
+const convertNpmToYarn = npmCode => {
+  // global install: 'npm i' -> 'yarn'
+  return (
+    npmCode
+      .replace(/^npm i$/gm, 'yarn')
+      // install: 'npm install --save foo' -> 'yarn add foo'
+      .replace(/npm install --save/gm, 'yarn add')
+      // run command: 'npm run start' -> 'yarn run start'
+      .replace(/npm run/gm, 'yarn run')
+  );
+};
+
+const transformNode = node => {
+  const npmCode = node.value;
+  const yarnCode = convertNpmToYarn(node.value);
+  node.children = [
+    {
+      type: 'jsx',
+      value:
+        "<Tabs\n  defaultValue=\"npm\"\n  values={[\n    { label: 'npm', value: 'npm', },\n    { label: 'yarn', value: 'yarn', },\n  ]\n}>\n<TabItem value=\"npm\">",
+    },
+    {
+      type: node.type,
+      lang: node.lang,
+      value: npmCode,
+    },
+    {
+      type: 'jsx',
+      value: '</TabItem>\n<TabItem value="yarn">',
+    },
+    {
+      type: node.type,
+      lang: node.lang,
+      value: yarnCode,
+    },
+    {
+      type: 'jsx',
+      value: '</TabItem>\n</Tabs>',
+    },
+  ];
+  node.type = 'element';
+  delete node.lang;
+  delete node.meta;
+  delete node.value;
+};
+
+module.exports = () => {
+  let transformed = false;
+  const transformer = node => {
+    if (node.type === 'code' && node.meta === 'npm2yarn') {
+      transformNode(node);
+      transformed = true;
+    } else if (Array.isArray(node.children)) {
+      node.children.forEach(transformer);
+    }
+    if (node.type === 'root' && transformed) {
+      node.children.unshift({
+        type: 'import',
+        value:
+          "import Tabs from '@theme/Tabs';\nimport TabItem from '@theme/TabItem';",
+      });
+    }
+  };
+  return transformer;
+};