mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-20 04:27:04 +02:00
chore(v2): prepare v2.0.0-beta.0 release (#4774)
* beta.0 version docs + changelog * fix config for beta switch * v2.0.0-beta.0
This commit is contained in:
Sébastien Lorber
GitHub
parent
fe6492aa87
commit
7e4d7671c8
103 changed files with 11779 additions and 149 deletions
|
|
@ -0,0 +1,79 @@
|
|||
---
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
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</h3>
|
||||
|
||||
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
|
||||
|
||||
</BrowserWindow>
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
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.
|
||||
|
||||
## 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}
|
||||
|
||||
If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.
|
||||
|
||||
To enable docs-only mode, set the docs plugin `routeBasePath: '/'`, and use the frontmatter `slug: /` on the document that should be the index page ([more infos](#home-page-docs)).
|
||||
|
||||
:::caution
|
||||
|
||||
You should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
|
||||
|
||||
:::
|
||||
|
||||
:::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.md#blog-only-mode).
|
||||
|
||||
:::
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
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 name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
|
||||
|
||||
For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
|
||||
|
||||
```md
|
||||
I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md).
|
||||
|
||||
[Relative document](../doc2.md) referencing works as well.
|
||||
```
|
||||
|
||||
One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
|
||||
|
||||
Another benefit, for versioned docs, is that one versioned doc will link to another doc of the exact same version.
|
||||
|
|
@ -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
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
|
@ -0,0 +1,634 @@
|
|||
---
|
||||
id: sidebar
|
||||
title: Sidebar
|
||||
slug: /sidebar
|
||||
---
|
||||
|
||||
Creating a sidebar is useful to:
|
||||
|
||||
- Group multiple **related documents**
|
||||
- **Display a sidebar** on each of those documents
|
||||
- Provide a **paginated navigation**, with next/previous button
|
||||
|
||||
To use sidebars on your Docusaurus site:
|
||||
|
||||
1. Define a file that exports a [sidebar object](#sidebar-object).
|
||||
1. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// highlight-start
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Default sidebar
|
||||
|
||||
By default, Docusaurus [automatically generates a sidebar](#sidebar-item-autogenerated) for you, by using the filesystem structure of the `docs` folder:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
mySidebar: [
|
||||
{
|
||||
type: 'autogenerated',
|
||||
dirName: '.', // generate sidebar slice from the docs folder (or versioned_docs/<version>)
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
You can also define your sidebars explicitly.
|
||||
|
||||
## Sidebar object {#sidebar-object}
|
||||
|
||||
A sidebar is a **tree of [sidebar items](#understanding-sidebar-items)**.
|
||||
|
||||
```typescript
|
||||
type Sidebar =
|
||||
// Normal syntax
|
||||
| SidebarItem[]
|
||||
|
||||
// Shorthand syntax
|
||||
| Record<
|
||||
string, // category label
|
||||
SidebarItem[] // category items
|
||||
>;
|
||||
```
|
||||
|
||||
A sidebars file can contain **multiple sidebar objects**.
|
||||
|
||||
```typescript
|
||||
type SidebarsFile = Record<
|
||||
string, // sidebar id
|
||||
Sidebar
|
||||
>;
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
mySidebar: [
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Getting Started',
|
||||
items: ['doc1'],
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Docusaurus',
|
||||
items: ['doc2', 'doc3'],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Notice the following:
|
||||
|
||||
- There is a single sidebar `mySidebar`, containing 5 [sidebar items](#understanding-sidebar-items)
|
||||
- `Getting Started` and `Docusaurus` are sidebar categories
|
||||
- `doc1`, `doc2` and `doc3` are sidebar documents
|
||||
|
||||
:::tip
|
||||
|
||||
Use the **shorthand syntax** to express this sidebar more concisely:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
mySidebar: {
|
||||
'Getting started': ['doc1'],
|
||||
Docusaurus: ['doc2', 'doc3'],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Using multiple sidebars {#using-multiple-sidebars}
|
||||
|
||||
You can create a sidebar for each **set of markdown files** that you want to **group together**.
|
||||
|
||||
:::tip
|
||||
|
||||
The Docusaurus site is a good example of using multiple sidebars:
|
||||
|
||||
- [Docs](../../introduction.md)
|
||||
- [API](../../cli.md)
|
||||
|
||||
:::
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
tutorialSidebar: {
|
||||
'Category A': ['doc1', 'doc2'],
|
||||
},
|
||||
apiSidebar: ['doc3', 'doc4'],
|
||||
};
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
The keys `tutorialSidebar` and `apiSidebar` are sidebar **technical ids** and do not matter much.
|
||||
|
||||
:::
|
||||
|
||||
When browsing:
|
||||
|
||||
- `doc1` or `doc2`: the `tutorialSidebar` will be displayed
|
||||
- `doc3` or `doc4`: the `apiSidebar` will be displayed
|
||||
|
||||
A **paginated navigation** link documents inside the same sidebar with **next and previous buttons**.
|
||||
|
||||
## Understanding sidebar items {#understanding-sidebar-items}
|
||||
|
||||
`SidebarItem` is an item defined in a Sidebar tree.
|
||||
|
||||
There are different types of sidebar items:
|
||||
|
||||
- **[Doc](#sidebar-item-doc)**: link to a doc page, assigning it to the sidebar
|
||||
- **[Ref](#sidebar-item-ref)**: link to a doc page, without assigning it to the sidebar
|
||||
- **[Link](#sidebar-item-link)**: link to any internal or external page
|
||||
- **[Category](#sidebar-item-category)**: create a hierarchy of sidebar items
|
||||
- **[Autogenerated](#sidebar-item-autogenerated)**: generate a sidebar slice automatically
|
||||
|
||||
### Doc: link to a doc {#sidebar-item-doc}
|
||||
|
||||
Use the `doc` type to link to a doc page and assign that doc to a sidebar:
|
||||
|
||||
```typescript
|
||||
type SidebarItemDoc =
|
||||
// Normal syntax
|
||||
| {
|
||||
type: 'doc';
|
||||
id: string;
|
||||
label: string; // Sidebar label text
|
||||
}
|
||||
|
||||
// Shorthand syntax
|
||||
| string; // docId shortcut
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
mySidebar: [
|
||||
// Normal syntax:
|
||||
// highlight-start
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'doc1', // document id
|
||||
label: 'Getting started', // sidebar label
|
||||
},
|
||||
// highlight-end
|
||||
|
||||
// Shorthand syntax:
|
||||
// highlight-start
|
||||
'doc2', // document id
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
The `sidebar_label` markdown frontmatter has a higher precedence over the `label` key in `SidebarItemDoc`.
|
||||
|
||||
:::note
|
||||
|
||||
Don't assign the same doc to multiple sidebars: use a [ref](#sidebar-item-ref) instead.
|
||||
|
||||
:::
|
||||
|
||||
### Ref: link to a doc, without sidebar {#sidebar-item-ref}
|
||||
|
||||
Use the `ref` type to link to a doc page without assigning it to a sidebar.
|
||||
|
||||
```typescript
|
||||
type SidebarItemRef = {
|
||||
type: 'ref';
|
||||
id: string;
|
||||
};
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
mySidebar: [
|
||||
{
|
||||
type: 'ref',
|
||||
id: 'doc1', // Document id (string).
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
When browsing `doc1`, Docusaurus **will not display** the `mySidebar` sidebar.
|
||||
|
||||
### Link: link to any page {#sidebar-item-link}
|
||||
|
||||
Use the `link` type to link to any page (internal or external) that is not a doc.
|
||||
|
||||
```typescript
|
||||
type SidebarItemLink = {
|
||||
type: 'link';
|
||||
label: string;
|
||||
href: string;
|
||||
};
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
myLinksSidebar: [
|
||||
// highlight-start
|
||||
// External link
|
||||
{
|
||||
type: 'link',
|
||||
label: 'Facebook', // The link label
|
||||
href: 'https://facebook.com', // The external URL
|
||||
},
|
||||
// highlight-end
|
||||
|
||||
// highlight-start
|
||||
// Internal link
|
||||
{
|
||||
type: 'link',
|
||||
label: 'Home', // The link label
|
||||
href: '/', // The internal path
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### Category: create a hierarchy {#sidebar-item-category}
|
||||
|
||||
Use the `category` type to create a hierarchy of sidebar items.
|
||||
|
||||
```typescript
|
||||
type SidebarItemCategory = {
|
||||
type: 'category';
|
||||
label: string; // Sidebar label text.
|
||||
items: SidebarItem[]; // Array of sidebar items.
|
||||
|
||||
// Category options:
|
||||
collapsed: boolean; // Set the category to be collapsed or open by default
|
||||
};
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
docs: [
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Guides',
|
||||
collapsed: false,
|
||||
items: [
|
||||
'creating-pages',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Docs',
|
||||
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Use the **shorthand syntax** when you don't need **category options**:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
docs: {
|
||||
Guides: [
|
||||
'creating-pages',
|
||||
{
|
||||
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### Collapsible categories {#collapsible-categories}
|
||||
|
||||
For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
// highlight-start
|
||||
sidebarCollapsible: false,
|
||||
// highlight-end
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### Expanded categories by default {#expanded-categories-by-default}
|
||||
|
||||
For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
docs: {
|
||||
Guides: [
|
||||
'creating-pages',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Docs',
|
||||
collapsed: false,
|
||||
items: ['markdown-features', 'sidebar', 'versioning'],
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Autogenerated: generate a sidebar {#sidebar-item-autogenerated}
|
||||
|
||||
Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category.
|
||||
|
||||
An `autogenerated` item is converted by Docusaurus to a **sidebar slice**: a list of items of type `doc` and `category`.
|
||||
|
||||
```typescript
|
||||
type SidebarItemAutogenerated = {
|
||||
type: 'autogenerated';
|
||||
dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
|
||||
};
|
||||
```
|
||||
|
||||
Docusaurus can generate a sidebar from your docs folder:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
myAutogeneratedSidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
type: 'autogenerated',
|
||||
dirName: '.', // '.' means the current docs folder
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
You can also use **multiple `autogenerated` items** in a sidebar, and interleave them with regular sidebar items:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
mySidebar: [
|
||||
'intro',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Tutorials',
|
||||
items: [
|
||||
'tutorial-intro',
|
||||
// highlight-start
|
||||
{
|
||||
type: 'autogenerated',
|
||||
dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy
|
||||
},
|
||||
// highlight-end
|
||||
'tutorial-medium',
|
||||
// highlight-start
|
||||
{
|
||||
type: 'autogenerated',
|
||||
dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/hard
|
||||
},
|
||||
// highlight-end
|
||||
'tutorial-end',
|
||||
],
|
||||
},
|
||||
// highlight-start
|
||||
{
|
||||
type: 'autogenerated',
|
||||
dirName: 'guides', // Generate sidebar slice from docs/guides
|
||||
},
|
||||
// highlight-end
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Community',
|
||||
items: ['team', 'chat'],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
#### Autogenerated sidebar metadatas {#autogenerated-sidebar-metadatas}
|
||||
|
||||
By default, the sidebar slice will be generated in **alphabetical order** (using files and folders names).
|
||||
|
||||
If the generated sidebar does not look good, you can assign additional metadatas to docs and categories.
|
||||
|
||||
**For docs**: use additional frontmatter:
|
||||
|
||||
```diff title="docs/tutorials/tutorial-easy.md"
|
||||
+ ---
|
||||
+ sidebar_label: Easy
|
||||
+ sidebar_position: 2
|
||||
+ ---
|
||||
|
||||
|
||||
# Easy Tutorial
|
||||
|
||||
This is the easy tutorial!
|
||||
```
|
||||
|
||||
**For categories**: add a `_category_.json` or `_category_.yml` file in the appropriate folder:
|
||||
|
||||
```json title="docs/tutorials/_category_.json"
|
||||
{
|
||||
"label": "Tutorial",
|
||||
"position": 3
|
||||
}
|
||||
```
|
||||
|
||||
```yaml title="docs/tutorials/_category_.yml"
|
||||
label: 'Tutorial'
|
||||
position: 2.5 # float position is supported
|
||||
collapsed: false # keep the category open by default
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
The position metadata is only used **inside a sidebar slice**: Docusaurus does not re-order other items of your sidebar.
|
||||
|
||||
:::
|
||||
|
||||
#### Using number prefixes
|
||||
|
||||
A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes:
|
||||
|
||||
```bash
|
||||
docs
|
||||
├── 01-Intro.md
|
||||
├── 02-Tutorial Easy
|
||||
│ ├── 01-First Part.md
|
||||
│ ├── 02-Second Part.md
|
||||
│ └── 03-End.md
|
||||
├── 03-Tutorial Hard
|
||||
│ ├── 01-First Part.md
|
||||
│ ├── 02-Second Part.md
|
||||
│ ├── 03-Third Part.md
|
||||
│ └── 04-End.md
|
||||
└── 04-End.md
|
||||
```
|
||||
|
||||
To make it **easier to adopt**, Docusaurus supports **multiple number prefix patterns**.
|
||||
|
||||
By default, Docusaurus will **remove the number prefix** from the doc id, title, label and url paths.
|
||||
|
||||
:::caution
|
||||
|
||||
**Prefer using [additional metadatas](#autogenerated-sidebar-metadatas)**.
|
||||
|
||||
Updating a number prefix can be annoying, as it can require **updating multiple existing markdown links**:
|
||||
|
||||
```diff title="docs/02-Tutorial Easy/01-First Part.md"
|
||||
- Check the [Tutorial End](../04-End.md);
|
||||
+ Check the [Tutorial End](../05-End.md);
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### Customize the sidebar items generator
|
||||
|
||||
You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
// highlight-start
|
||||
sidebarItemsGenerator: async function ({
|
||||
defaultSidebarItemsGenerator,
|
||||
numberPrefixParser,
|
||||
item,
|
||||
version,
|
||||
docs,
|
||||
}) {
|
||||
// Example: return an hardcoded list of static sidebar items
|
||||
return [
|
||||
{type: 'doc', id: 'doc1'},
|
||||
{type: 'doc', id: 'doc2'},
|
||||
];
|
||||
},
|
||||
// highlight-end
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
**Re-use and enhance the default generator** instead of writing a generator from scratch.
|
||||
|
||||
**Add, update, filter, re-order** the sidebar items according to your use-case:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
// Reverse the sidebar items ordering (including nested category items)
|
||||
function reverseSidebarItems(items) {
|
||||
// Reverse items in categories
|
||||
const result = items.map((item) => {
|
||||
if (item.type === 'category') {
|
||||
return {...item, items: reverseSidebarItems(item.items)};
|
||||
}
|
||||
return item;
|
||||
});
|
||||
// Reverse items at current level
|
||||
result.reverse();
|
||||
return result;
|
||||
}
|
||||
// highlight-end
|
||||
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
// highlight-start
|
||||
sidebarItemsGenerator: async function ({
|
||||
defaultSidebarItemsGenerator,
|
||||
...args
|
||||
}) {
|
||||
const sidebarItems = await defaultSidebarItemsGenerator(args);
|
||||
return reverseSidebarItems(sidebarItems);
|
||||
},
|
||||
// highlight-end
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Hideable sidebar {#hideable-sidebar}
|
||||
|
||||
Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
// highlight-starrt
|
||||
hideableSidebar: true,
|
||||
// highlight-end
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Passing custom props {#passing-custom-props}
|
||||
|
||||
To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'doc1',
|
||||
customProps: {
|
||||
/* props */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Complex sidebars example {#complex-sidebars-example}
|
||||
|
||||
Real-world example from the Docusaurus site:
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
||||
<CodeBlock className="language-js" title="sidebars.js">
|
||||
{require('!!raw-loader!@site/sidebars.js')
|
||||
.default
|
||||
.split('\n')
|
||||
// remove comments
|
||||
.map((line) => !['#','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line)
|
||||
.filter(Boolean)
|
||||
.join('\n')}
|
||||
</CodeBlock>
|
||||
```
|
||||
|
|
@ -0,0 +1,208 @@
|
|||
---
|
||||
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 master (next) version
|
||||
├── docs # docs directory for master (next) 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` | next | /docs/next/hello |
|
||||
|
||||
### Tagging a new version {#tagging-a-new-version}
|
||||
|
||||
1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master.
|
||||
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-<version>/` folder.
|
||||
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-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.
|
||||
|
||||
**Master docs**
|
||||
|
||||
```shell
|
||||
# The new file.
|
||||
docs/new.md
|
||||
|
||||
# Edit the corresponding sidebar file.
|
||||
sidebar.js
|
||||
```
|
||||
|
||||
**Older 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 version 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)
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue