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 :
- Define a sidebars file that exports a dictionary of sidebar objects.
- Pass its path to the
@docusaurus/plugin-docsplugin directly or via@docusaurus/preset-classic.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
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 :
📄️ Éléments de la barre latérale
The sidebar supports various item types:
📄️ Autogenerated
Docusaurus peut créer une barre latérale automatiquement à partir de votre structure de système de fichiers : chaque dossier crée une catégorie de barre latérale et chaque fichier crée un lien de documentation.
📄️ Utiliser plusieurs barres latérales
Vous pouvez créer une barre latérale pour chaque ensemble de fichiers Markdown que vous souhaitez regrouper.
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 :
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.
Objet sidebar
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 :
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).
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.
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
};
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.
Fil d'Ariane de la barre latérale
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 :
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
Exemple de barres latérales complexes
Un exemple du monde réel du site Docusaurus :
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;