mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-03 11:22:30 +02:00
feat(content-docs): allow omitting enclosing array consistently for category shorthand (#6602)
* feat(content-docs): allow omitting enclosing array consistently for category shorthand * update snapshot * fix doc
This commit is contained in:
Joshua Chen
GitHub
parent
e3fd3e74ce
commit
0c4dc00443
6 changed files with 302 additions and 80 deletions
|
|
@ -3,6 +3,11 @@ toc_max_heading_level: 4
|
|||
slug: /sidebar/items
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
```
|
||||
|
||||
# Sidebar items
|
||||
|
||||
We have introduced three types of item types in the example in the previous section: `doc`, `category`, and `link`, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later.
|
||||
|
|
@ -101,6 +106,55 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## HTML: render custom markup {#sidebar-item-html}
|
||||
|
||||
Use the `html` type to render custom HTML within the item's `<li>` tag.
|
||||
|
||||
This can be useful for inserting custom items such as dividers, section titles, ads, and images.
|
||||
|
||||
```ts
|
||||
type SidebarItemHtml = {
|
||||
type: 'html';
|
||||
value: string;
|
||||
defaultStyle?: boolean; // Use default menu item styles
|
||||
className?: string;
|
||||
};
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
myHtmlSidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
type: 'html',
|
||||
value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
|
||||
defaultStyle: true, // Use the default menu item styling
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
The menu item is already wrapped in an `<li>` tag, so if your custom item is simple, such as a title, just supply a string as the value and use the `className` property to style it:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
myHtmlSidebar: [
|
||||
{
|
||||
type: 'html',
|
||||
value: 'Core concepts',
|
||||
className: 'sidebar-title',
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Category: create a hierarchy {#sidebar-item-category}
|
||||
|
||||
Use the `category` type to create a hierarchy of sidebar items.
|
||||
|
|
@ -161,55 +215,6 @@ module.exports = {
|
|||
|
||||
:::
|
||||
|
||||
## HTML: render custom markup {#sidebar-item-html}
|
||||
|
||||
Use the `html` type to render custom HTML within the item's `<li>` tag.
|
||||
|
||||
This can be useful for inserting custom items such as dividers, section titles, ads, and images.
|
||||
|
||||
```ts
|
||||
type SidebarItemHtml = {
|
||||
type: 'html';
|
||||
value: string;
|
||||
defaultStyle?: boolean; // Use default menu item styles
|
||||
className?: string;
|
||||
};
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
myHtmlSidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
type: 'html',
|
||||
value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
|
||||
defaultStyle: true, // Use the default menu item styling
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
The menu item is already wrapped in an `<li>` tag, so if your custom item is simple, such as a title, just supply a string as the value and use the `className` property to style it:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
myHtmlSidebar: [
|
||||
{
|
||||
type: 'html',
|
||||
value: 'Core concepts',
|
||||
className: 'sidebar-title',
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Category links {#category-link}
|
||||
|
||||
With category links, clicking on a category can navigate you to another page.
|
||||
|
|
@ -390,20 +395,38 @@ You can express typical sidebar items without much customization more concisely
|
|||
|
||||
An item with type `doc` can be simply a string representing its ID:
|
||||
|
||||
```js
|
||||
// =================
|
||||
// This item:
|
||||
// =================
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'myDoc',
|
||||
<Tabs>
|
||||
<TabItem value="Longhand">
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'myDoc',
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
// =================
|
||||
// Is equivalent to:
|
||||
// =================
|
||||
'myDoc';
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Shorthand">
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
'myDoc',
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
So it's possible to simplify the example above to:
|
||||
|
||||
```js title="sidebars.js"
|
||||
|
|
@ -440,23 +463,41 @@ module.exports = {
|
|||
|
||||
A category item can be represented by an object whose key is its label, and the value is an array of subitems.
|
||||
|
||||
```js
|
||||
// ===================
|
||||
// This item:
|
||||
// ===================
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Getting started',
|
||||
items: ['doc1', 'doc2'],
|
||||
};
|
||||
// ===================
|
||||
// Is equivalent to:
|
||||
// ===================
|
||||
{
|
||||
'Getting started': ['doc1', 'doc2'],
|
||||
<Tabs>
|
||||
<TabItem value="Longhand">
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Getting started',
|
||||
items: ['doc1', 'doc2'],
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Shorthand">
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
'Getting started': ['doc1', 'doc2'],
|
||||
},
|
||||
// highlight-end
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This permits us to simplify that example to:
|
||||
|
||||
```js title="sidebars.js"
|
||||
|
|
@ -500,3 +541,42 @@ module.exports = {
|
|||
```
|
||||
|
||||
Note how the two consecutive category shorthands are compressed into one object with two entries. This syntax generates a **sidebar slice**: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing [autogenerated sidebars](autogenerated.md).
|
||||
|
||||
Wherever you have an array of items that is reduced to one category shorthand, you can omit that enclosing array as well.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Before">
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
sidebar: [
|
||||
{
|
||||
'Getting started': ['doc1'],
|
||||
Docusaurus: [
|
||||
{
|
||||
'Basic guides': ['doc2', 'doc3'],
|
||||
'Advanced guides': ['doc4', 'doc5'],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="After">
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
sidebar: {
|
||||
'Getting started': ['doc1'],
|
||||
Docusaurus: {
|
||||
'Basic guides': ['doc2', 'doc3'],
|
||||
'Advanced guides': ['doc4', 'doc5'],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue