mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
docs(website): document npm2yarn plugin + use new Tabs API everywhere (#5590)
* Update docs * Bad grammar * Add code highlight
This commit is contained in:
Joshua Chen
GitHub
parent
b403356dbd
commit
89cb975cc4
6 changed files with 80 additions and 82 deletions
|
|
@ -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
|
||||
<Tabs
|
||||
defaultValue="single"
|
||||
values={[
|
||||
{label: 'Single author', value: 'single'},
|
||||
{label: 'Multiple authors', value: 'multiple'},
|
||||
]}
|
||||
groupId="author-frontmatter">
|
||||
<TabItem value="single">
|
||||
<Tabs groupId="author-frontmatter">
|
||||
<TabItem value="single" label="Single author" default>
|
||||
|
||||
```yml title="my-blog-post.md"
|
||||
---
|
||||
|
|
@ -196,7 +190,7 @@ authors:
|
|||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="multiple">
|
||||
<TabItem value="multiple" label="Multiple 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
|
||||
<Tabs
|
||||
defaultValue="single"
|
||||
values={[
|
||||
{label: 'Single author', value: 'single'},
|
||||
{label: 'Multiple authors', value: 'multiple'},
|
||||
]}
|
||||
groupId="author-frontmatter">
|
||||
<TabItem value="single">
|
||||
<Tabs groupId="author-frontmatter">
|
||||
<TabItem value="single" label="Single author" default>
|
||||
|
||||
```yml title="my-blog-post.md"
|
||||
---
|
||||
|
|
@ -284,7 +272,7 @@ authors: jmarcey
|
|||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="multiple">
|
||||
<TabItem value="multiple" label="Multiple authors">
|
||||
|
||||
```yml title="my-blog-post.md"
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' },
|
||||
{ label: 'PowerShell', value: 'powershell' }
|
||||
]}>
|
||||
<TabItem value="bash">
|
||||
<Tabs>
|
||||
<TabItem value="bash" label="Bash" default>
|
||||
|
||||
```bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows">
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```batch
|
||||
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="powershell">
|
||||
<TabItem value="powershell" label="PowerShell">
|
||||
|
||||
```powershell
|
||||
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<Tabs
|
||||
defaultValue="apple"
|
||||
values={[
|
||||
{label: 'Apple', value: 'apple'},
|
||||
{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>
|
||||
<TabItem value="apple" label="Apple" default>This is an apple 🍎</TabItem>
|
||||
<TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
|
||||
<TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::
|
||||
|
|
@ -119,16 +113,10 @@ import TabItem from '@theme/TabItem';
|
|||
:::tip Use tabs in admonitions
|
||||
|
||||
```mdx-code-block
|
||||
<Tabs
|
||||
defaultValue="apple"
|
||||
values={[
|
||||
{label: 'Apple', value: 'apple'},
|
||||
{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>
|
||||
<TabItem value="apple" label="Apple" default>This is an apple 🍎</TabItem>
|
||||
<TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
|
||||
<TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
||||
<Tabs
|
||||
defaultValue="js"
|
||||
values={[
|
||||
{ label: 'JavaScript', value: 'js', },
|
||||
{ label: 'Python', value: 'py', },
|
||||
{ label: 'Java', value: 'java', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="js">
|
||||
<Tabs>
|
||||
<TabItem value="js" label="JavaScript" default>
|
||||
|
||||
```js
|
||||
function helloWorld() {
|
||||
|
|
@ -391,7 +384,7 @@ function helloWorld() {
|
|||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="py">
|
||||
<TabItem value="py" label="Python">
|
||||
|
||||
```py
|
||||
def hello_world():
|
||||
|
|
@ -399,7 +392,7 @@ def hello_world():
|
|||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="java">
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
class HelloWorld {
|
||||
|
|
@ -416,15 +409,8 @@ class HelloWorld {
|
|||
And you will get the following:
|
||||
|
||||
````mdx-code-block
|
||||
<Tabs
|
||||
defaultValue="js"
|
||||
values={[
|
||||
{ label: 'JavaScript', value: 'js', },
|
||||
{ label: 'Python', value: 'py', },
|
||||
{ label: 'Java', value: 'java', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="js">
|
||||
<Tabs>
|
||||
<TabItem value="js" label="JavaScript" default>
|
||||
|
||||
```js
|
||||
function helloWorld() {
|
||||
|
|
@ -433,7 +419,7 @@ function helloWorld() {
|
|||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="py">
|
||||
<TabItem value="py" label="Python">
|
||||
|
||||
```py
|
||||
def hello_world():
|
||||
|
|
@ -441,7 +427,7 @@ def hello_world():
|
|||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="java">
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
class HelloWorld {
|
||||
|
|
@ -455,6 +441,51 @@ class HelloWorld {
|
|||
</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).
|
||||
|
||||
### 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.
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@ import TabItem from '@theme/TabItem';
|
|||
|
||||
Docusaurus provides `<Tabs>` components that you can use thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
@ -27,8 +28,9 @@ import TabItem from '@theme/TabItem';
|
|||
<TabItem value="banana" label="Banana">
|
||||
This is a banana 🍌
|
||||
</TabItem>
|
||||
</Tabs>;
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
|
|
|||
|
|
@ -363,20 +363,15 @@ import Tabs from '@theme/Tabs';
|
|||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<Tabs
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
{ label: 'Bash', value: 'bash' },
|
||||
{ label: 'Windows', value: 'windows' }
|
||||
]}>
|
||||
<TabItem value="bash">
|
||||
<Tabs>
|
||||
<TabItem value="bash" label="Bash" default>
|
||||
|
||||
```bash
|
||||
GIT_USER=<GITHUB_USERNAME> yarn deploy
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows">
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```batch
|
||||
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue