mirror of
https://github.com/facebook/docusaurus.git
synced 2025-07-30 23:08:54 +02:00
chore(v2): prepare v2.0.0-beta.6 release (#5473)
* add beta.6 * v2.0.0-beta.6
This commit is contained in:
Sébastien Lorber
GitHub
parent
cb8718a1e3
commit
2611bbb501
108 changed files with 13439 additions and 147 deletions
|
|
@ -0,0 +1,3 @@
|
|||
<span>Hello {props.name}</span>
|
||||
|
||||
This is text some content from `_markdown-partial-example.md`.
|
||||
|
|
@ -0,0 +1,135 @@
|
|||
---
|
||||
id: admonitions
|
||||
title: Admonitions
|
||||
description: Handling admonitions/callouts in Docusaurus Markdown
|
||||
slug: /markdown-features/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
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::info
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::danger
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::note
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::info
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
:::danger
|
||||
|
||||
Some **content** with _markdown_ `syntax`. Check [this `api`](#).
|
||||
|
||||
:::
|
||||
|
||||
## Specifying title {#specifying-title}
|
||||
|
||||
You may also specify an optional title
|
||||
|
||||
:::note Your Title
|
||||
|
||||
Some **content** with _markdown_ `syntax`.
|
||||
|
||||
:::
|
||||
|
||||
:::note Your Title
|
||||
|
||||
Some **content** with _markdown_ `syntax`.
|
||||
|
||||
:::
|
||||
|
||||
## Admonitions with MDX
|
||||
|
||||
You can use MDX inside admonitions too!
|
||||
|
||||
```mdx
|
||||
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>
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
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>
|
||||
```
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
id: assets
|
||||
title: Assets
|
||||
description: Handling assets in Docusaurus Markdown
|
||||
slug: /markdown-features/assets
|
||||
---
|
||||
|
||||
Sometimes you want to link to static assets directly from Markdown files, and it is convenient to co-locate the asset next to the Markdown file using it.
|
||||
|
||||
We have setup Webpack loaders to handle most common file types, so that when you import a file, you get its url, and the asset is automatically copied to the output folder.
|
||||
|
||||
Let's imagine the following file structure:
|
||||
|
||||
```
|
||||
# Your doc
|
||||
/website/docs/myFeature.mdx
|
||||
|
||||
# Some assets you want to use
|
||||
/website/docs/assets/docusaurus-asset-example-banner.png
|
||||
/website/docs/assets/docusaurus-asset-example-pdf.pdf
|
||||
```
|
||||
|
||||
## Images {#images}
|
||||
|
||||
You can display images in three different ways: Markdown syntax, JSX require or ES imports syntax.
|
||||
|
||||
Display images using simple Markdown syntax:
|
||||
|
||||
```mdx
|
||||
|
||||
```
|
||||
|
||||
Display images using inline CommonJS `require` in JSX image tag:
|
||||
|
||||
```mdx
|
||||
<img
|
||||
src={require('./assets/docusaurus-asset-example-banner.png').default}
|
||||
alt="Example banner"
|
||||
/>
|
||||
```
|
||||
|
||||
Display images using ES `import` syntax and JSX image tag:
|
||||
|
||||
```mdx
|
||||
import myImageUrl from './assets/docusaurus-asset-example-banner.png';
|
||||
|
||||
<img src={myImageUrl} alt="Example banner" />
|
||||
```
|
||||
|
||||
This results in displaying the image:
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
|
||||
If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal-image.md), you need to use the dedicated image component, as documented.
|
||||
|
||||
:::
|
||||
|
||||
## Files {#files}
|
||||
|
||||
In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc.
|
||||
|
||||
```mdx
|
||||
# My Markdown page
|
||||
|
||||
<a
|
||||
target="_blank"
|
||||
href={require('./assets/docusaurus-asset-example-pdf.pdf').default}>
|
||||
Download this PDF
|
||||
</a>
|
||||
|
||||
or
|
||||
|
||||
[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf)
|
||||
```
|
||||
|
||||
<a
|
||||
target="_blank"
|
||||
href={require('../../assets/docusaurus-asset-example-pdf.pdf').default}>
|
||||
Download this PDF
|
||||
</a>
|
||||
|
||||
[Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf)
|
||||
|
||||
## Inline SVGs {#inline-svgs}
|
||||
|
||||
Docusaurus supports inlining SVGs out of the box.
|
||||
|
||||
```jsx
|
||||
import DocusaurusSvg from './docusaurus.svg';
|
||||
|
||||
<DocusaurusSvg />;
|
||||
```
|
||||
|
||||
import DocusaurusSvg from '@site/static/img/docusaurus.svg';
|
||||
|
||||
<DocusaurusSvg />
|
||||
|
||||
This can be useful, if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme.
|
||||
|
||||
```jsx
|
||||
import DocusaurusSvg from './docusaurus.svg';
|
||||
|
||||
<DocusaurusSvg className="themedDocusaurus" />;
|
||||
```
|
||||
|
||||
```css
|
||||
html[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
|
||||
fill: greenyellow;
|
||||
}
|
||||
|
||||
html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
|
||||
fill: seagreen;
|
||||
}
|
||||
```
|
||||
|
||||
<DocusaurusSvg className="themedDocusaurus" />
|
||||
|
||||
## Themed Images {#themed-images}
|
||||
|
||||
Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme.
|
||||
|
||||
```jsx {5-8}
|
||||
import ThemedImage from '@theme/ThemedImage';
|
||||
|
||||
<ThemedImage
|
||||
alt="Docusaurus themed image"
|
||||
sources={{
|
||||
light: useBaseUrl('/img/docusaurus_light.svg'),
|
||||
dark: useBaseUrl('/img/docusaurus_dark.svg'),
|
||||
}}
|
||||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
import ThemedImage from '@theme/ThemedImage';
|
||||
|
||||
<ThemedImage
|
||||
alt="Docusaurus themed image"
|
||||
sources={{
|
||||
light: useBaseUrl('/img/docusaurus_keytar.svg'),
|
||||
dark: useBaseUrl('/img/docusaurus_speed.svg'),
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
|
@ -0,0 +1,460 @@
|
|||
---
|
||||
id: code-blocks
|
||||
title: Code blocks
|
||||
description: Handling code blocks in Docusaurus Markdown
|
||||
slug: /markdown-features/code-blocks
|
||||
---
|
||||
|
||||
Code blocks within documentation are super-powered 💪.
|
||||
|
||||
## Code title {#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 {#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.');
|
||||
```
|
||||
|
||||
### Theming {#theming}
|
||||
|
||||
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'),
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Supported Languages {#supported-languages}
|
||||
|
||||
By default, Docusaurus comes with a subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
|
||||
|
||||
:::caution
|
||||
|
||||
Some popular languages like Java, C#, or PHP are not enabled by default.
|
||||
|
||||
:::
|
||||
|
||||
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'],
|
||||
},
|
||||
// ...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
After adding `additionalLanguages`, restart Docusaurus.
|
||||
|
||||
If you want to add highlighting for languages not yet supported by Prism, you can swizzle `prism-include-languages`:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run swizzle @docusaurus/theme-classic prism-include-languages
|
||||
```
|
||||
|
||||
It will produce `prism-include-languages.js` in your `src/theme` folder. You can add highlighting support for custom languages by editing `prism-include-languages.js`:
|
||||
|
||||
```js {8} title="src/theme/prism-include-languages.js"
|
||||
const prismIncludeLanguages = (Prism) => {
|
||||
// ...
|
||||
|
||||
additionalLanguages.forEach((lang) => {
|
||||
require(`prismjs/components/prism-${lang}`); // eslint-disable-line
|
||||
});
|
||||
|
||||
require('/path/to/your/prism-language-definition');
|
||||
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions.
|
||||
|
||||
## Line highlighting {#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 {
|
||||
/* Color which works with dark mode syntax highlighting theme */
|
||||
background-color: rgb(100, 100, 100);
|
||||
}
|
||||
```
|
||||
|
||||
### Multiple line highlighting {#multiple-line-highlighting}
|
||||
|
||||
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;
|
||||
```
|
||||
|
||||
### Highlighting with comments {#highlighting-with-comments}
|
||||
|
||||
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 {#interactive-code-editor}
|
||||
|
||||
(Powered by [React Live](https://github.com/FormidableLabs/react-live))
|
||||
|
||||
You can create an interactive coding editor with the `@docusaurus/theme-live-codeblock` plugin.
|
||||
|
||||
First, add the plugin to your package.
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save @docusaurus/theme-live-codeblock
|
||||
```
|
||||
|
||||
You will also need to add the plugin to your `docusaurus.config.js`.
|
||||
|
||||
```js {3}
|
||||
module.exports = {
|
||||
// ...
|
||||
themes: ['@docusaurus/theme-live-codeblock'],
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
To use the plugin, create a code block with `live` attached to the language meta string.
|
||||
|
||||
```jsx live
|
||||
function Clock(props) {
|
||||
const [date, setDate] = useState(new Date());
|
||||
useEffect(() => {
|
||||
var timerID = setInterval(() => tick(), 1000);
|
||||
|
||||
return function cleanup() {
|
||||
clearInterval(timerID);
|
||||
};
|
||||
});
|
||||
|
||||
function tick() {
|
||||
setDate(new Date());
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h2>It is {date.toLocaleTimeString()}.</h2>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.
|
||||
|
||||
```jsx live
|
||||
function Clock(props) {
|
||||
const [date, setDate] = useState(new Date());
|
||||
useEffect(() => {
|
||||
var timerID = setInterval(() => tick(), 1000);
|
||||
|
||||
return function cleanup() {
|
||||
clearInterval(timerID);
|
||||
};
|
||||
});
|
||||
|
||||
function tick() {
|
||||
setDate(new Date());
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h2>It is {date.toLocaleTimeString()}.</h2>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Imports {#imports}
|
||||
|
||||
:::caution react-live and imports
|
||||
|
||||
It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.
|
||||
|
||||
:::
|
||||
|
||||
By default, all React imports are available. If you need more imports available, swizzle the react-live scope:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope
|
||||
```
|
||||
|
||||
```jsx {3-15,21} title="src/theme/ReactLiveScope/index.js"
|
||||
import React from 'react';
|
||||
|
||||
const ButtonExample = (props) => (
|
||||
<button
|
||||
{...props}
|
||||
style={{
|
||||
backgroundColor: 'white',
|
||||
border: 'solid red',
|
||||
borderRadius: 20,
|
||||
padding: 10,
|
||||
cursor: 'pointer',
|
||||
...props.style,
|
||||
}}
|
||||
/>
|
||||
);
|
||||
|
||||
// Add react-live imports you need here
|
||||
const ReactLiveScope = {
|
||||
React,
|
||||
...React,
|
||||
ButtonExample,
|
||||
};
|
||||
|
||||
export default ReactLiveScope;
|
||||
```
|
||||
|
||||
The `ButtonExample` component is now available to use:
|
||||
|
||||
```jsx live
|
||||
function MyPlayground(props) {
|
||||
return (
|
||||
<div>
|
||||
<ButtonExample onClick={() => alert('hey!')}>Click me</ButtonExample>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Multi-language support code blocks {#multi-language-support-code-blocks}
|
||||
|
||||
With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.
|
||||
|
||||
Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well.
|
||||
|
||||
The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block is **intentional**. This is a current limitation of MDX, you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.
|
||||
|
||||
````jsx
|
||||
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">
|
||||
|
||||
```js
|
||||
function helloWorld() {
|
||||
console.log('Hello, world!');
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="py">
|
||||
|
||||
```py
|
||||
def hello_world():
|
||||
print 'Hello, world!'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="java">
|
||||
|
||||
```java
|
||||
class HelloWorld {
|
||||
public static void main(String args[]) {
|
||||
System.out.println("Hello, World");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
````
|
||||
|
||||
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">
|
||||
|
||||
```js
|
||||
function helloWorld() {
|
||||
console.log('Hello, world!');
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="py">
|
||||
|
||||
```py
|
||||
def hello_world():
|
||||
print 'Hello, world!'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="java">
|
||||
|
||||
```java
|
||||
class HelloWorld {
|
||||
public static void main(String args[]) {
|
||||
System.out.println("Hello, World");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</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).
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
---
|
||||
id: head-metadatas
|
||||
title: Head Metadatas
|
||||
description: Declaring page-specific head metadatas through MDX
|
||||
slug: /markdown-features/head-metadatas
|
||||
---
|
||||
|
||||
# Head Metadatas
|
||||
|
||||
Docusaurus automatically sets useful page metadatas in `<html>`, `<head>` and `<body>` for you.
|
||||
|
||||
It is possible to add extra metadatas (or override existing ones) by using the `<head>` tag in Markdown files:
|
||||
|
||||
```md title="markdown-features-head-metadatas.mdx"
|
||||
---
|
||||
id: head-metadatas
|
||||
title: Head Metadatas
|
||||
---
|
||||
|
||||
<!-- highlight-start -->
|
||||
<head>
|
||||
<html className="some-extra-html-class" />
|
||||
<body className="other-extra-body-class" />
|
||||
<title>Head Metadatas customized title!</title>
|
||||
<meta charSet="utf-8" />
|
||||
<meta name="twitter:card" content="summary" />
|
||||
<link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadatas" />
|
||||
</head>
|
||||
<!-- highlight-end -->
|
||||
|
||||
# Head Metadatas
|
||||
|
||||
My text
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<head>
|
||||
<html className="some-extra-html-class" />
|
||||
<body className="other-extra-body-class" />
|
||||
<title>Head Metadatas customized title!</title>
|
||||
<meta charSet="utf-8" />
|
||||
<meta name="twitter:card" content="summary" />
|
||||
<link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadatas" />
|
||||
</head>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
This `<head>` declaration has been added to the current Markdown doc, as a demo.
|
||||
|
||||
Open your browser DevTools and check how this page's metadatas have been affected.
|
||||
|
||||
:::
|
||||
|
||||
:::note
|
||||
|
||||
This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.md#head) component.
|
||||
|
||||
Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
id: headings
|
||||
title: Headings
|
||||
description: Using Markdown headings
|
||||
slug: /markdown-features/headings
|
||||
---
|
||||
|
||||
## Markdown headings {#markdown-headings}
|
||||
|
||||
You can use regular Markdown headings.
|
||||
|
||||
```
|
||||
## Level 2 title
|
||||
|
||||
### Level 3 title
|
||||
|
||||
#### Level 4 title
|
||||
```
|
||||
|
||||
Markdown headings appear as a table-of-contents entry.
|
||||
|
||||
## Heading ids {#heading-ids}
|
||||
|
||||
Each heading has an id that can be automatically generated, or explicitly specified.
|
||||
|
||||
Heading ids allow you to link to a specific document heading in Markdown or JSX:
|
||||
|
||||
```md
|
||||
[link](#heading-id)
|
||||
```
|
||||
|
||||
```jsx
|
||||
<Link to="#heading-id">link</Link>
|
||||
```
|
||||
|
||||
### Generated ids {#generated-ids}
|
||||
|
||||
By default, Docusaurus will generate heading ids for you, based on the heading text.
|
||||
|
||||
`### Hello World` will have id `hello-world`.
|
||||
|
||||
Generated ids have **some limits**:
|
||||
|
||||
- The id might not look good
|
||||
- You might want to **change or translate** the text without updating the existing id
|
||||
|
||||
### Explicit ids {#explicit-ids}
|
||||
|
||||
A special Markdown syntax lets you set an **explicit heading id**:
|
||||
|
||||
```md
|
||||
### Hello World {#my-explicit-id}
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit ids to all your Markdown documents.
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
id: inline-toc
|
||||
title: Inline TOC
|
||||
description: Using inline table-of-contents inside Docusaurus Markdown
|
||||
slug: /markdown-features/inline-toc
|
||||
---
|
||||
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
|
||||
Each Markdown document displays a tab of content on the top-right corner.
|
||||
|
||||
But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
|
||||
|
||||
## Full table of contents {#full-table-of-contents}
|
||||
|
||||
The `toc` variable is available in any MDX document, and contain all the top level headings of a MDX document.
|
||||
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
<TOCInline toc={toc} />;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
<BrowserWindow>
|
||||
|
||||
<TOCInline toc={toc} />
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
## Custom table of contents {#custom-table-of-contents}
|
||||
|
||||
The `toc` props is just a list of table of contents items:
|
||||
|
||||
```ts
|
||||
type TOCItem = {
|
||||
value: string;
|
||||
id: string;
|
||||
children: TOCItem[];
|
||||
};
|
||||
```
|
||||
|
||||
You can create this TOC tree manually, or derive a new TOC tree from the `toc` variable:
|
||||
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
<TOCInline
|
||||
toc={
|
||||
// Only show 3th and 5th top-level heading
|
||||
[toc[2], toc[4]]
|
||||
}
|
||||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
<TOCInline toc={[toc[2], toc[4]]} />
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
:::caution
|
||||
|
||||
The underlying content is just an example to have more table-of-contents items available in current page.
|
||||
|
||||
:::
|
||||
|
||||
## Example Section 1 {#example-section-1}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 1 a {#example-subsection-1-a}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 1 b {#example-subsection-1-b}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 1 c {#example-subsection-1-c}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
## Example Section 2 {#example-section-2}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 2 a {#example-subsection-2-a}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 2 b {#example-subsection-2-b}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 2 c {#example-subsection-2-c}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
## Example Section 3 {#example-section-3}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 3 a {#example-subsection-3-a}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 3 b {#example-subsection-3-b}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
### Example Subsection 3 c {#example-subsection-3-c}
|
||||
|
||||
Lorem ipsum
|
||||
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
id: introduction
|
||||
title: Markdown Features
|
||||
sidebar_label: Introduction
|
||||
description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown.
|
||||
slug: /markdown-features
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build a powerful documentation. Let us walk you through with an example.
|
||||
|
||||
:::important
|
||||
|
||||
This section assumes you are using the official Docusaurus content plugins.
|
||||
|
||||
:::
|
||||
|
||||
## Standard features
|
||||
|
||||
Markdown is a syntax that enables you to write formatted content in a readable syntax.
|
||||
|
||||
The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported, and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents.
|
||||
|
||||
```md
|
||||
### My Doc Section
|
||||
|
||||
Hello world message with some **bold** text, some _italic_ text and a [link](/)
|
||||
|
||||
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
<h2>My Doc Section</h2>
|
||||
|
||||
Hello world message with some **bold** text, some _italic_ text and a [link](/)
|
||||
|
||||
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
## Quotes
|
||||
|
||||
Markdown quotes are beautifully styled:
|
||||
|
||||
```md
|
||||
> This is a quote
|
||||
```
|
||||
|
||||
> This is a quote
|
||||
|
||||
## Details
|
||||
|
||||
Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled:
|
||||
|
||||
```md
|
||||
### Details element example
|
||||
|
||||
<details>
|
||||
<summary>Toggle me!</summary>
|
||||
<div>
|
||||
<div>This is the detailed content</div>
|
||||
<br/>
|
||||
<details>
|
||||
<summary>
|
||||
Nested toggle! Some surprise inside...
|
||||
</summary>
|
||||
<div>
|
||||
😲😲😲😲😲
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</details>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
<h3>Details element example</h3>
|
||||
|
||||
<details>
|
||||
<summary>Toggle me!</summary>
|
||||
<div>
|
||||
<div>This is the detailed content</div>
|
||||
<br/>
|
||||
<details>
|
||||
<summary>
|
||||
Nested toggle! Some surprise inside...
|
||||
</summary>
|
||||
<div>
|
||||
😲😲😲😲😲
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
</BrowserWindow>
|
||||
|
||||
<br/>
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
In practice, those are not really HTML elements, but React JSX elements, which we'll cover next!
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,116 @@
|
|||
---
|
||||
id: math-equations
|
||||
title: Math Equations
|
||||
description: Writing LaTeX Math Equations
|
||||
slug: /markdown-features/math-equations
|
||||
---
|
||||
|
||||
Mathematical equations can be rendered using [KaTeX](https://katex.org).
|
||||
|
||||
## Usage
|
||||
|
||||
Please read [KaTeX](https://katex.org) documentation for more details.
|
||||
|
||||
### Inline
|
||||
|
||||
Write inline math equations by wrapping LaTeX equations between `$`:
|
||||
|
||||
```mdx
|
||||
Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)=
|
||||
\int_{a}^{x}f(t)dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
|
||||
```
|
||||
|
||||
Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)=
|
||||
\int_{a}^{x}f(t)dt$. Then $F$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
|
||||
|
||||
### Blocks
|
||||
|
||||
For equation block or display mode, use line breaks and `$$`:
|
||||
|
||||
```mdx
|
||||
$$
|
||||
I = \int_0^{2\pi} \sin(x) dx
|
||||
$$
|
||||
```
|
||||
|
||||
$$
|
||||
I = \int_0^{2\pi} \sin(x) dx
|
||||
$$
|
||||
|
||||
## Configuration
|
||||
|
||||
To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save remark-math@3 rehype-katex@4 hast-util-is-element@1.1.0
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
Use the exact same versions. The latest versions are incompatible with Docusaurus 2.
|
||||
|
||||
:::
|
||||
|
||||
Import the plugins in `docusaurus.config.js`:
|
||||
|
||||
```js
|
||||
const math = require('remark-math');
|
||||
const katex = require('rehype-katex');
|
||||
```
|
||||
|
||||
Add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
|
||||
|
||||
```js
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
```
|
||||
|
||||
Include the KaTeX CSS in your config under `stylesheets`:
|
||||
|
||||
```js
|
||||
stylesheets: [
|
||||
{
|
||||
href: "https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css",
|
||||
integrity: "sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc",
|
||||
crossorigin: "anonymous",
|
||||
},
|
||||
],
|
||||
```
|
||||
|
||||
Overall the changes look like:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
const math = require('remark-math');
|
||||
const katex = require('rehype-katex');
|
||||
// highlight-end
|
||||
|
||||
module.exports = {
|
||||
title: 'Docusaurus',
|
||||
tagline: 'Build optimized websites quickly, focus on your content',
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
// highlight-start
|
||||
stylesheets: [
|
||||
{
|
||||
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css',
|
||||
integrity:
|
||||
'sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc',
|
||||
crossorigin: 'anonymous',
|
||||
},
|
||||
],
|
||||
// highlight-end
|
||||
};
|
||||
```
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
id: plugins
|
||||
title: Plugins
|
||||
description: Using MDX plugins to expand Docusaurus Markdown functionalities
|
||||
slug: /markdown-features/plugins
|
||||
---
|
||||
|
||||
You can expand the MDX functionalities, using plugins.
|
||||
|
||||
Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
|
||||
|
||||
## Configuring plugins {#configuring-plugins}
|
||||
|
||||
An MDX plugin is usually a npm package, so you install them like other npm packages using npm.
|
||||
|
||||
First, install your [Remark](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) and [Rehype](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins) plugins.
|
||||
|
||||
For example:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save remark-images
|
||||
npm install --save rehype-truncate
|
||||
```
|
||||
|
||||
Next, import the plugins:
|
||||
|
||||
```js
|
||||
const remarkImages = require('remark-images');
|
||||
const rehypeTruncate = require('rehype-truncate');
|
||||
```
|
||||
|
||||
Finally, add them to the `@docusaurus/preset-classic` options in `docusaurus.config.js`:
|
||||
|
||||
```js {10,11} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
// ...
|
||||
remarkPlugins: [remarkImages],
|
||||
rehypePlugins: [rehypeTruncate],
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Configuring plugin options {#configuring-plugin-options}
|
||||
|
||||
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so:
|
||||
|
||||
```jsx {10-13} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
// ...
|
||||
remarkPlugins: [
|
||||
plugin1,
|
||||
[plugin2, {option1: {...}}],
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
See more information in the [MDX documentation](https://mdxjs.com/advanced/plugins).
|
||||
|
|
@ -0,0 +1,171 @@
|
|||
---
|
||||
id: react
|
||||
title: MDX and React
|
||||
description: Using the power of React in Docusaurus Markdown documents, thanks to MDX
|
||||
slug: /markdown-features/react
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
```
|
||||
|
||||
## Using JSX in Markdown {#using-jsx-in-markdown}
|
||||
|
||||
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.
|
||||
|
||||
:::note
|
||||
|
||||
While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax.
|
||||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
|
||||
MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018).
|
||||
|
||||
Use the **[MDX playground](https://mdxjs.com/playground)** to ensure that your syntax is valid MDX.
|
||||
|
||||
:::
|
||||
|
||||
Try this block here:
|
||||
|
||||
```jsx
|
||||
export const Highlight = ({children, color}) => (
|
||||
<span
|
||||
style={{
|
||||
backgroundColor: color,
|
||||
borderRadius: '2px',
|
||||
color: '#fff',
|
||||
padding: '0.2rem',
|
||||
}}>
|
||||
{children}
|
||||
</span>
|
||||
);
|
||||
|
||||
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
|
||||
|
||||
I can write **Markdown** alongside my _JSX_!
|
||||
```
|
||||
|
||||
Notice how it renders both the markup from your React component and the Markdown syntax:
|
||||
|
||||
```mdx-code-block
|
||||
export const Highlight = ({children, color}) => (
|
||||
<span
|
||||
style={{
|
||||
backgroundColor: color,
|
||||
borderRadius: '2px',
|
||||
color: '#fff',
|
||||
padding: '0.2rem',
|
||||
}}>
|
||||
{children}
|
||||
</span>
|
||||
);
|
||||
|
||||
<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_!
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
<br />
|
||||
|
||||
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.
|
||||
|
||||
:::caution
|
||||
|
||||
Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx).
|
||||
|
||||
:::
|
||||
|
||||
## Importing code snippets {#importing-code-snippets}
|
||||
|
||||
You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, first you need to install it in your project:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save raw-loader
|
||||
```
|
||||
|
||||
Now you can import code snippets from another file as it is:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```jsx title="myMarkdownFile.mdx"
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!./myComponent';
|
||||
|
||||
<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!@site/src/pages/examples/_myComponent';
|
||||
|
||||
<BrowserWindow url="http://localhost:3000">
|
||||
|
||||
<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>
|
||||
|
||||
</BrowserWindow>
|
||||
|
||||
<br />
|
||||
```
|
||||
|
||||
You can also pass `title` prop to `CodeBlock` component in order to appear it as header above your codeblock:
|
||||
|
||||
```jsx
|
||||
<CodeBlock className="language-jsx" title="/src/myComponent">
|
||||
{MyComponentSource}
|
||||
</CodeBlock>
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
You have to use `<CodeBlock>` rather than the Markdown triple-backtick ` ``` `, because the latter will ship out any of its content as-is, but you want JSX to insert the imported text here.
|
||||
|
||||
:::
|
||||
|
||||
:::warning
|
||||
|
||||
This feature is experimental and might be subject to API breaking changes in the future.
|
||||
|
||||
:::
|
||||
|
||||
## Importing Markdown {#importing-markdown}
|
||||
|
||||
You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages.
|
||||
|
||||
By convention, using the **`_` filename prefix** will not create any doc page and means the markdown file is a **"partial"**, to be imported by other files.
|
||||
|
||||
```md title="_markdown-partial-example.mdx"
|
||||
<span>Hello {props.name}</span>
|
||||
|
||||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<BrowserWindow url="http://localhost:3000">
|
||||
<PartialExample name="Sebastien" />
|
||||
</BrowserWindow>
|
||||
|
||||
<br />
|
||||
```
|
||||
|
||||
This way, you can reuse contents among multiple pages and avoid duplicating materials.
|
||||
|
||||
:::caution
|
||||
|
||||
The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)).
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,253 @@
|
|||
---
|
||||
id: tabs
|
||||
title: Tabs
|
||||
description: Using tabs inside Docusaurus Markdown
|
||||
slug: /markdown-features/tabs
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
```
|
||||
|
||||
Docusaurus provides `<Tabs>` components that you can use thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/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>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<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>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
It is also possible to provide `values` and `defaultValue` props to `Tabs`:
|
||||
|
||||
```jsx
|
||||
<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>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<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>
|
||||
</BrowserWindow>
|
||||
<br/>
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><code>Tabs</code> props take precedence over the <code>TabItem</code> props:</summary>
|
||||
|
||||
```jsx
|
||||
<Tabs
|
||||
defaultValue="apple"
|
||||
values={[
|
||||
{label: 'Apple 1', value: 'apple'},
|
||||
{label: 'Orange 1', value: 'orange'},
|
||||
{label: 'Banana 1', value: 'banana'},
|
||||
]}>
|
||||
<TabItem value="apple" label="Apple 2">
|
||||
This is an apple 🍎
|
||||
</TabItem>
|
||||
<TabItem value="orange" label="Orange 2">
|
||||
This is an orange 🍊
|
||||
</TabItem>
|
||||
<TabItem value="banana" label="Banana 2" default>
|
||||
This is a banana 🍌
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs
|
||||
defaultValue="apple"
|
||||
values={[
|
||||
{label: 'Apple 1', value: 'apple'},
|
||||
{label: 'Orange 1', value: 'orange'},
|
||||
{label: 'Banana 1', value: 'banana'},
|
||||
]}>
|
||||
<TabItem value="apple" label="Apple 2">This is an apple 🍎</TabItem>
|
||||
<TabItem value="orange" label="Orange 2">This is an orange 🍊</TabItem>
|
||||
<TabItem value="banana" label="Banana 2">This is a banana 🍌</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
<br/>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
:::tip
|
||||
|
||||
By default, all tabs are rendered eagerly during the build process, and search engines can index hidden tabs.
|
||||
|
||||
It is possible to only render the default tab with `<Tabs lazy={true} />`.
|
||||
|
||||
:::
|
||||
|
||||
## Displaying a default tab
|
||||
|
||||
Add `default` to one of the tab items to make it displayed by default. You can also set the `defaultValue` prop in the `Tabs` component to the label value of your choice.
|
||||
|
||||
For example, in the example above, setting `default` for the `value="apple"` tab forces it to be open by default.
|
||||
|
||||
If none of the children contains the `default` prop, neither is the `defaultValue` provided for the `Tabs`, or it refers to an non-existing value, only the tab headings appear until the user clicks on a tab.
|
||||
|
||||
## 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` 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. Note that `groupID` are globally-namespaced.
|
||||
|
||||
```jsx
|
||||
// highlight-next-line
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Use Ctrl + C to copy.</TabItem>
|
||||
<TabItem value="mac" label="MacOS">Use Command + C to copy.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
// highlight-next-line
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Use Ctrl + V to paste.</TabItem>
|
||||
<TabItem value="mac" label="MacOS">Use Command + V to paste.</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Use Ctrl + C to copy.</TabItem>
|
||||
<TabItem value="mac" label="MacOS">Use Command + C to copy.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Use Ctrl + V to paste.</TabItem>
|
||||
<TabItem value="mac" label="MacOS">Use Command + V to paste.</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
<br/>
|
||||
```
|
||||
|
||||
For all tab groups that have the same `groupId`, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same `groupId`, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change.
|
||||
|
||||
```jsx
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>
|
||||
I am Windows.
|
||||
</TabItem>
|
||||
<TabItem value="mac" label="MacOS">
|
||||
I am macOS.
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
I am Linux.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>I am Windows.</TabItem>
|
||||
<TabItem value="mac" label="MacOS">I am macOS.</TabItem>
|
||||
<TabItem value="linux" label="Linux">I am Linux.</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Tab choices with different `groupId`s will not interfere with each other:
|
||||
|
||||
```jsx
|
||||
// highlight-next-line
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Windows in windows.</TabItem>
|
||||
<TabItem value="mac" label="MacOS">macOS is macOS.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
// highlight-next-line
|
||||
<Tabs groupId="non-mac-operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Windows is windows.</TabItem>
|
||||
<TabItem value="unix" label="Unix">Unix is unix.</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Windows in windows.</TabItem>
|
||||
<TabItem value="mac" label="MacOS">macOS is macOS.</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Tabs groupId="non-mac-operating-systems">
|
||||
<TabItem value="win" label="Windows" default>Windows is windows.</TabItem>
|
||||
<TabItem value="unix" label="Unix">Unix is unix.</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
## Customizing tabs {#customizing-tabs}
|
||||
|
||||
You might want to customize the appearance of certain set of tabs. To do that you can pass the string in `className` prop and the specified CSS class will be added to the `Tabs` component:
|
||||
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
// highlight-next-line
|
||||
<Tabs className="unique-tabs">
|
||||
<TabItem value="Apple" default>
|
||||
This is an apple 🍎
|
||||
</TabItem>
|
||||
<TabItem value="Orange">This is an orange 🍊</TabItem>
|
||||
<TabItem value="Banana">This is a banana 🍌</TabItem>
|
||||
</Tabs>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs className="unique-tabs">
|
||||
<TabItem value="Apple" default>This is an apple 🍎</TabItem>
|
||||
<TabItem value="Orange">This is an orange 🍊</TabItem>
|
||||
<TabItem value="Banana">This is a banana 🍌</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue