Éléments de la barre latérale
We have introduced three types of item types in the example in the previous section: doc
, category
, and link
, whose usages are fairly intuitive. Nous présenterons explicitement leurs API. There's also a fourth type: autogenerated
, which we will explain in detail later.
- Doc: link to a doc page, associating it with the sidebar
- Link: link to any internal or external page
- Category: creates a dropdown of sidebar items
- Autogenerated: generate a sidebar slice automatically
- HTML: renders pure HTML in the item's position
- *Ref: link to a doc page, without making the item take part in navigation generation
Doc: link to a doc
Use the doc
type to link to a doc page and assign that doc to a sidebar:
type SidebarItemDoc =
// Normal syntax
| {
type: 'doc';
id: string;
label: string; // Sidebar label text
className?: string; // Class name for sidebar label
customProps?: Record<string, unknown>; // Custom props
}
// Shorthand syntax
| string; // docId shortcut
Exemple :
module.exports = {
mySidebar: [
// Syntaxe normale :
{
type: 'doc',
id: 'doc1', // ID du document
label: 'Pour commencer', // libellé de la barre latérale
},
// Syntaxe abrégée :
'doc2', // ID du document
],
};
If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the sidebar_label
Markdown front matter within that doc, which has higher precedence over the label
key in the sidebar item. Similarly, you can use sidebar_custom_props
to declare custom metadata for a doc page.
A doc
item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars: change the type to ref
instead.
Les props personnalisés de la barre latérale sont un moyen utile de propager des métadonnées arbitraires sur les documents du côté client, afin que vous puissiez obtenir des informations supplémentaires lorsque vous utilisez un hook lié aux documents qui récupère un objet doc.
Link: link to any page
Use the link
type to link to any page (internal or external) that is not a doc.
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
description?: string;
};
Exemple :
module.exports = {
myLinksSidebar: [
// Lien externe
{
type: 'link',
label: 'Facebook', // Le libellé du lien
href: 'https://facebook.com', // L'URL externe
},
// Lien interne
{
type: 'link',
label: 'Accueil', // Le libellé du lien
href: '/', // Le chemin interne
},
],
};
HTML: render custom markup
Use the html
type to render custom HTML within the item's <li>
tag.
Cela peut être utile pour insérer des éléments personnalisés tels que des divisions, des titres de section, des publicités et des images.
type SidebarItemHtml = {
type: 'html';
value: string;
defaultStyle?: boolean; // Utiliser les styles de l'élément du menu par défaut
className?: string;
};
Exemple :
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
defaultStyle: true, // Use the default menu item styling
},
],
};
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:
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: 'Concepts de base',
className: 'sidebar-title',
},
],
};
Category: create a hierarchy
Use the category
type to create a hierarchy of sidebar items.
type SidebarItemCategory = {
type: 'category';
label: string; // Sidebar label text.
items: SidebarItem[]; // Array of sidebar items.
className?: string;
description?: string;
// Category options:
collapsible: boolean; // Set the category to be collapsible
collapsed: boolean; // Set the category to be initially collapsed or open by default
link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
Exemple :
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
Use the shorthand syntax when you don't need customizations:
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
Category links
Avec les liens de catégorie, un clic sur une catégorie peut vous faire accéder à une autre page.
Utilisez les liens de catégorie pour introduire une catégorie de documents.
Autogenerated categories can use the _category_.yml
file to declare the link.
Generated index page
Vous pouvez générer automatiquement une page d'index qui affiche tous les enfants directs de cette catégorie. The slug
allows you to customize the generated page's route, which defaults to /category/[categoryName]
.
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Guides de Docusaurus',
description: 'En savoir plus sur les concepts Docusaurus les plus importants !',
slug: '/category/docusaurus-guides',
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
See it in action on the Docusaurus Guides page.
Use generated-index
links as a quick way to get an introductory document.
Doc link
Une catégorie peut créer un lien vers un document existant.
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'introduction'},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
See it in action on the i18n introduction page.
Embedding generated index in doc page
You can embed the generated cards list in a normal doc page as well with the DocCardList
component. Elle affichera tous les éléments de la barre latérale de la catégorie parente du document courant.
import DocCardList from '@theme/DocCardList';
<DocCardList />
📄️ Éléments de la barre latérale
We have introduced three types of item types in the example in the previous section autogenerated, which we will explain in detail later.
📄️ Autogenerated
Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.
📄️ Utiliser plusieurs barres latérales
You can create a sidebar for each set of Markdown files that you want to group together.
Collapsible categories
Nous prenons en charge l'option permettant de développer/réduire les catégories. Categories are collapsible by default, but you can disable collapsing with collapsible: false
.
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
items: [
'creating-pages',
{
type: 'category',
collapsible: false,
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
To make all categories non-collapsible by default, set the sidebarCollapsible
option in plugin-content-docs
to false
:
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
The option in sidebars.js
takes precedence over plugin configuration, so it is possible to make certain categories collapsible when sidebarCollapsible
is set to false
globally.
Expanded categories by default
Les catégories repliables sont réduites par défaut. If you want them to be expanded on the first render, you can set collapsed
to false
:
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
Similar to collapsible
, you can also set the global configuration options.sidebarCollapsed
to false
. Individual collapsed
options in sidebars.js
will still take precedence over this configuration.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
When a category has collapsed: true
but collapsible: false
(either through sidebars.js
or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.
Using shorthands
You can express typical sidebar items without much customization more concisely with shorthand syntaxes. There are two parts to this: doc shorthand and category shorthand.
Doc shorthand
An item with type doc
can be simply a string representing its ID:
- Longhand
- Shorthand
module.exports = {
sidebar: [
{
type: 'doc',
id: 'myDoc',
},
],
};
module.exports = {
sidebar: [
'myDoc',
],
};
Il est donc possible de simplifier l'exemple ci-dessus ainsi :
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Pour commencer',
items: [
'doc1',
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
'doc2',
'doc3',
],
},
{
type: 'link',
label: 'En savoir plus',
href: 'https://example.com',
},
],
};
Category shorthand
Un élément de catégorie peut être représenté par un objet dont la clé est son label, et la valeur est un tableau de sous-éléments.
- Longhand
- Shorthand
module.exports = {
sidebar: [
{
type: 'category',
label: 'Démarrage',
items: ['doc1', 'doc2'],
},
],
};
module.exports = {
sidebar: [
{
'Démarrage': ['doc1', 'doc2'],
},
],
};
Cela nous permet de simplifier cet exemple en :
module.exports = {
mySidebar: [
{
'Pour commencer': ['doc1'],
},
{
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'En savoir plus',
href: 'https://example.com',
},
],
};
Chaque objet raccourci après cette transformation contiendra exactement une entrée. Considérez maintenant l'exemple simplifié ci-dessous :
module.exports = {
mySidebar: [
{
'Pour commencer': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'En savoir plus',
href: 'https://example.com',
},
],
};
Notez comment les deux catégories consécutives sont comprimées en un seul objet avec deux entrées. 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.
Chaque fois que vous avez un tableau d'éléments qui est réduit à un arcccourci d'une catégorie, vous pouvez également omettre le tableau qui l'entoure.
- Before
- After
module.exports = {
sidebar: [
{
'Démarrage': ['doc1'],
Docusaurus: [
{
'Guides de base': ['doc2', 'doc3'],
'Guides avancés': ['doc4', 'doc5'],
},
],
},
],
};
module.exports = {
sidebar: {
'Démarrage': ['doc1'],
Docusaurus: {
'Guides de base': ['doc2', 'doc3'],
'Guides avancés': ['doc4', 'doc5'],
},
},
};