Aller au contenu principal
Version : Canary 🚧

Barre latérale

La création d'une barre latérale est utile pour :

  • Group multiple related documents into an ordered tree
  • Display a common sidebar on each of those documents
  • Fournir une navigation paginée, avec le bouton suivant/précédent

Pour utiliser les barres latérales sur votre site Docusaurus :

  1. Define a sidebars file that exports a dictionary of sidebar objects.
  2. Pass its path to the @docusaurus/plugin-docs plugin directly or via @docusaurus/preset-classic.
docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
Node.js runtime

The sidebars file is run with Node.js. You can't use or import browsers APIs, React or JSX in it.

Cette section sert de vue d'ensemble des caractéristiques diverses de la barre latérale du doc. Dans les sections suivantes, nous introduirons plus systématiquement les concepts suivants :

Barre latérale par défaut

Si le sidebarPath n'est pas spécifié, Docusaurus génère automatiquement une barre latérale pour vous, en utilisant la structure du système de fichiers du dossier docs :

sidebars.js
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // génère une barre latérale à partir du dossier docs (ou versioned_docs/<version>)
},
],
};

Vous pouvez également définir vos barres latérales de manière explicite.

A sidebar is a hierarchy of categories, doc links, and other hyperlinks.

type Sidebar =
// Syntaxe normale
| SidebarItem[]
// Syntaxe abrégée
| {[categoryLabel: string]: SidebarItem[]};

Par exemple :

sidebars.js
export default {
mySidebar: [
{
type: 'category',
label: 'Pour commencer',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: 'En savoir plus',
href: 'https://example.com',
},
],
};

Ceci est un fichier de barres latérales qui exporte une barre latérale, appelée mySidebar. Il comporte trois éléments de premier niveau : deux catégories et un lien externe. Dans chaque catégorie, il y a quelques liens de doc.

Un fichier de barres latérales peut contenir des objets de barre latérale multiples, identifiés par leurs clés d'objet.

type SidebarsFile = {
[sidebarID: string]: Sidebar;
};

Configuration du thème

Barre latérale masquable

En activant l'option themeConfig.docs.sidebar.hideable vous pouvez masquer l'ensemble de la barre latérale, permettant aux utilisateurs de mieux se concentrer sur le contenu. Ceci est particulièrement utile lors de la consommation de contenu sur des écrans à dimensions moyennes (par exemple, sur des tablettes).

docusaurus.config.js
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};

Réduire automatiquement les catégories de la barre latérale

L'option themeConfig.docs.sidebar.autoCollapseCategories réduit toutes les catégories voisines lors du développement d'une catégorie. Cela évite à l'utilisateur d'avoir trop de catégories ouvertes et l'aide à se concentrer sur la section sélectionnée.

docusaurus.config.js
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};

Passing CSS classes

To pass CSS classes to a sidebar item, add the optional className attribute to any of the items. This is useful to apply visual customizations to specific sidebar items.

{
type: 'doc',
id: 'doc1',
className: 'sidebar-item--highlighted',
};

Passage de props personnalisés

Pour transmettre des propriétés personnalisées à un élément de barre latérale, ajoutez l'objet facultatif customProps à l'un des éléments. Cela est utile pour appliquer des personnalisations de site en changeant les composants React qui rendent les éléments de la barre latérale.

{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};

Passing a unique key

Passing a unique key attribute can help uniquely identify a sidebar item. Sometimes other attributes (such as label) are not enough to distinguish two sidebar items from each other.

{
type: 'category',
label: 'API', // You may have multiple categories with this widespread label
key: 'api-for-feature-1', // and now, they can be uniquely identified
};
How is this useful?

Docusaurus only uses the key attribute to generate unique i18n translation keys. When a translation key conflict happens (issue), Docusaurus will tell you to apply a key to distinguish sidebar items.

Alternatively, you may have your own reasons for using the key attribute that will be passed to the respective sidebar item React components.

Par défaut, le fil d'Ariane est affiché en haut, en utilisant le « chemin de la barre latérale » de la page courante.

Ce comportement peut être désactivé avec les options du plugin :

docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};

Exemple de barres latérales complexes

Un exemple du monde réel du site Docusaurus :

sidebars.js
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
link: {
type: 'generated-index',
},
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description:
"Let's learn about the most important Docusaurus concepts!",
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: [
'guides/creating-pages',
{
type: 'category',
label: 'Docs',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: 'Sidebar',
link: {
type: 'doc',
id: 'guides/docs/sidebar/index',
},
items: [
'guides/docs/sidebar/items',
'guides/docs/sidebar/autogenerated',
'guides/docs/sidebar/multiple-sidebars',
],
},
'guides/docs/versioning',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
link: {
type: 'doc',
id: 'guides/markdown-features/introduction',
},
items: [
'guides/markdown-features/react',
'guides/markdown-features/tabs',
'guides/markdown-features/code-blocks',
'guides/markdown-features/admonitions',
'guides/markdown-features/toc',
'guides/markdown-features/assets',
'guides/markdown-features/links',
'guides/markdown-features/plugins',
'guides/markdown-features/math-equations',
'guides/markdown-features/diagrams',
'guides/markdown-features/head-metadata',
],
},
'styling-layout',
'swizzling',
'static-assets',
'search',
'browser-support',
'seo',
'using-plugins',
'deployment',
{
type: 'category',
label: 'Internationalization',
link: {type: 'doc', id: 'i18n/introduction'},
items: [
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
'guides/whats-next',
],
},
{
type: 'category',
label: 'Advanced Guides',
link: {type: 'doc', id: 'advanced/index'},
items: [
'advanced/architecture',
'advanced/plugins',
'advanced/routing',
'advanced/ssg',
'advanced/client',
],
},
{
type: 'category',
label: 'Upgrading',
link: {
type: 'doc',
id: 'migration/index',
},
items: [
'migration/v3',
{
type: 'category',
label: 'To Docusaurus v2',
items: [
'migration/v2/migration-overview',
'migration/v2/migration-automated',
'migration/v2/migration-manual',
'migration/v2/migration-versioned-sites',
'migration/v2/migration-translated-sites',
],
},
],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
export default sidebars;