3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-31 09:57:03 +02:00
Code Issues Projects Releases Packages Wiki Activity

chore: release v3.5.1 (#10385)

Browse source
This commit is contained in:
Sébastien Lorber 2024-08-09 23:42:06 +02:00 • committed by GitHub
parent 9c5eb35e51
commit bde4414614
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
142 changed files with 379 additions and 203 deletions
Download patch file Download diff file Expand all files Collapse all files

212
website/versioned_docs/version-3.5.0/guides/docs/sidebar/index.mdx
View file

@ -1,212 +0,0 @@
---
slug: /sidebar
---
# Sidebar
Creating a sidebar is useful to:
- Group multiple **related documents**
- **Display a sidebar** on each of those documents
- Provide **paginated navigation**, with next/previous button
To use sidebars on your Docusaurus site:
1. Define a file that exports a dictionary of [sidebar objects](#sidebar-object).
2. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
```js title="docusaurus.config.js"
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
sidebarPath: './sidebars.js',
},
},
],
],
};
```
This section serves as an overview of miscellaneous features of the doc sidebar. In the following sections, we will more systematically introduce the following concepts:
```mdx-code-block
import DocCardList from '@theme/DocCardList';
<DocCardList />
```
## Default sidebar {#default-sidebar}
If the `sidebarPath` is unspecified, Docusaurus [automatically generates a sidebar](autogenerated.mdx) for you, by using the filesystem structure of the `docs` folder:
```js title="sidebars.js"
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
},
],
};
```
You can also define your sidebars explicitly.
## Sidebar object {#sidebar-object}
A sidebar at its crux is a hierarchy of categories, doc links, and other hyperlinks.
```ts
type Sidebar =
// Normal syntax
| SidebarItem[]
// Shorthand syntax
| {[categoryLabel: string]: SidebarItem[]};
```
For example:
```js title="sidebars.js"
export default {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
```
This is a sidebars file that exports one sidebar, called `mySidebar`. It has three top-level items: two categories and one external link. Within each category, there are a few doc links.
A sidebars file can contain [**multiple sidebar objects**](multiple-sidebars.mdx), identified by their object keys.
```ts
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
```
## Theme configuration {#theme-configuration}
### Hideable sidebar {#hideable-sidebar}
By enabling the `themeConfig.docs.sidebar.hideable` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).
```js title="docusaurus.config.js"
export default {
themeConfig: {
// highlight-start
docs: {
sidebar: {
hideable: true,
},
},
// highlight-end
},
};
```
### Auto-collapse sidebar categories {#auto-collapse-sidebar-categories}
The `themeConfig.docs.sidebar.autoCollapseCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.
```js title="docusaurus.config.js"
export default {
themeConfig: {
// highlight-start
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
// highlight-end
},
};
```
## Passing custom props {#passing-custom-props}
To pass in custom props to a sidebar item, add the optional `customProps` object to any of the items. This is useful to apply site customizations by swizzling React components rendering sidebar items.
```js
{
type: 'doc',
id: 'doc1',
// highlight-start
customProps: {
badges: ['new', 'green'],
featured: true,
},
// highlight-end
};
```
## Sidebar Breadcrumbs {#sidebar-breadcrumbs}
By default, breadcrumbs are rendered at the top, using the "sidebar path" of the current page.
This behavior can be disabled with plugin options:
```js title="docusaurus.config.js"
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
breadcrumbs: false,
},
},
],
],
};
```
## Complex sidebars example {#complex-sidebars-example}
A real-world example from the Docusaurus site:
```mdx-code-block
import CodeBlock from '@theme/CodeBlock';
<CodeBlock language="js" title="sidebars.js">
{require('!!raw-loader!@site/sidebars.ts')
.default
.split('\n')
// remove comments
.map((line) => !['//','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line)
.filter(Boolean)
.join('\n')}
</CodeBlock>
```