From c533adc4aaa73ef3e8ce58dc302d40ae5cb94c9f Mon Sep 17 00:00:00 2001 From: Endi Date: Sun, 24 Nov 2019 09:32:26 +0700 Subject: [PATCH] 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 | 12 ++-- website/docs/cli.md | 2 +- website/docs/deployment.md | 4 +- website/docs/installation.md | 8 +-- website/docs/markdown-features.mdx | 7 +-- website/docs/migrating-from-v1-to-v2.md | 4 +- website/docs/presets.md | 2 +- website/docs/search.md | 8 +-- website/docs/using-plugins.md | 2 +- website/docs/using-themes.md | 8 ++- website/docusaurus.config.js | 1 + website/src/plugins/remark-npm2yarn.js | 75 +++++++++++++++++++++++++ 12 files changed, 104 insertions(+), 29 deletions(-) create mode 100644 website/src/plugins/remark-npm2yarn.js diff --git a/website/docs/advanced-plugins.md b/website/docs/advanced-plugins.md index 9af8ffb2f4..0674bef389 100644 --- a/website/docs/advanced-plugins.md +++ b/website/docs/advanced-plugins.md @@ -204,8 +204,8 @@ The default [Google Analytics](https://developers.google.com/analytics/devguides **Installation** -```shell -$ npm install --save @docusaurus/plugin-google-analytics +```bash npm2yarn +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 -$ npm install --save @docusaurus/plugin-google-gtag +```bash npm2yarn +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 | diff --git a/website/docs/cli.md b/website/docs/cli.md index 549cbf8a3e..87324205f0 100644 --- a/website/docs/cli.md +++ b/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 [componentName] [siteDir] +docusaurus swizzle [componentName] [siteDir] ``` **params** diff --git a/website/docs/deployment.md b/website/docs/deployment.md index f2234f89de..694791e4e6 100644 --- a/website/docs/deployment.md +++ b/website/docs/deployment.md @@ -5,8 +5,8 @@ title: Deployment To build the static files of your website for production, run: -```bash -npm build +```bash npm2yarn +npm run build ``` Once it finishes, you should see the production build under the `build/` directory. diff --git a/website/docs/installation.md b/website/docs/installation.md index c44674ff65..5022fbf37c 100644 --- a/website/docs/installation.md +++ b/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 -npm build +```bash npm2yarn +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. diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx index 4eda8ebcbe..b8ac1906f4 100644 --- a/website/docs/markdown-features.mdx +++ b/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 -npm i @docusaurus/theme-live-codeblock +```bash npm2yarn +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'; - ` 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. diff --git a/website/docs/presets.md b/website/docs/presets.md index ab7a8dca3b..e7a13dccc9 100644 --- a/website/docs/presets.md +++ b/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 ``` diff --git a/website/docs/search.md b/website/docs/search.md index e01bfb4d23..7051de42dc 100644 --- a/website/docs/search.md +++ b/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 -yarn swizzle @docusaurus/theme-search-algolia SearchBar +```bash npm2yarn +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 -yarn swizzle @docusaurus/theme-classic SearchBar +```bash npm2yarn +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. diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index 995b8ebd5c..b7007424b3 100644 --- a/website/docs/using-plugins.md +++ b/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 ``` diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index f6700a59f4..a6e27bbc57 100644 --- a/website/docs/using-themes.md +++ b/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 [component name] ``` As an example, to swizzle the `