Aller au contenu principal
Version : Canary 🚧

Barre latérale

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

  • Grouper plusieurs documents connexes
  • Afficher une barre latérale sur chacun de ces documents
  • Fournir une navigation paginée, avec le bouton suivant/précédent

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

  1. Définit un fichier qui exporte un dictionnaire d'objets de la barre latérale.
  2. Passez cet objet directement dans le plugin @docusaurus/plugin-docs ou via @docusaurus/preset-classic.
docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};

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.

Une barre latérale, c'est avant tout une hiérarchie de catégories, de liens vers des documents et d'autres hyperliens.

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,
},
},
},
};

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,
},
};

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;