mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-02 08:19:07 +02:00
chore(v2): prepare v2.0.0-beta.14 release (#6147)
This commit is contained in:
Sébastien Lorber
GitHub
parent
cc0a439e12
commit
01b407011a
118 changed files with 2121 additions and 1456 deletions
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
id: creating-pages
|
||||
title: Creating Pages
|
||||
slug: /creating-pages
|
||||
sidebar_label: Pages
|
||||
---
|
||||
|
||||
In this section, we will learn about creating pages in Docusaurus.
|
||||
|
||||
This is useful for creating **one-off standalone pages** like a showcase page, playground page or support page.
|
||||
|
||||
The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
|
||||
|
||||
You can use React components, or Markdown.
|
||||
|
||||
:::note
|
||||
|
||||
Pages do not have sidebars, only [docs](./docs/docs-introduction.md) do.
|
||||
|
||||
:::
|
||||
|
||||
:::info
|
||||
|
||||
Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-content-pages.md) for an exhaustive list of options.
|
||||
|
||||
:::
|
||||
|
||||
## Add a React page {#add-a-react-page}
|
||||
|
||||
Create a file `/src/pages/helloReact.js`:
|
||||
|
||||
```jsx title="/src/pages/helloReact.js"
|
||||
import React from 'react';
|
||||
import Layout from '@theme/Layout';
|
||||
|
||||
function Hello() {
|
||||
return (
|
||||
<Layout title="Hello">
|
||||
<div
|
||||
style={{
|
||||
display: 'flex',
|
||||
justifyContent: 'center',
|
||||
alignItems: 'center',
|
||||
height: '50vh',
|
||||
fontSize: '20px',
|
||||
}}>
|
||||
<p>
|
||||
Edit <code>pages/helloReact.js</code> and save to reload.
|
||||
</p>
|
||||
</div>
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
|
||||
export default Hello;
|
||||
```
|
||||
|
||||
Once you save the file, the development server will automatically reload the changes. Now open `http://localhost:3000/helloReact`, you will see the new page you just created.
|
||||
|
||||
Each page doesn't come with any styling. You will need to import the `Layout` component from `@theme/Layout` and wrap your contents within that component if you want the navbar and/or footer to appear.
|
||||
|
||||
:::tip
|
||||
|
||||
You can also create TypeScript pages with the `.tsx` extension (`helloReact.tsx`).
|
||||
|
||||
:::
|
||||
|
||||
## Add a Markdown page {#add-a-markdown-page}
|
||||
|
||||
Create a file `/src/pages/helloMarkdown.md`:
|
||||
|
||||
```mdx title="/src/pages/helloMarkdown.md"
|
||||
---
|
||||
title: my hello page title
|
||||
description: my hello page description
|
||||
hide_table_of_contents: true
|
||||
---
|
||||
|
||||
# Hello
|
||||
|
||||
How are you?
|
||||
```
|
||||
|
||||
In the same way, a page will be created at `http://localhost:3000/helloMarkdown`.
|
||||
|
||||
Markdown pages are less flexible than React pages, because it always uses the theme layout.
|
||||
|
||||
Here's an [example Markdown page](/examples/markdownPageExample).
|
||||
|
||||
:::tip
|
||||
|
||||
You can use the full power of React in Markdown pages too, refer to the [MDX](https://mdxjs.com/) documentation.
|
||||
|
||||
:::
|
||||
|
||||
## Routing {#routing}
|
||||
|
||||
If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:
|
||||
|
||||
- `/src/pages/index.js` → `[baseUrl]`
|
||||
- `/src/pages/foo.js` → `[baseUrl]/foo`
|
||||
- `/src/pages/foo/test.js` → `[baseUrl]/foo/test`
|
||||
- `/src/pages/foo/index.js` → `[baseUrl]/foo/`
|
||||
|
||||
In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:
|
||||
|
||||
- Add a `/src/pages/support.js` file
|
||||
- Create a `/src/pages/support/` directory and a `/src/pages/support/index.js` file.
|
||||
|
||||
The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`). By default, any Markdown or Javascript file starting with `_` will be ignored, and no routes will be created for that file (see the `exclude` option).
|
||||
|
||||
```sh
|
||||
my-website
|
||||
├── src
|
||||
│ └── pages
|
||||
│ ├── styles.module.css
|
||||
│ ├── index.js
|
||||
| ├──_ignored.js
|
||||
│ └── support
|
||||
│ ├── index.js
|
||||
│ └── styles.module.css
|
||||
.
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. If you want to create reusable components into that directory, use the `exclude` option (by default, files prefixed with `_`, test files(`.test.js`) and files in `__tests__` directory are not turned into pages).
|
||||
|
||||
:::
|
||||
|
||||
## Using React {#using-react}
|
||||
|
||||
React is used as the UI library to create pages. Every page component should export a React component, and you can leverage on the expressiveness of React to build rich and interactive content.
|
||||
|
||||
## Duplicate Routes {#duplicate-routes}
|
||||
|
||||
You may accidentally create multiple pages that are meant to be accessed on the same route. When this happens, Docusaurus will warn you about duplicate routes when you run `yarn start` or `yarn build`, but the site will still be built successfully. The page that was created last will be accessible, but it will override other conflicting pages. To resolve this issue, you should modify or remove any conflicting routes.
|
||||
|
|
@ -0,0 +1,119 @@
|
|||
---
|
||||
id: create-doc
|
||||
title: Create a doc
|
||||
description: Create a Markdown Document
|
||||
slug: /create-doc
|
||||
---
|
||||
|
||||
Create a Markdown file, `greeting.md`, and place it under the `docs` directory.
|
||||
|
||||
```bash
|
||||
website # root directory of your site
|
||||
├── docs
|
||||
│ └── greeting.md
|
||||
├── src
|
||||
│ └── pages
|
||||
├── docusaurus.config.js
|
||||
├── ...
|
||||
```
|
||||
|
||||
At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
|
||||
|
||||
```yml
|
||||
---
|
||||
id: greeting
|
||||
title: Hello
|
||||
---
|
||||
|
||||
## Hello from Docusaurus
|
||||
|
||||
Are you ready to create the documentation site for your open source project?
|
||||
|
||||
### Headers
|
||||
|
||||
will show up on the table of contents on the upper right
|
||||
|
||||
So that your users will know what this page is all about without scrolling down or even without reading too much.
|
||||
|
||||
### Only h2 and h3 will be in the toc by default.
|
||||
|
||||
You can configure the TOC heading levels either per-document or in the theme configuration.
|
||||
|
||||
The headers are well-spaced so that the hierarchy is clear.
|
||||
|
||||
- lists will help you
|
||||
- present the key points
|
||||
- that you want your users to remember
|
||||
- and you may nest them
|
||||
- multiple times
|
||||
|
||||
### Custom id headers {#custom-id}
|
||||
|
||||
With `{#custom-id}` syntax you can set your own header id.
|
||||
```
|
||||
|
||||
This will render in the browser as follows:
|
||||
|
||||
```mdx-code-block
|
||||
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?
|
||||
|
||||
<h3>Headers</h3>
|
||||
|
||||
will show up on the table of contents on the upper right
|
||||
|
||||
So that your users will know what this page is all about without scrolling down or even without reading too much.
|
||||
|
||||
<h3>Only h2 and h3 will be in the toc by default.</h3>
|
||||
|
||||
You can configure the TOC heading levels either per-document or in the theme configuration.
|
||||
|
||||
The headers are well-spaced so that the hierarchy is clear.
|
||||
|
||||
- lists will help you
|
||||
- present the key points
|
||||
- that you want your users to remember
|
||||
- and you may nest them
|
||||
- multiple times
|
||||
|
||||
<h3 id="custom-id">Custom id headers</h3>
|
||||
|
||||
With <code>{#custom-id}</code> syntax you can set your own header id.
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default.
|
||||
|
||||
Read more about [importing partial pages](../markdown-features/markdown-features-react.mdx#importing-markdown).
|
||||
|
||||
:::
|
||||
|
||||
## Doc tags {#doc-tags}
|
||||
|
||||
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar.md). Tags are passed in the front matter as a list of labels:
|
||||
|
||||
```yml "your-doc-page.md"
|
||||
---
|
||||
id: doc-with-tags
|
||||
title: A doc with tags
|
||||
tags:
|
||||
- Demo
|
||||
- Getting started
|
||||
---
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Tags can also be declared with `tags: [Demo, Getting started]`.
|
||||
|
||||
Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,159 @@
|
|||
---
|
||||
id: introduction
|
||||
title: Docs Introduction
|
||||
sidebar_label: Introduction
|
||||
slug: /docs-introduction
|
||||
---
|
||||
|
||||
The docs feature provides users with a way to organize Markdown files in a hierarchical format.
|
||||
|
||||
:::info
|
||||
|
||||
Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.md) for an exhaustive list of options.
|
||||
|
||||
:::
|
||||
|
||||
## Document ID {#document-id}
|
||||
|
||||
Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
|
||||
|
||||
For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.
|
||||
|
||||
```bash
|
||||
website # Root directory of your site
|
||||
└── docs
|
||||
├── greeting.md
|
||||
└── guide
|
||||
└── hello.md
|
||||
```
|
||||
|
||||
However, the **last part** of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
|
||||
|
||||
```yml
|
||||
---
|
||||
id: part1
|
||||
---
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`).
|
||||
|
||||
```yml
|
||||
---
|
||||
id: part1
|
||||
slug: part1.html
|
||||
---
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
It is possible to use:
|
||||
|
||||
- absolute slugs: `slug: /mySlug`, `slug: /`...
|
||||
- relative slugs: `slug: mySlug`, `slug: ./../mySlug`...
|
||||
|
||||
:::
|
||||
|
||||
## Home page docs {#home-page-docs}
|
||||
|
||||
If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug frontmatter:
|
||||
|
||||
```yml
|
||||
---
|
||||
id: my-home-doc
|
||||
slug: /
|
||||
---
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
## Docs-only mode {#docs-only-mode}
|
||||
|
||||
A freshly initialized Docusaurus site has the following structure:
|
||||
|
||||
```
|
||||
example.com/ -> generated from `src/pages/index.js`
|
||||
|
||||
example.com/docs/intro -> generated from `docs/intro.md`
|
||||
example.com/docs/tutorial-basics/... -> generated from `docs/tutorial-basics/...`
|
||||
...
|
||||
|
||||
example.com/blog/2021/08/26/welcome -> generated from `blog/2021-08-26-welcome/index.md`
|
||||
example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-mdx-blog-post.mdx`
|
||||
...
|
||||
```
|
||||
|
||||
All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting it at the root?
|
||||
|
||||
Assume that you have the following in your configuration:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
/* docs plugin options */
|
||||
},
|
||||
blog: {
|
||||
/* blog plugin options */
|
||||
},
|
||||
// ...
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
To enter docs-only mode, change it to like this:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// highlight-next-line
|
||||
routeBasePath: '/', // Serve the docs at the site's root
|
||||
/* other docs plugin options */
|
||||
},
|
||||
// highlight-next-line
|
||||
blog: false, // Optional: disable the blog plugin
|
||||
// ...
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Note that you **don't necessarily have to give up on using blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute.
|
||||
|
||||
Don't forget to put some page at the root (`https://example.com/`) through adding the front matter:
|
||||
|
||||
```yml title="docs/intro.md"
|
||||
---
|
||||
# highlight-next-line
|
||||
slug: /
|
||||
---
|
||||
This page will be the home page when users visit https://example.com/.
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
If you added `slug: /` to a doc to make it the homepage, you should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
|
||||
|
||||
:::
|
||||
|
||||
Now, the site's structure will be like the following:
|
||||
|
||||
```
|
||||
example.com/ -> generated from `docs/intro.md`
|
||||
example.com/tutorial-basics/... -> generated from `docs/tutorial-basics/...`
|
||||
...
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
id: markdown-features
|
||||
title: Docs Markdown Features
|
||||
description: Docusaurus Markdown features that are specific to the docs plugin
|
||||
slug: /docs-markdown-features
|
||||
---
|
||||
|
||||
Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx), and have a few additional docs-specific Markdown features.
|
||||
|
||||
## Markdown frontmatter {#markdown-frontmatter}
|
||||
|
||||
Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
|
||||
|
||||
## Referencing other documents {#referencing-other-documents}
|
||||
|
||||
If you want to reference another document file, you could use the relative path of the document you want to link to.
|
||||
|
||||
Docusaurus will convert the file path to be the final document url path (and remove the `.md` extension).
|
||||
|
||||
For example, if you are in `folder/doc1.md` and you want to reference `folder/doc2.md`, `folder/subfolder/doc3.md` and `otherFolder/doc4.md`:
|
||||
|
||||
```md
|
||||
I am referencing a [document](doc2.md).
|
||||
|
||||
Reference to another [document in a subfolder](subfolder/doc3.md).
|
||||
|
||||
[Relative document](../otherFolder/doc4.md) referencing works as well.
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
It is better to use relative file paths links instead of relative links:
|
||||
|
||||
- links will keep working on the GitHub interface
|
||||
- you can customize the document slugs without having to update all the links
|
||||
- a versioned doc will link to another doc of the exact same version
|
||||
- relative links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailing-slash)
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,212 @@
|
|||
---
|
||||
id: multi-instance
|
||||
title: Docs Multi-instance
|
||||
description: Use multiple docs plugin instances on a single Docusaurus site.
|
||||
slug: /docs-multi-instance
|
||||
---
|
||||
|
||||
The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../using-plugins.md#multi-instance-plugins-and-plugin-ids).
|
||||
|
||||
:::note
|
||||
|
||||
This feature is only useful for [versioned documentations](./versioning.md). It is recommended to be familiar with docs versioning before reading this page.
|
||||
|
||||
:::
|
||||
|
||||
## Use-cases {#use-cases}
|
||||
|
||||
Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more).
|
||||
|
||||
These documentations may even have different versioning/release lifecycles.
|
||||
|
||||
### Mobile SDKs documentation {#mobile-sdks-documentation}
|
||||
|
||||
If you build a cross-platform mobile SDK, you may have 2 documentations:
|
||||
|
||||
- Android SDK documentation (`v1.0`, `v1.1`)
|
||||
- iOS SDK documentation (`v1.0`, `v2.0`)
|
||||
|
||||
In such case, you can use a distinct docs plugin instance per mobile SDK documentation.
|
||||
|
||||
:::caution
|
||||
|
||||
If each documentation instance is very large, you should rather create 2 distinct Docusaurus sites.
|
||||
|
||||
If someone edits the iOS documentation, is it really useful to rebuild everything, including the whole Android documentation that did not change?
|
||||
|
||||
:::
|
||||
|
||||
### Versioned and unversioned doc {#versioned-and-unversioned-doc}
|
||||
|
||||
Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them.
|
||||
|
||||
We use this pattern on the Docusaurus website itself:
|
||||
|
||||
- The [/docs/\*](/docs) section is versioned
|
||||
- The [/community/\*](/community/support) section is unversioned
|
||||
|
||||
## Setup {#setup}
|
||||
|
||||
Suppose you have 2 documentations:
|
||||
|
||||
- Product: some versioned doc about your product
|
||||
- Community: some unversioned doc about the community around your product
|
||||
|
||||
In this case, you should use the same plugin twice in your site configuration.
|
||||
|
||||
:::caution
|
||||
|
||||
`@docusaurus/preset-classic` already includes a docs plugin instance for you!
|
||||
|
||||
:::
|
||||
|
||||
When using the preset:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// highlight-start
|
||||
// id: 'product', // omitted => default instance
|
||||
// highlight-end
|
||||
path: 'product',
|
||||
routeBasePath: 'product',
|
||||
sidebarPath: require.resolve('./sidebarsProduct.js'),
|
||||
// ... other options
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
// highlight-start
|
||||
id: 'community',
|
||||
// highlight-end
|
||||
path: 'community',
|
||||
routeBasePath: 'community',
|
||||
sidebarPath: require.resolve('./sidebarsCommunity.js'),
|
||||
// ... other options
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
When not using the preset:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
// highlight-start
|
||||
// id: 'product', // omitted => default instance
|
||||
// highlight-end
|
||||
path: 'product',
|
||||
routeBasePath: 'product',
|
||||
sidebarPath: require.resolve('./sidebarsProduct.js'),
|
||||
// ... other options
|
||||
},
|
||||
],
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
// highlight-start
|
||||
id: 'community',
|
||||
// highlight-end
|
||||
path: 'community',
|
||||
routeBasePath: 'community',
|
||||
sidebarPath: require.resolve('./sidebarsCommunity.js'),
|
||||
// ... other options
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Don't forget to assign a unique `id` attribute to plugin instances.
|
||||
|
||||
:::note
|
||||
|
||||
We consider that the `product` instance is the most important one, and make it the "default" instance by not assigning any id.
|
||||
|
||||
:::
|
||||
|
||||
## Versioned paths {#versioned-paths}
|
||||
|
||||
Each plugin instance will store versioned docs in a distinct folder.
|
||||
|
||||
The default plugin instance will use these paths:
|
||||
|
||||
- `website/versions.json`
|
||||
- `website/versioned_docs`
|
||||
- `website/versioned_sidebars`
|
||||
|
||||
The other plugin instances (with an `id` attribute) will use these paths:
|
||||
|
||||
- `website/[pluginId]_versions.json`
|
||||
- `website/[pluginId]_versioned_docs`
|
||||
- `website/[pluginId]_versioned_sidebars`
|
||||
|
||||
:::tip
|
||||
|
||||
You can omit the `id` attribute (defaults to `default`) for one of the docs plugin instances.
|
||||
|
||||
The instance paths will be simpler, and retro-compatible with a single-instance setup.
|
||||
|
||||
:::
|
||||
|
||||
## Tagging new versions {#tagging-new-versions}
|
||||
|
||||
Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run docusaurus -- --help
|
||||
```
|
||||
|
||||
To version the product/default docs plugin instance:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run docusaurus docs:version 1.0.0
|
||||
```
|
||||
|
||||
To version the non-default/community docs plugin instance:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run docusaurus docs:version:community 1.0.0
|
||||
```
|
||||
|
||||
## Docs navbar items {#docs-navbar-items}
|
||||
|
||||
Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute.
|
||||
|
||||
For example, if you want to have one version dropdown for each mobile SDK (iOS and Android), you could do:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
items: [
|
||||
{
|
||||
type: 'docsVersionDropdown',
|
||||
// highlight-start
|
||||
docsPluginId: 'ios',
|
||||
// highlight-end
|
||||
},
|
||||
{
|
||||
type: 'docsVersionDropdown',
|
||||
// highlight-start
|
||||
docsPluginId: 'android',
|
||||
// highlight-end
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
1052
website/versioned_docs/version-2.0.0-beta.14/guides/docs/sidebar.md
Normal file
1052
website/versioned_docs/version-2.0.0-beta.14/guides/docs/sidebar.md
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -0,0 +1,216 @@
|
|||
---
|
||||
id: versioning
|
||||
title: Versioning
|
||||
slug: /versioning
|
||||
---
|
||||
|
||||
You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
|
||||
|
||||
:::caution
|
||||
|
||||
Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!
|
||||
|
||||
:::
|
||||
|
||||
Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is **best suited for websites with high-traffic and rapid changes to documentation between versions**. If your documentation rarely changes, don't add versioning to your documentation.
|
||||
|
||||
To better understand how versioning works and see if it suits your needs, you can read on below.
|
||||
|
||||
## Directory structure {#directory-structure}
|
||||
|
||||
```shell
|
||||
website
|
||||
├── sidebars.json # sidebar for the current docs version
|
||||
├── docs # docs directory for the current docs version
|
||||
│ ├── foo
|
||||
│ │ └── bar.md # https://mysite.com/docs/next/foo/bar
|
||||
│ └── hello.md # https://mysite.com/docs/next/hello
|
||||
├── versions.json # file to indicate what versions are available
|
||||
├── versioned_docs
|
||||
│ ├── version-1.1.0
|
||||
│ │ ├── foo
|
||||
│ │ │ └── bar.md # https://mysite.com/docs/foo/bar
|
||||
│ │ └── hello.md
|
||||
│ └── version-1.0.0
|
||||
│ ├── foo
|
||||
│ │ └── bar.md # https://mysite.com/docs/1.0.0/foo/bar
|
||||
│ └── hello.md
|
||||
├── versioned_sidebars
|
||||
│ ├── version-1.1.0-sidebars.json
|
||||
│ └── version-1.0.0-sidebars.json
|
||||
├── docusaurus.config.js
|
||||
└── package.json
|
||||
```
|
||||
|
||||
The table below explains how a versioned file maps to its version and the generated URL.
|
||||
|
||||
| Path | Version | URL |
|
||||
| --------------------------------------- | -------------- | ----------------- |
|
||||
| `versioned_docs/version-1.0.0/hello.md` | 1.0.0 | /docs/1.0.0/hello |
|
||||
| `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello |
|
||||
| `docs/hello.md` | current | /docs/next/hello |
|
||||
|
||||
:::tip
|
||||
|
||||
The files in the `docs` directory belong to the `current` docs version.
|
||||
|
||||
By default, the `current` docs version is labelled as `Next` and hosted under `/docs/next/*`, but is entirely configurable to fit your project's release lifecycle.
|
||||
|
||||
:::
|
||||
|
||||
### Tagging a new version {#tagging-a-new-version}
|
||||
|
||||
1. First, make sure the current docs version (the `docs` directory) is ready to be frozen.
|
||||
1. Enter a new version number.
|
||||
|
||||
```bash npm2yarn
|
||||
npm run docusaurus docs:version 1.1.0
|
||||
```
|
||||
|
||||
When tagging a new version, the document versioning mechanism will:
|
||||
|
||||
- Copy the full `docs/` folder contents into a new `versioned_docs/version-[versionName]/` folder.
|
||||
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-[versionName]-sidebars.json`.
|
||||
- Append the new version number to `versions.json`.
|
||||
|
||||
## Docs {#docs}
|
||||
|
||||
### Creating new docs {#creating-new-docs}
|
||||
|
||||
1. Place the new file into the corresponding version folder.
|
||||
1. Include the reference for the new file into the corresponding sidebar file, according to version number.
|
||||
|
||||
**Current version docs**
|
||||
|
||||
```shell
|
||||
# The new file.
|
||||
docs/new.md
|
||||
|
||||
# Edit the corresponding sidebar file.
|
||||
sidebar.js
|
||||
```
|
||||
|
||||
**Older version docs**
|
||||
|
||||
```shell
|
||||
# The new file.
|
||||
versioned_docs/version-1.0.0/new.md
|
||||
|
||||
# Edit the corresponding sidebar file.
|
||||
versioned_sidebars/version-1.0.0-sidebars.json
|
||||
```
|
||||
|
||||
### Linking docs {#linking-docs}
|
||||
|
||||
- Remember to include the `.md` extension.
|
||||
- Files will be linked to correct corresponding version.
|
||||
- Relative paths work as well.
|
||||
|
||||
```md
|
||||
The [@hello](hello.md#paginate) document is great!
|
||||
|
||||
See the [Tutorial](../getting-started/tutorial.md) for more info.
|
||||
```
|
||||
|
||||
## Versions {#versions}
|
||||
|
||||
Each directory in `versioned_docs/` will represent a documentation version.
|
||||
|
||||
### Updating an existing version {#updating-an-existing-version}
|
||||
|
||||
You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published.
|
||||
|
||||
1. Edit any file.
|
||||
1. Commit and push changes.
|
||||
1. It will be published to the version.
|
||||
|
||||
Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
|
||||
|
||||
### Deleting an existing version {#deleting-an-existing-version}
|
||||
|
||||
You can delete/remove versions as well.
|
||||
|
||||
1. Remove the version from `versions.json`.
|
||||
|
||||
Example:
|
||||
|
||||
```diff {4}
|
||||
[
|
||||
"2.0.0",
|
||||
"1.9.0",
|
||||
- "1.8.0"
|
||||
]
|
||||
```
|
||||
|
||||
2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`.
|
||||
3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`.
|
||||
|
||||
## Recommended practices {#recommended-practices}
|
||||
|
||||
### Figure out the behavior for the "current" version {#figure-out-the-behavior-for-the-current-version}
|
||||
|
||||
The "current" version is the version name for the `./docs` folder.
|
||||
|
||||
There are different ways to manage versioning, but two very common patterns are:
|
||||
|
||||
- You release v1, and start immediately working on v2 (including its docs)
|
||||
- You release v1, and will maintain it for some time before thinking about v2.
|
||||
|
||||
Docusaurus defaults work great for the first usecase.
|
||||
|
||||
**For the 2nd usecase**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider using the following configuration instead:
|
||||
|
||||
```json
|
||||
{
|
||||
"lastVersion": "current",
|
||||
"versions": {
|
||||
"current": {
|
||||
"label": "1.0.0",
|
||||
"path": "1.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, and `1.0.0` will become the default version we link to in the navbar dropdown, and you will only need to maintain a single `./docs` folder.
|
||||
|
||||
See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details.
|
||||
|
||||
### Version your documentation only when needed {#version-your-documentation-only-when-needed}
|
||||
|
||||
For example, you are building a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.
|
||||
|
||||
Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.
|
||||
|
||||
### Keep the number of versions small {#keep-the-number-of-versions-small}
|
||||
|
||||
As a good rule of thumb, try to keep the number of your versions below 10. **It is very likely** that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `24.9`, and only maintains several latest documentation versions with the lowest being `22.X`. Keep it small 😊
|
||||
|
||||
### Use absolute import within the docs {#use-absolute-import-within-the-docs}
|
||||
|
||||
Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by Docusaurus, that points to the `website` directory. Example:
|
||||
|
||||
```diff
|
||||
- import Foo from '../src/components/Foo';
|
||||
+ import Foo from '@site/src/components/Foo';
|
||||
```
|
||||
|
||||
### Global or versioned colocated assets {#global-or-versioned-colocated-assets}
|
||||
|
||||
You should decide if assets like images and files are per version or shared between versions
|
||||
|
||||
If your assets should be versioned, put them in the docs version, and use relative paths:
|
||||
|
||||
```md
|
||||
|
||||
|
||||
[download this file](./file.pdf)
|
||||
```
|
||||
|
||||
If your assets are global, put them in `/static` and use absolute paths:
|
||||
|
||||
```md
|
||||
|
||||
|
||||
[download this file](/file.pdf)
|
||||
```
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
<span>Hello {props.name}</span>
|
||||
|
||||
This is text some content from `_markdown-partial-example.md`.
|
||||
|
|
@ -0,0 +1,185 @@
|
|||
---
|
||||
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`](#).
|
||||
|
||||
:::
|
||||
|
||||
## Usage with Prettier {#usage-with-prettier}
|
||||
|
||||
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might autoformat your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
```md
|
||||
<!-- Prettier doesn't change this -->
|
||||
::: note
|
||||
|
||||
Hello world
|
||||
|
||||
:::
|
||||
|
||||
<!-- Prettier changes this -->
|
||||
::: note
|
||||
Hello world
|
||||
:::
|
||||
|
||||
<!-- to this -->
|
||||
::: note Hello world:::
|
||||
```
|
||||
|
||||
## 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!
|
||||
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">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
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
```
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
|
||||
```mdx-code-block
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">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>
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Usage in JSX
|
||||
|
||||
Outside of Markdown, you can use the `@theme/Admonitions` component to get the same output.
|
||||
|
||||
```jsx title="MyReactPage.jsx"
|
||||
import Admonition from '@theme/Admonitions';
|
||||
|
||||
export default function MyReactPage() {
|
||||
return (
|
||||
<div>
|
||||
<Admonition type="info">
|
||||
<p>Some information</p>
|
||||
</Admonition>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
The types that are accepted are the same as above: `note`, `tip`, `danger`, `info`, `caution`. Optionally, you can specify an icon by passing a JSX element or a string, or a title:
|
||||
|
||||
```jsx title="MyReactPage.jsx"
|
||||
<Admonition type="tip" icon="💡" title="Did you know...">
|
||||
<p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</p>
|
||||
</Admonition>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import Admonition from '@theme/Admonition';
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
|
||||
<BrowserWindow>
|
||||
<Admonition type="tip" icon="💡" title="Did you know...">
|
||||
<p>Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project.</p>
|
||||
</Admonition>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
|
@ -0,0 +1,158 @@
|
|||
---
|
||||
id: assets
|
||||
title: Assets
|
||||
description: Handling assets in Docusaurus Markdown
|
||||
slug: /markdown-features/assets
|
||||
---
|
||||
|
||||
Sometimes you want to link to assets (e.g. docx files, images...) directly from Markdown files, and it is convenient to co-locate the asset next to the Markdown file using it.
|
||||
|
||||
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.docx
|
||||
```
|
||||
|
||||
## 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.docx').default}>
|
||||
Download this docx
|
||||
</a>
|
||||
|
||||
or
|
||||
|
||||
[Download this docx using Markdown](./assets/docusaurus-asset-example.docx)
|
||||
```
|
||||
|
||||
<a
|
||||
target="_blank"
|
||||
href={require('../../assets/docusaurus-asset-example.docx').default}>
|
||||
Download this docx
|
||||
</a>
|
||||
|
||||
[Download this docx using Markdown](../../assets/docusaurus-asset-example.docx)
|
||||
|
||||
## 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 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'),
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
## Static assets {#static-assets}
|
||||
|
||||
If a Markdown link or image has an absolute path, the path will be seen as a file path and will be resolved from the static directories. For example, if you have configured [static directories](../../static-assets.md) to be `['public', 'static']`, then for the following image:
|
||||
|
||||
```md title="my-doc.md"
|
||||
|
||||
```
|
||||
|
||||
Docusaurus will try to look for it in both `static/img/docusaurus.png` and `public/img/docusaurus.png`. The link will then be converted to a `require` call instead of staying as a URL. This is desirable in two regards:
|
||||
|
||||
1. You don't have to worry about base URL, which Docusaurus will take care of when serving the asset;
|
||||
2. The image enters Webpack's build pipeline and its name will be appended by a hash, which enables browsers to aggressively cache the image and improves your site's performance.
|
||||
|
|
@ -0,0 +1,491 @@
|
|||
---
|
||||
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>
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```js
|
||||
function helloWorld() {
|
||||
console.log('Hello, world!');
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="py" label="Python">
|
||||
|
||||
```py
|
||||
def hello_world():
|
||||
print 'Hello, world!'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="java" label="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>
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```js
|
||||
function helloWorld() {
|
||||
console.log('Hello, world!');
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="py" label="Python">
|
||||
|
||||
```py
|
||||
def hello_world():
|
||||
print 'Hello, world!'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
class HelloWorld {
|
||||
public static void main(String args[]) {
|
||||
System.out.println("Hello, World");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
````
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
id: head-metadata
|
||||
title: Head Metadata
|
||||
description: Declaring page-specific head metadata through MDX
|
||||
slug: /markdown-features/head-metadata
|
||||
---
|
||||
|
||||
# Head Metadata
|
||||
|
||||
Docusaurus automatically sets useful page metadata in `<html>`, `<head>` and `<body>` for you.
|
||||
|
||||
It is possible to add extra metadata (or override existing ones) by using the `<head>` tag in Markdown files:
|
||||
|
||||
```md title="markdown-features-head-metadata.mdx"
|
||||
---
|
||||
id: head-metadata
|
||||
title: Head Metadata
|
||||
---
|
||||
|
||||
<!-- highlight-start -->
|
||||
<head>
|
||||
<html className="some-extra-html-class" />
|
||||
<body className="other-extra-body-class" />
|
||||
<title>Head Metadata customized title!</title>
|
||||
<meta charSet="utf-8" />
|
||||
<meta name="twitter:card" content="summary" />
|
||||
<link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadata" />
|
||||
</head>
|
||||
<!-- highlight-end -->
|
||||
|
||||
# Head Metadata
|
||||
|
||||
My text
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<head>
|
||||
<html className="some-extra-html-class" />
|
||||
<body className="other-extra-body-class" />
|
||||
<title>Head Metadata customized title!</title>
|
||||
<meta charSet="utf-8" />
|
||||
<meta name="twitter:card" content="summary" />
|
||||
<link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadata" />
|
||||
</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 metadata have been affected.
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
**You don't always need this for typical SEO needs.** Content plugins (e.g. docs and blog) provide front matter options like `description`, `keywords`, and `image`, which will be automatically applied to both `description` and `og:description`, while you would have to manually declare two metadata tags when using the `<head>` tag.
|
||||
|
||||
:::
|
||||
|
||||
:::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,124 @@
|
|||
---
|
||||
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 contains all the headings of a MDX document.
|
||||
|
||||
By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel`.
|
||||
|
||||
```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[];
|
||||
level: number;
|
||||
};
|
||||
```
|
||||
|
||||
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,198 @@
|
|||
---
|
||||
id: plugins
|
||||
title: MDX Plugins
|
||||
description: Using MDX plugins to expand Docusaurus Markdown functionalities
|
||||
slug: /markdown-features/plugins
|
||||
---
|
||||
|
||||
Sometimes, you may want to extend or tweak your Markdown syntax. For example:
|
||||
|
||||
- How do I embed youtube videos using the image syntax (``)?
|
||||
- How do I style links that are on its own line differently, e.g., like a social card?
|
||||
- How do I make every page start with a copyright notice?
|
||||
|
||||
And the answer is: create an MDX plugin! MDX has a built-in [plugin system](https://mdxjs.com/advanced/plugins/) that can be used to customize how the Markdown files will be parsed and transformed to JSX. There are three typical use-cases of MDX plugins:
|
||||
|
||||
- Using existing [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) or [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins);
|
||||
- Creating remark/rehype plugins to tranform the elements generated by existing MDX syntax;
|
||||
- Creating remark/rehype plugins to introduce new syntaxes to MDX.
|
||||
|
||||
If you play with the [MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground), you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms:
|
||||
|
||||
- **[Remark](https://github.com/remarkjs/remark/)**: processes the Markdown AST.
|
||||
- **[Rehype](https://github.com/rehypejs/rehype/)**: processes the Hypertext AST.
|
||||
|
||||
:::tip
|
||||
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project. The [admonition](./markdown-features-admonitions.mdx) syntax that we offer is also generated by a [Remark plugin](https://github.com/elviswolcott/remark-admonitions), and you could do the same for your own use-case.
|
||||
|
||||
:::
|
||||
|
||||
## Default plugins {#default-plugins}
|
||||
|
||||
Docusaurus injects [some default Remark plugins](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-mdx-loader/src/remark) during Markdown processing. These plugins would:
|
||||
|
||||
- Generate the table of contents;
|
||||
- Add anchor links to each heading;
|
||||
- Transform images and links to `require()` calls.
|
||||
- …
|
||||
|
||||
These are all typical use-cases of Remark plugins, which can also be a source of inspiration if you want to implement your own plugin.
|
||||
|
||||
## Installing plugins {#installing-plugins}
|
||||
|
||||
An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Take the [math plugins](./markdown-features-math-equations.mdx) as example.
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save remark-math@3 rehype-katex@4
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
There's recently a trend in the Remark/Rehype ecosystem to migrate to ES Modules, which Docusaurus doesn't support yet. Please make sure your installed plugin version is CommonJS-compatible before we officially support ESM.
|
||||
|
||||
:::
|
||||
|
||||
<details>
|
||||
<summary>How are <code>remark-math</code> and <code>rehype-katex</code> different?</summary>
|
||||
|
||||
In case you are wondering how Remark and Rehype are different, here is a good example. `remark-math` operates on the Markdown AST, where it sees text like `$...$`, and all it does is transforms that to the JSX `<span class="math math-inline">...</span>` without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap $\KaTeX$ out with other math renderers, like MathJax (with [`rehype-mathjax`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax)), just by replacing the Rehype plugin.
|
||||
|
||||
Next, the `rehype-katex` operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with `math` class, and uses $\KaTeX$ to parse and render the content to actual HTML.
|
||||
|
||||
</details>
|
||||
|
||||
Next, add them to the plugin options through plugin or preset config in `docusaurus.config.js`:
|
||||
|
||||
```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: {
|
||||
// highlight-start
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Configuring plugins {#configuring-plugins}
|
||||
|
||||
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like this:
|
||||
|
||||
```jsx title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [
|
||||
// highlight-next-line
|
||||
[katex, {strict: false}],
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
You should check your plugin's documentation for options it supports.
|
||||
|
||||
## Creating new rehype/remark plugins
|
||||
|
||||
If there isn't an existing package that satisfies your customization need, you can create your own MDX plugin.
|
||||
|
||||
:::note
|
||||
|
||||
The writeup below is **not** meant to be a comprehensive guide to creating a plugin, but just an illustration of how to make it work with Docusaurus. Visit the [Remark](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#creating-plugins) or [Rehype](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#creating-plugins) documentation for a more in-depth explanation of how they work.
|
||||
|
||||
:::
|
||||
|
||||
For example, let's make a plugin that visits every `h2` heading and adds a `Section X. ` prefix. First, create your plugin source file anywhere—you can even publish it as a separate NPM package and install it like explained above. We would put ours at `src/remark/section-prefix.js`. A remark/rehype plugin is just a function that receives the `options` and returns a `transformer` which operates on the AST.
|
||||
|
||||
```js "src/remark/section-prefix.js"
|
||||
const visit = require('unist-util-visit');
|
||||
|
||||
const plugin = (options) => {
|
||||
const transformer = async (ast) => {
|
||||
let number = 1;
|
||||
visit(ast, 'heading', (node) => {
|
||||
if (node.depth === 2 && node.children.length > 0) {
|
||||
if (node.children[0].type === 'text') {
|
||||
node.children[0].value = `Section ${number}. ${node.children[0].value}`;
|
||||
} else {
|
||||
node.children.unshift({
|
||||
type: 'text',
|
||||
value: `Section ${number}. `,
|
||||
});
|
||||
}
|
||||
number++;
|
||||
}
|
||||
});
|
||||
};
|
||||
return transformer;
|
||||
};
|
||||
|
||||
module.exports = plugin;
|
||||
```
|
||||
|
||||
You can now import your plugin in `docusaurus.config.js` and use it just like an installed plugin!
|
||||
|
||||
```jsx title="docusaurus.config.js"
|
||||
// highlight-next-line
|
||||
const sectionPrefix = require('./src/remark/section-prefix');
|
||||
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// highlight-next-line
|
||||
remarkPlugins: [sectionPrefix],
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
The default plugins of Docusaurus would operate before the custom remark plugins, and that means the images or links have been converted to JSX with `require()` calls already. For example, in the example above, the table of contents generated is still the same even when all `h2` headings are now prefixed by `Section X.`, because the TOC-generating plugin is called before our custom plugin. If you need to process the MDAST before the default plugins do, use the `beforeDefaultRemarkPlugins` and `beforeDefaultRehypePlugins`.
|
||||
|
||||
```jsx title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// highlight-next-line
|
||||
beforeDefaultRemarkPlugins: [sectionPrefix],
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
This would make the table of contents generated contain the `Section X.` prefix as well.
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,218 @@
|
|||
---
|
||||
id: react
|
||||
title: MDX and React
|
||||
description: Using the power of React in Docusaurus Markdown documents, thanks to MDX
|
||||
slug: /markdown-features/react
|
||||
---
|
||||
|
||||
# MDX and 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 v1](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://mdx-git-renovate-babel-monorepo-mdx.vercel.app/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)).
|
||||
|
||||
:::
|
||||
|
||||
## Available exports
|
||||
|
||||
Within the MDX page, the following variables are available as globals:
|
||||
|
||||
- `frontMatter`: the front matter as a record of string keys and values;
|
||||
- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-inline-toc.mdx) for a more concrete use-case.
|
||||
- `contentTitle`: the Markdown title, which is the first `h1` heading in the Markdown text. It's `undefined` if there isn't one (e.g. title specified in the front matter).
|
||||
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
||||
The table of contents for this page, serialized:
|
||||
|
||||
<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>
|
||||
|
||||
The front matter of this page:
|
||||
|
||||
<ul>
|
||||
{Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
|
||||
</ul>
|
||||
|
||||
<p>The title of this page is: <b>{contentTitle}</b></p>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
<BrowserWindow>
|
||||
|
||||
The table of contents for this page, serialized:
|
||||
|
||||
<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>
|
||||
|
||||
The front matter of this page:
|
||||
|
||||
<ul>
|
||||
{Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
|
||||
</ul>
|
||||
|
||||
<p>The title of this page is: <b>{contentTitle}</b></p>
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
.red {
|
||||
color: red;
|
||||
}
|
||||
.red[aria-selected="true"] {
|
||||
border-bottom-color: red;
|
||||
}
|
||||
|
||||
.orange {
|
||||
color: orange;
|
||||
}
|
||||
.orange[aria-selected="true"] {
|
||||
border-bottom-color: orange;
|
||||
}
|
||||
|
||||
.yellow {
|
||||
color: yellow;
|
||||
}
|
||||
.yellow[aria-selected="true"] {
|
||||
border-bottom-color: yellow;
|
||||
}
|
||||
|
|
@ -0,0 +1,322 @@
|
|||
---
|
||||
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';
|
||||
import styles from './markdown-features-tabs-styles.module.css';
|
||||
```
|
||||
|
||||
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';
|
||||
|
||||
<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>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">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" default>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 />`.
|
||||
|
||||
:::
|
||||
|
||||
## Displaying a default tab
|
||||
|
||||
The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding `default` to one of the tab items. You can also set the `defaultValue` prop of the `Tabs` component to the label value of your choice. For example, in the example above, either setting `default` for the `value="apple"` tab or setting `defaultValue="apple"` for the tabs forces the "Apple" tab to be open by default.
|
||||
|
||||
Docusaurus will throw an error if a `defaultValue` is provided for the `Tabs` but it refers to an non-existing value. If you want none of the tabs to be shown by default, use `defaultValue={null}`.
|
||||
|
||||
## 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">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">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">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">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">
|
||||
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">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">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">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">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">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
|
||||
// highlight-next-line
|
||||
<Tabs className="unique-tabs">
|
||||
<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 className="unique-tabs">
|
||||
<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>
|
||||
```
|
||||
|
||||
### Customizing tab headings
|
||||
|
||||
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```jsx title="some-doc.mdx"
|
||||
import styles from './styles.module.css';
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple" attributes={{className: styles.red}}>
|
||||
This is an apple 🍎
|
||||
</TabItem>
|
||||
<TabItem value="orange" label="Orange" attributes={{className: styles.orange}}>
|
||||
This is an orange 🍊
|
||||
</TabItem>
|
||||
<TabItem value="banana" label="Banana" attributes={{className: styles.yellow}}>
|
||||
This is a banana 🍌
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```css title="styles.module.css"
|
||||
.red {
|
||||
color: red;
|
||||
}
|
||||
.red[aria-selected='true'] {
|
||||
border-bottom-color: red;
|
||||
}
|
||||
|
||||
.orange {
|
||||
color: orange;
|
||||
}
|
||||
.orange[aria-selected='true'] {
|
||||
border-bottom-color: orange;
|
||||
}
|
||||
|
||||
.yellow {
|
||||
color: yellow;
|
||||
}
|
||||
.yellow[aria-selected='true'] {
|
||||
border-bottom-color: yellow;
|
||||
}
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple" attributes={{className: styles.red}}>
|
||||
This is an apple 🍎
|
||||
</TabItem>
|
||||
<TabItem value="orange" label="Orange" attributes={{className: styles.orange}}>
|
||||
This is an orange 🍊
|
||||
</TabItem>
|
||||
<TabItem value="banana" label="Banana" attributes={{className: styles.yellow}}>
|
||||
This is a banana 🍌
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
`className` would be merged with other default class names. You may also use a custom `data-value` field (`{'data-value': 'apple'}`) paired with CSS attribute selectors:
|
||||
|
||||
```css title="styles.module.css"
|
||||
li[role='tab'][data-value='apple'] {
|
||||
color: red;
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
Loading…
Add table
Add a link
Reference in a new issue