mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 18:27:56 +02:00
docs(v2): reorganize markdown features page (#2503)
* docs(v2): reorganize markdown features page * docs(v2): reorganize markdown features page
This commit is contained in:
Yangshun Tay
GitHub
parent
8018a835e5
commit
eeebc31ff1
4 changed files with 433 additions and 337 deletions
|
|
@ -109,7 +109,7 @@ function DocItem(props) {
|
|||
<article>
|
||||
{version && (
|
||||
<div>
|
||||
<span className="badge badge--info">
|
||||
<span className="badge badge--secondary">
|
||||
Version: {version}
|
||||
</span>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -4,12 +4,6 @@ title: Markdown Features
|
|||
description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown.
|
||||
---
|
||||
|
||||
<!--
|
||||
combining:
|
||||
- assets
|
||||
- markdown features
|
||||
-->
|
||||
|
||||
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
|
||||
|
||||
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
|
||||
|
|
@ -17,7 +11,7 @@ Docusaurus 2 uses modern tooling to help you compose your interactive documentat
|
|||
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.
|
||||
|
||||
:::important
|
||||
All the following content assumes you are using `@docusaurus/preset-classic`.
|
||||
All the following content assumes you are using `@docusaurus/preset-classic` or `@docusaurus/plugin-content-docs`.
|
||||
:::
|
||||
|
||||
---
|
||||
|
|
@ -72,6 +66,7 @@ This will render in the browser as follows:
|
|||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
|
||||
<BrowserWindow url="http://localhost:3000">
|
||||
|
||||
<h2>Hello from Docusaurus</h2>
|
||||
|
||||
Are you ready to create the documentation site for your open source project?
|
||||
|
|
@ -94,7 +89,7 @@ The headers are well-spaced so that the hierarchy is clear.
|
|||
|
||||
</BrowserWindow>
|
||||
|
||||
### Markdown Headers
|
||||
## Markdown Headers
|
||||
|
||||
Documents use the following markdown header fields that are enclosed by a line `---` on either side:
|
||||
|
||||
|
|
@ -126,7 +121,21 @@ image: https://i.imgur.com/mErPwqL.png
|
|||
---
|
||||
```
|
||||
|
||||
### Embedding React components
|
||||
|
||||
## Referencing other documents
|
||||
|
||||
If you want to reference another document file, you should use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
|
||||
|
||||
For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
|
||||
|
||||
```md
|
||||
I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md)
|
||||
[Relative document](../doc2.md) referencing works as well.
|
||||
```
|
||||
|
||||
One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
|
||||
|
||||
## Embedding React components with MDX
|
||||
|
||||
Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components.
|
||||
|
||||
|
|
@ -169,6 +178,7 @@ export const Highlight = ({children, color}) => (
|
|||
);
|
||||
|
||||
<BrowserWindow minHeight={240} url="http://localhost:3000">
|
||||
|
||||
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
|
||||
|
||||
I can write **Markdown** alongside my _JSX_!
|
||||
|
|
@ -179,199 +189,6 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
|
||||
|
||||
### Referencing other documents
|
||||
|
||||
If you want to reference another document file, you should use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
|
||||
|
||||
For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
|
||||
|
||||
```md
|
||||
I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md)
|
||||
[Relative document](../doc2.md) referencing works as well.
|
||||
```
|
||||
|
||||
One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
|
||||
|
||||
### Syntax highlighting
|
||||
|
||||
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
|
||||
|
||||
```jsx
|
||||
console.log('Every repo must come with a mascot.');
|
||||
```
|
||||
|
||||
<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->
|
||||
|
||||
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
|
||||
|
||||
```jsx
|
||||
console.log('Every repo must come with a mascot.');
|
||||
```
|
||||
|
||||
By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `theme` field in `prism` as `themeConfig` in your docusaurus.config.js.
|
||||
|
||||
For example, if you prefer to use the `dracula` highlighting theme:
|
||||
|
||||
```js {3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
prism: {
|
||||
theme: require('prism-react-renderer/themes/dracula'),
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
|
||||
|
||||
To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages),
|
||||
define it in an array of additional languages.
|
||||
|
||||
For example, if you want to add highlighting for the `powershell` language:
|
||||
|
||||
```js {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
prism: {
|
||||
additionalLanguages: ['powershell'],
|
||||
},
|
||||
...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Line highlighting
|
||||
|
||||
You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
|
||||
|
||||
```jsx {3}
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
```jsx {3}
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
|
||||
|
||||
```jsx
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
// highlight-next-line
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
|
||||
function HighlightMoreText(highlight) {
|
||||
// highlight-start
|
||||
if (highlight) {
|
||||
return 'This range is highlighted!';
|
||||
}
|
||||
// highlight-end
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
```jsx
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
// highlight-next-line
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
function HighlightMoreText(highlight) {
|
||||
// highlight-start
|
||||
if (highlight) {
|
||||
return 'This range is highlighted!';
|
||||
}
|
||||
// highlight-end
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
JS style (`/* */` and `//`), JSX style (`{ /* */ }`), Python style (`# `), and HTML style (`<!-- -->`) are supported.
|
||||
|
||||
To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
|
||||
|
||||
```css title="/src/css/custom.css"
|
||||
.docusaurus-highlight-code-line {
|
||||
background-color: rgb(72, 77, 91);
|
||||
display: block;
|
||||
margin: 0 calc(-1 * var(--ifm-pre-padding));
|
||||
padding: 0 var(--ifm-pre-padding);
|
||||
}
|
||||
|
||||
/* If you have a different syntax highlighting theme for dark mode. */
|
||||
html[data-theme='dark'] .docusaurus-highlight-code-line {
|
||||
background-color: /* Color which works with dark mode syntax highlighting theme */
|
||||
}
|
||||
```
|
||||
|
||||
To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
|
||||
|
||||
```jsx {1,4-6,11}
|
||||
import React from 'react';
|
||||
|
||||
function MyComponent(props) {
|
||||
if (props.isBar) {
|
||||
return <div>Bar</div>;
|
||||
}
|
||||
|
||||
return <div>Foo</div>;
|
||||
}
|
||||
|
||||
export default MyComponent;
|
||||
```
|
||||
|
||||
```jsx {1,4-6,11}
|
||||
import React from 'react';
|
||||
|
||||
function MyComponent(props) {
|
||||
if (props.isBar) {
|
||||
return <div>Bar</div>;
|
||||
}
|
||||
|
||||
return <div>Foo</div>;
|
||||
}
|
||||
|
||||
export default MyComponent;
|
||||
```
|
||||
|
||||
### Code title
|
||||
|
||||
You can add title to code block by adding `title` key after the language (leave a space between them).
|
||||
|
||||
```jsx title="src/components/HelloCodeTitle.js"
|
||||
function HelloCodeTitle(props) {
|
||||
return <h1>Hello, {props.name}</h1>;
|
||||
}
|
||||
```
|
||||
|
||||
```jsx title="src/components/HelloCodeTitle.js"
|
||||
function HelloCodeTitle(props) {
|
||||
return <h1>Hello, {props.name}</h1>;
|
||||
}
|
||||
```
|
||||
|
||||
### Configuring plugins
|
||||
|
||||
You can expand the MDX functionalities, using plugins. An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Docusaurus supports both [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
|
||||
|
|
@ -440,6 +257,405 @@ module.exports = {
|
|||
|
||||
See more information in the [MDX documentation](https://mdxjs.com/advanced/plugins).
|
||||
|
||||
## Tabs
|
||||
|
||||
To show tabbed content within Markdown files, you can fall back on MDX. Docusaurus provides `<Tabs>` components out-of-the-box.
|
||||
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<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>
|
||||
```
|
||||
|
||||
will result in
|
||||
|
||||
<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>
|
||||
|
||||
### Syncing tab choices
|
||||
|
||||
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Not that `groupID` are globally-namespaced.
|
||||
|
||||
```jsx {2,14}
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
|
||||
<TabItem value="mac">Use Command + C to copy.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
|
||||
<TabItem value="mac">Use Command + V to paste.</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
|
||||
<TabItem value="mac">Use Command + C to copy.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
|
||||
<TabItem value="mac">Use Command + V to paste.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
Tab choices with different `groupId`s will not interfere with each other:
|
||||
|
||||
```jsx {2,14}
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows in windows.</TabItem>
|
||||
<TabItem value="mac">macOS is macOS.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="non-mac-operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'Unix', value: 'unix', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows is windows.</TabItem>
|
||||
<TabItem value="unix">Unix is unix.</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows in windows.</TabItem>
|
||||
<TabItem value="mac">macOS is macOS.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="non-mac-operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'Unix', value: 'unix', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows is windows.</TabItem>
|
||||
<TabItem value="unix">Unix is unix.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Callouts/admonitions
|
||||
|
||||
In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions.
|
||||
Admonitions are wrapped by a set of 3 colons.
|
||||
|
||||
Example:
|
||||
|
||||
:::note
|
||||
The content and title *can* include markdown.
|
||||
:::
|
||||
|
||||
:::tip You can specify an optional title
|
||||
Heads up! Here's a pro-tip.
|
||||
:::
|
||||
|
||||
:::info
|
||||
Useful information.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
Warning! You better pay attention!
|
||||
:::
|
||||
|
||||
:::danger
|
||||
Danger danger, mayday!
|
||||
:::
|
||||
|
||||
:::note
|
||||
The content and title *can* include markdown.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
Heads up! Here's a pro-tip.
|
||||
:::
|
||||
|
||||
:::info
|
||||
Useful information.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
Warning! You better pay attention!
|
||||
:::
|
||||
|
||||
:::danger
|
||||
Danger danger, mayday!
|
||||
:::
|
||||
|
||||
### Specifying title
|
||||
|
||||
You may also specify an optional title
|
||||
|
||||
:::note Your Title
|
||||
The content and title *can* include markdown.
|
||||
:::
|
||||
|
||||
:::note Your Title
|
||||
The content and title *can* include markdown.
|
||||
:::
|
||||
|
||||
## Code Blocks
|
||||
|
||||
Code blocks within documentation are super-powered 💪.
|
||||
|
||||
### Code title
|
||||
|
||||
You can add a title to the code block by adding `title` key after the language (leave a space between them).
|
||||
|
||||
```jsx title="src/components/HelloCodeTitle.js"
|
||||
function HelloCodeTitle(props) {
|
||||
return <h1>Hello, {props.name}</h1>;
|
||||
}
|
||||
```
|
||||
|
||||
```jsx title="src/components/HelloCodeTitle.js"
|
||||
function HelloCodeTitle(props) {
|
||||
return <h1>Hello, {props.name}</h1>;
|
||||
}
|
||||
```
|
||||
|
||||
### Syntax highlighting
|
||||
|
||||
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
|
||||
|
||||
```jsx
|
||||
console.log('Every repo must come with a mascot.');
|
||||
```
|
||||
|
||||
<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->
|
||||
|
||||
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
|
||||
|
||||
```jsx
|
||||
console.log('Every repo must come with a mascot.');
|
||||
```
|
||||
|
||||
By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `theme` field in `prism` as `themeConfig` in your docusaurus.config.js.
|
||||
|
||||
For example, if you prefer to use the `dracula` highlighting theme:
|
||||
|
||||
```js {4} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
prism: {
|
||||
theme: require('prism-react-renderer/themes/dracula'),
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
|
||||
|
||||
To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages),
|
||||
define it in an array of additional languages.
|
||||
|
||||
For example, if you want to add highlighting for the `powershell` language:
|
||||
|
||||
```js {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
prism: {
|
||||
additionalLanguages: ['powershell'],
|
||||
},
|
||||
...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Line highlighting
|
||||
|
||||
You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
|
||||
|
||||
```jsx {3}
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
```jsx {3}
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
|
||||
|
||||
```css title="/src/css/custom.css"
|
||||
.docusaurus-highlight-code-line {
|
||||
background-color: rgb(72, 77, 91);
|
||||
display: block;
|
||||
margin: 0 calc(-1 * var(--ifm-pre-padding));
|
||||
padding: 0 var(--ifm-pre-padding);
|
||||
}
|
||||
|
||||
/* If you have a different syntax highlighting theme for dark mode. */
|
||||
html[data-theme='dark'] .docusaurus-highlight-code-line {
|
||||
background-color: /* Color which works with dark mode syntax highlighting theme */
|
||||
}
|
||||
```
|
||||
|
||||
To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
|
||||
|
||||
```jsx {1,4-6,11}
|
||||
import React from 'react';
|
||||
|
||||
function MyComponent(props) {
|
||||
if (props.isBar) {
|
||||
return <div>Bar</div>;
|
||||
}
|
||||
|
||||
return <div>Foo</div>;
|
||||
}
|
||||
|
||||
export default MyComponent;
|
||||
```
|
||||
|
||||
```jsx {1,4-6,11}
|
||||
import React from 'react';
|
||||
|
||||
function MyComponent(props) {
|
||||
if (props.isBar) {
|
||||
return <div>Bar</div>;
|
||||
}
|
||||
|
||||
return <div>Foo</div>;
|
||||
}
|
||||
|
||||
export default MyComponent;
|
||||
```
|
||||
|
||||
|
||||
You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
|
||||
|
||||
```jsx
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
// highlight-next-line
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
|
||||
function HighlightMoreText(highlight) {
|
||||
// highlight-start
|
||||
if (highlight) {
|
||||
return 'This range is highlighted!';
|
||||
}
|
||||
// highlight-end
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
```jsx
|
||||
function HighlightSomeText(highlight) {
|
||||
if (highlight) {
|
||||
// highlight-next-line
|
||||
return 'This text is highlighted!';
|
||||
}
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
|
||||
function HighlightMoreText(highlight) {
|
||||
// highlight-start
|
||||
if (highlight) {
|
||||
return 'This range is highlighted!';
|
||||
}
|
||||
// highlight-end
|
||||
|
||||
return 'Nothing highlighted';
|
||||
}
|
||||
```
|
||||
|
||||
Supported commenting syntax:
|
||||
|
||||
|Language|Syntax|
|
||||
|---|---|
|
||||
|JavaScript|`/* ... */` and `// ...`|
|
||||
|JSX|`{/* ... */}`|
|
||||
|Python|`# ...`|
|
||||
|HTML|`<!-- ... -->`|
|
||||
|
||||
If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
|
||||
|
||||
### Interactive code editor
|
||||
|
||||
(Powered by [React Live](https://github.com/FormidableLabs/react-live))
|
||||
|
|
@ -603,128 +819,4 @@ class HelloWorld {
|
|||
|
||||
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, read on for the [Syncing tab choices section](#syncing-tab-choices).
|
||||
|
||||
### Syncing tab choices
|
||||
|
||||
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId`. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed.
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
|
||||
<TabItem value="mac">Use Command + C to copy.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
|
||||
<TabItem value="mac">Use Command + V to paste.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + C to copy.</TabItem>
|
||||
<TabItem value="mac">Use Command + C to copy.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'macOS', value: 'mac', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Use Ctrl + V to paste.</TabItem>
|
||||
<TabItem value="mac">Use Command + V to paste.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Tab choices with different `groupId`s will not interfere with each other:
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
<Tabs
|
||||
groupId="non-mac-operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'Unix', value: 'unix', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows is windows.</TabItem>
|
||||
<TabItem value="unix">Unix is unix.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="non-mac-operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'Unix', value: 'unix', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows is not unix.</TabItem>
|
||||
<TabItem value="unix">Unix is not windows.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="non-mac-operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'Unix', value: 'unix', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows is windows.</TabItem>
|
||||
<TabItem value="unix">Unix is unix.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs
|
||||
groupId="non-mac-operating-systems"
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{ label: 'Windows', value: 'win', },
|
||||
{ label: 'Unix', value: 'unix', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="win">Windows is not unix.</TabItem>
|
||||
<TabItem value="unix">Unix is not windows.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Callouts/admonitions
|
||||
|
||||
In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions.
|
||||
Admonitions are wrapped by a set of 3 colons.
|
||||
|
||||
Example:
|
||||
|
||||
```markdown
|
||||
:::tip Title
|
||||
The content and title *can* include markdown.
|
||||
:::
|
||||
```
|
||||
|
||||
:::tip Title
|
||||
The content and title *can* include markdown.
|
||||
:::
|
||||
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](#syncing-tab-choices).
|
||||
|
|
|
|||
|
|
@ -5,9 +5,13 @@ title: Migrating from v1 to v2
|
|||
|
||||
import ColorGenerator from '@site/src/components/ColorGenerator';
|
||||
|
||||
This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
|
||||
:::caution
|
||||
|
||||
**Note: This migration guide is targeted at Docusaurus users without translation and/or versioning features and assumes the following structure:**
|
||||
This migration guide is targeted at Docusaurus users without translation and/or versioning features.
|
||||
|
||||
:::
|
||||
|
||||
This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2. Your Docusaurus 1 site should have the following structure:
|
||||
|
||||
```sh
|
||||
├── docs
|
||||
|
|
@ -326,7 +330,7 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust
|
|||
|
||||
Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
|
||||
|
||||
```jsx {8-21} title="docusaurus.config.js"
|
||||
```jsx {8-20} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -471,9 +475,9 @@ In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com
|
|||
|
||||
Refer to the [multi-language support code blocks](markdown-features.mdx#multi-language-support-code-blocks) section.
|
||||
|
||||
### Frontmatter
|
||||
### Front matter
|
||||
|
||||
The Docusaurus frontmatter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
|
||||
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
|
||||
|
||||
The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field.
|
||||
|
||||
|
|
@ -523,9 +527,9 @@ The versioning feature is a work in progress! Although we've implemented docs ve
|
|||
|
||||
## Changes from v1
|
||||
|
||||
Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem
|
||||
Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
|
||||
|
||||
### Migrate your `versioned_docs` frontmatter
|
||||
### Migrate your `versioned_docs` front matter
|
||||
|
||||
Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation.
|
||||
|
||||
|
|
@ -629,7 +633,7 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`:
|
|||
|
||||
### Populate your `versioned_sidebars` and `versioned_docs`
|
||||
|
||||
In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).
|
||||
In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).
|
||||
|
||||
For example, if your `versions.json` looks like this in v1
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ You can use the version script to cut a new documentation version based on the l
|
|||
|
||||
:::caution
|
||||
|
||||
Consider hard before starting to version your documentation.
|
||||
Consider well before starting to version your documentation.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue