3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-04-30 02:37:59 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(website): document npm2yarn plugin + use new Tabs API everywhere (#5590)

Browse source 
* Update docs

* Bad grammar

* Add code highlight
This commit is contained in:
Joshua Chen 2021-09-22 18:25:21 +08:00 • committed by GitHub
parent b403356dbd
commit 89cb975cc4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 80 additions and 82 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
website/docs/blog.mdx
View file

@ -176,14 +176,8 @@ Use the `authors` FrontMatter field to declare blog post authors.
Blog post authors can be declared directly inside the FrontMatter: Blog post authors can be declared directly inside the FrontMatter:
````mdx-code-block ````mdx-code-block
<Tabs <Tabs groupId="author-frontmatter">
defaultValue="single" <TabItem value="single" label="Single author" default>
values={[
{label: 'Single author', value: 'single'},
{label: 'Multiple authors', value: 'multiple'},
]}
groupId="author-frontmatter">
<TabItem value="single">
```yml title="my-blog-post.md" ```yml title="my-blog-post.md"
--- ---
@ -196,7 +190,7 @@ authors:
``` ```
</TabItem> </TabItem>
<TabItem value="multiple"> <TabItem value="multiple" label="Multiple authors">
```yml title="my-blog-post.md" ```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: In blog posts FrontMatter, you can reference the authors declared in the global configuration file:
````mdx-code-block ````mdx-code-block
<Tabs <Tabs groupId="author-frontmatter">
defaultValue="single" <TabItem value="single" label="Single author" default>
values={[
{label: 'Single author', value: 'single'},
{label: 'Multiple authors', value: 'multiple'},
]}
groupId="author-frontmatter">
<TabItem value="single">
```yml title="my-blog-post.md" ```yml title="my-blog-post.md"
--- ---
@ -284,7 +272,7 @@ authors: jmarcey
``` ```
</TabItem> </TabItem>
<TabItem value="multiple"> <TabItem value="multiple" label="Multiple authors">
```yml title="my-blog-post.md" ```yml title="my-blog-post.md"
--- ---

14
website/docs/deployment.mdx
View file

@ -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: Finally, to deploy your site to GitHub Pages, run:
````mdx-code-block ````mdx-code-block
<Tabs <Tabs>
defaultValue="bash" <TabItem value="bash" label="Bash" default>
values={[
{ label: 'Bash', value: 'bash' },
{ label: 'Windows', value: 'windows' },
{ label: 'PowerShell', value: 'powershell' }
]}>
<TabItem value="bash">
```bash ```bash
GIT_USER=<GITHUB_USERNAME> yarn deploy GIT_USER=<GITHUB_USERNAME> yarn deploy
``` ```
</TabItem> </TabItem>
<TabItem value="windows"> <TabItem value="windows" label="Windows">
```batch ```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy" cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
``` ```
</TabItem> </TabItem>
<TabItem value="powershell"> <TabItem value="powershell" label="PowerShell">
```powershell ```powershell
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy' cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

30
website/docs/guides/markdown-features/markdown-features-admonitions.mdx
View file

@ -89,23 +89,17 @@ Some **content** with _markdown_ `syntax`.
You can use MDX inside admonitions too! You can use MDX inside admonitions too!
```mdx ```jsx
import Tabs from '@theme/Tabs'; import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem'; import TabItem from '@theme/TabItem';
:::tip Use tabs in admonitions :::tip Use tabs in admonitions
<Tabs <Tabs>
defaultValue="apple" <TabItem value="apple" label="Apple" default>This is an apple 🍎</TabItem>
values={[ <TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
{label: 'Apple', value: 'apple'}, <TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs> </Tabs>
::: :::
@ -119,16 +113,10 @@ import TabItem from '@theme/TabItem';
:::tip Use tabs in admonitions :::tip Use tabs in admonitions
```mdx-code-block ```mdx-code-block
<Tabs <Tabs>
defaultValue="apple" <TabItem value="apple" label="Apple" default>This is an apple 🍎</TabItem>
values={[ <TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
{label: 'Apple', value: 'apple'}, <TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple 🍎</TabItem>
<TabItem value="orange">This is an orange 🍊</TabItem>
<TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs> </Tabs>
``` ```

79
website/docs/guides/markdown-features/markdown-features-code-blocks.mdx
View file

@ -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 Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem'; import TabItem from '@theme/TabItem';
<Tabs <Tabs>
defaultValue="js" <TabItem value="js" label="JavaScript" default>
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'Python', value: 'py', },
{ label: 'Java', value: 'java', },
]
}>
<TabItem value="js">
```js ```js
function helloWorld() { function helloWorld() {
@ -391,7 +384,7 @@ function helloWorld() {
``` ```
</TabItem> </TabItem>
<TabItem value="py"> <TabItem value="py" label="Python">
```py ```py
def hello_world(): def hello_world():
@ -399,7 +392,7 @@ def hello_world():
``` ```
</TabItem> </TabItem>
<TabItem value="java"> <TabItem value="java" label="Java">
```java ```java
class HelloWorld { class HelloWorld {
@ -416,15 +409,8 @@ class HelloWorld {
And you will get the following: And you will get the following:
````mdx-code-block ````mdx-code-block
<Tabs <Tabs>
defaultValue="js" <TabItem value="js" label="JavaScript" default>
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'Python', value: 'py', },
{ label: 'Java', value: 'java', },
]
}>
<TabItem value="js">
```js ```js
function helloWorld() { function helloWorld() {
@ -433,7 +419,7 @@ function helloWorld() {
``` ```
</TabItem> </TabItem>
<TabItem value="py"> <TabItem value="py" label="Python">
```py ```py
def hello_world(): def hello_world():
@ -441,7 +427,7 @@ def hello_world():
``` ```
</TabItem> </TabItem>
<TabItem value="java"> <TabItem value="java" label="Java">
```java ```java
class HelloWorld { class HelloWorld {
@ -455,6 +441,51 @@ class HelloWorld {
</Tabs> </Tabs>
```` ````
You may want to implement your own `<MultiLanguageCode />` 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). 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.

4
website/docs/guides/markdown-features/markdown-features-tabs.mdx
View file

@ -13,6 +13,7 @@ import TabItem from '@theme/TabItem';
Docusaurus provides `<Tabs>` components that you can use thanks to [MDX](./markdown-features-react.mdx): Docusaurus provides `<Tabs>` components that you can use thanks to [MDX](./markdown-features-react.mdx):
<!-- prettier-ignore-start -->
```jsx ```jsx
import Tabs from '@theme/Tabs'; import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem'; import TabItem from '@theme/TabItem';
@ -27,8 +28,9 @@ import TabItem from '@theme/TabItem';
<TabItem value="banana" label="Banana"> <TabItem value="banana" label="Banana">
This is a banana 🍌 This is a banana 🍌
</TabItem> </TabItem>
</Tabs>; </Tabs>
``` ```
<!-- prettier-ignore-end -->
```mdx-code-block ```mdx-code-block
<BrowserWindow> <BrowserWindow>

11
website/docs/i18n/i18n-crowdin.mdx
View file

@ -363,20 +363,15 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem'; import TabItem from '@theme/TabItem';
<Tabs <Tabs>
defaultValue="bash" <TabItem value="bash" label="Bash" default>
values={[
{ label: 'Bash', value: 'bash' },
{ label: 'Windows', value: 'windows' }
]}>
<TabItem value="bash">
```bash ```bash
GIT_USER=<GITHUB_USERNAME> yarn deploy GIT_USER=<GITHUB_USERNAME> yarn deploy
``` ```
</TabItem> </TabItem>
<TabItem value="windows"> <TabItem value="windows" label="Windows">
```batch ```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy" cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"