From 89cb975cc4cdf5bc20b8231720a53642a9a0f1df Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Wed, 22 Sep 2021 18:25:21 +0800 Subject: [PATCH] docs(website): document npm2yarn plugin + use new Tabs API everywhere (#5590) * Update docs * Bad grammar * Add code highlight --- website/docs/blog.mdx | 24 ++---- website/docs/deployment.mdx | 14 +--- .../markdown-features-admonitions.mdx | 30 +++---- .../markdown-features-code-blocks.mdx | 79 +++++++++++++------ .../markdown-features-tabs.mdx | 4 +- website/docs/i18n/i18n-crowdin.mdx | 11 +-- 6 files changed, 80 insertions(+), 82 deletions(-) diff --git a/website/docs/blog.mdx b/website/docs/blog.mdx index a028526023..dad48ac8e2 100644 --- a/website/docs/blog.mdx +++ b/website/docs/blog.mdx @@ -176,14 +176,8 @@ Use the `authors` FrontMatter field to declare blog post authors. Blog post authors can be declared directly inside the FrontMatter: ````mdx-code-block - - + + ```yml title="my-blog-post.md" --- @@ -196,7 +190,7 @@ authors: ``` - + ```yml title="my-blog-post.md" --- @@ -268,14 +262,8 @@ Use the `authorsMapPath` plugin option to configure the path. JSON is also suppo In blog posts FrontMatter, you can reference the authors declared in the global configuration file: ````mdx-code-block - - + + ```yml title="my-blog-post.md" --- @@ -284,7 +272,7 @@ authors: jmarcey ``` - + ```yml title="my-blog-post.md" --- diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 504d657ee5..62aaf57faa 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -143,28 +143,22 @@ GitHub enterprise installations should work in the same manner as github.com; yo Finally, to deploy your site to GitHub Pages, run: ````mdx-code-block - - + + ```bash GIT_USER= yarn deploy ``` - + ```batch cmd /C "set "GIT_USER=" && yarn deploy" ``` - + ```powershell cmd /C 'set "GIT_USER=" && yarn deploy' diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx index ccd7ae68ff..e66c0d84ec 100644 --- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx +++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx @@ -89,23 +89,17 @@ Some **content** with _markdown_ `syntax`. You can use MDX inside admonitions too! -```mdx +```jsx import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::tip Use tabs in admonitions - - This is an apple 🍎 - This is an orange 🍊 - This is a banana 🍌 + + This is an apple 🍎 + This is an orange 🍊 + This is a banana 🍌 ::: @@ -119,16 +113,10 @@ import TabItem from '@theme/TabItem'; :::tip Use tabs in admonitions ```mdx-code-block - - This is an apple 🍎 - This is an orange 🍊 - This is a banana 🍌 + + This is an apple 🍎 + This is an orange 🍊 + This is a banana 🍌 ``` diff --git a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx index 7fedb93fec..69b488496f 100644 --- a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -374,15 +374,8 @@ The following example is how you can have multi-language code tabs in your docs. import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - - + + ```js function helloWorld() { @@ -391,7 +384,7 @@ function helloWorld() { ``` - + ```py def hello_world(): @@ -399,7 +392,7 @@ def hello_world(): ``` - + ```java class HelloWorld { @@ -416,15 +409,8 @@ class HelloWorld { And you will get the following: ````mdx-code-block - - + + ```js function helloWorld() { @@ -433,7 +419,7 @@ function helloWorld() { ``` - + ```py def hello_world(): @@ -441,7 +427,7 @@ def hello_world(): ``` - + ```java class HelloWorld { @@ -455,6 +441,51 @@ class HelloWorld { ```` -You may want to implement your own `` abstraction if you find the above approach too verbose. We might just implement one in future for convenience. - If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the [Syncing tab choices section](markdown-features-tabs.mdx#syncing-tab-choices). + +### Docusaurus npm2yarn remark plugin {#npm2yarn-remark-plugin} + +Displaying CLI commands in both NPM and Yarn is a very common need, for example: + +```bash npm2yarn +npm install @docusaurus/remark-plugin-npm2yarn +``` + +Docusaurus provides such a utility out of the box, freeing you from using the `Tabs` component every time. To enable this feature, first install the `@docusaurus/remark-plugin-npm2yarn` package as above, and then in `docusaurus.config.js`, for the plugins where you need this feature (doc, blog, pages, etc.), register it in the `remarkPlugins` option. (See [Docs configuration](../../api/plugins/plugin-content-docs.md#ex-config) for more details on configuration format) + +```js title="docusaurus.config.js" +module.exports = { + // ... + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + // highlight-start + remarkPlugins: [ + [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}], + ], + // highlight-end + }, + pages: { + // highlight-next-line + remarkPlugins: [require('@docusaurus/remark-plugin-npm2yarn')], + }, + blog: { + // ... + }, + }, + ], + ], +}; +``` + +And then use it by adding the `npm2yarn` key to the code block: + +````md +```bash npm2yarn +npm install @docusaurus/remark-plugin-npm2yarn +``` +```` + +Using the `{sync: true}` option would make all tab choices synced. Because the choice is stored under the same namespace `npm2yarn`, different `npm2yarn` plugin instances would also sync their choices. diff --git a/website/docs/guides/markdown-features/markdown-features-tabs.mdx b/website/docs/guides/markdown-features/markdown-features-tabs.mdx index 4e4e2da682..01ed2cad93 100644 --- a/website/docs/guides/markdown-features/markdown-features-tabs.mdx +++ b/website/docs/guides/markdown-features/markdown-features-tabs.mdx @@ -13,6 +13,7 @@ import TabItem from '@theme/TabItem'; Docusaurus provides `` components that you can use thanks to [MDX](./markdown-features-react.mdx): + ```jsx import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -27,8 +28,9 @@ import TabItem from '@theme/TabItem'; This is a banana 🍌 -; + ``` + ```mdx-code-block diff --git a/website/docs/i18n/i18n-crowdin.mdx b/website/docs/i18n/i18n-crowdin.mdx index 98cccdf274..45a44e2235 100644 --- a/website/docs/i18n/i18n-crowdin.mdx +++ b/website/docs/i18n/i18n-crowdin.mdx @@ -363,20 +363,15 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - - + + ```bash GIT_USER= yarn deploy ``` - + ```batch cmd /C "set "GIT_USER=" && yarn deploy"