Aller au contenu principal
Version: 2.0.0-beta.1 🚧

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. Spécifiez un fichier exportant un objet de barre latérale.
  2. Passez cet objet directement dans le plugin @docusaurus/plugin-docs ou via @docusaurus/preset-classic.
docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
},
],
],
};

Barre latérale par défaut#

Par défaut, 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
module.exports = {
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#

Une barre latérale est un arbre d'éléments de la barre latérale.

type Sidebar =
// Syntaxe normale
| SidebarItem[]
// Syntaxe abrégée
| Record<
string, // libellé de la catégorie
SidebarItem[] // éléments de la catégorie
>;

Un fichier de barres latérales peut contenir des objets de barre latérale multiples.

type SidebarsFile = Record<
string, // sidebar id
Sidebar
>;

Exemple :

sidebars.js
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Pour commencer',
items: ['doc1'],
},
{
type: 'category',
label: 'Docusaurus',
items: ['doc2', 'doc3'],
},
],
};

Remarquez les éléments suivants :

  • Il y a une seule barre latérale mySidebar, contenant 5 éléments de la barre latérale
  • Pour commencer et Docusaurus sont des catégories de la barre latérale
  • doc1, doc2 et doc3 sont des documents de barre latérale
astuce

Utilisez la syntaxe abrégée pour exprimer cette barre latérale de manière plus concise :

sidebars.js
module.exports = {
mySidebar: {
'Pour commencer': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
};

Utiliser plusieurs barres latérales#

Vous pouvez créer une barre latérale pour chaque ensemble de fichiers markdown que vous souhaitez regrouper.

astuce

Le site Docusaurus est un bon exemple d'utilisation de plusieurs barres latérales :

Exemple :

sidebars.js
module.exports = {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
remarque

Les clés tutorialSidebar et apiSidebar sont identifiants techniques de barre latéralé et n'ont pas beaucoup d'importance.

Lors de la navigation :

  • doc1 ou doc2: la tutorialSidebar sera affichée
  • doc3 ou doc4: la apiSidebar sera affichée

Un lien de navigation paginé pour les documents dans la même barre latérale avec les boutons suivant et précédent.

Comprendre les éléments de la barre latérale#

SidebarItem est un élément défini dans un arbre de barre latérale.

Il y a différents types pour les éléments de la barre latérale :

  • Doc : lien vers une page de doc, permettant de la placer dans la barre latérale
  • Ref : lien vers une page de doc, sans la placer dans la barre latérale
  • Link : lien vers une page interne ou externe
  • Category : créer une hiérarchie des éléments de la barre latérale
  • Autogenerated : génère automatiquement une barre latérale

Doc : lien vers un doc#

Utilisez le type doc pour créer un lien vers une page doc et ajouter ce doc à une barre latérale :

type SidebarItemDoc =
// Syntaxe normale
| {
type: 'doc';
id : string;
label: string; // Texte libellé de la barre latérale
}
// Syntaxe abrégée
| string ; // raccourci docId

Exemple :

sidebars.js
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
],
};

Le sidebar_label de la partie supérieure de la page markdown a une priorité supérieure à la clé label dans SidebarItemDoc.

remarque

Ne pas affecter le même doc à plusieurs barres latérales : utilisez plutôt un ref.

Ref : lien vers un doc, sans barre latérale#

Utilisez le type ref pour créer un lien vers une page doc sans l'ajouter à une barre latérale.

type SidebarItemRef = {
type: 'ref';
id: string;
};

Exemple :

sidebars.js
module.exports = {
mySidebar: [
{
type: 'ref',
id: 'doc1', // Id du document (string).
},
],
};

Lorsque vous parcourez doc1, Docusaurus n'affichera pas la barre latérale mySidebar.

Link : lien vers n'importe quelle page#

Utilisez le type link pour créer un lien vers une page (interne ou externe) qui n'est pas un doc.

type SidebarItemLink = {
type: 'link';
label: string;
href: string;
};

Exemple :

sidebars.js
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
},
],
};

Category : créer une hiérarchie#

Utilisez le type category pour créer une hiérarchie des éléments de la barre latérale.

type SidebarItemCategory = {
type: 'category';
label: string; // Texte du libellé de la barre latérale.
items: SidebarItem[]; // Tableau d'éléments de la barre latérale.
// Options de catégorie :
collapsed: boolean; // Définit la catégorie à réduire ou à ouvrir par défaut
};

Exemple :

sidebars.js
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
astuce

Utilisez la syntaxe abrégée ** lorsque vous n'avez pas besoin d'options de catégorie** :

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};

Catégories repliables#

Pour les sites dont le contenu est assez important, nous préconisons l'option de développer/réduire une catégorie pour afficher son contenu. Les catégories sont repliables par défaut. Si vous voulez qu'elles soient toujours développés, mettez themeConfig.sidebarCollapsible à false :

docusaurus.config.js
module.exports = {
themeConfig: {
sidebarCollapsible: false,
},
};

Catégories développées par défaut#

Pour les documents comportant des catégories repliables, vous pouvez souhaiter un contrôle plus précis sur certaines catégories. Si vous voulez que des catégories spécifiques soient toujours développées, vous pouvez définir collapsed à false :

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};

Autogenerated : générer une barre latérale#

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.

Un élément autogenerated est converti par Docusaurus en une barre latérale : une liste d'éléments de type doc et category.

type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // Dossier source pour générer la barre latérale (relative à docs)
};

Docusaurus peut générer une barre latérale à partir de votre dossier docs :

sidebars.js
module.exports = {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' signifie le dossier docs courant
},
],
};

Vous pouvez également utiliser plusieurs autogenerated dans une barre latérale, et les laisser avec les éléments de la barre latérale habituelle :

sidebars.js
module.exports = {
mySidebar: [
'intro',
{
type: 'category',
label: 'Tutorials',
items: [
'tutorial-intro',
{
type: 'autogenerated',
dirName: 'tutorials/easy', // Génère une barre latérale à partir de docs/tutorials/easy
},
'tutorial-medium',
{
type: 'autogenerated',
dirName: 'tutorials/advanced', // Génère une barre latérale à partir de docs/tutorials/hard
},
'tutorial-end',
],
},
{
type: 'autogenerated',
dirName: 'guides', // Génère une barre latérale à partir de docs/guides
},
{
type: 'category',
label: 'Community',
items: ['team', 'chat'],
},
],
};

Métadonnées de la barre latérale générées automatiquement#

Par défaut, la barre latérale sera générée par ordre alphabétique (en utilisant les noms des fichiers et des dossiers).

Si la barre latérale générée ne semble pas correcte, vous pouvez assigner des métadonnées supplémentaires à des docs et des catégories.

Pour les docs : utilisez un frontmatter supplémentaire :

docs/tutorials/tutorial-easy.md
+ ---
+ sidebar_label: Facile
+ sidebar_position: 2
+ ---
# Tutoriel facile
C'est le tutoriel facile !

Pour les catégories : ajoutez un fichier _category_.json ou _category_.yml dans le dossier approprié :

docs/tutorials/_category_.json
{
"label": "Tutoriel",
"position": 3
}
docs/tutorials/_category_.yml
label: 'Tutoriel'
position: 2.5 # la position flottante est supportée
collapsed: false # garder la catégorie ouverte par défaut
info

Les métadonnées de position ne sont utilisées que à l'intérieur d'une barre latérale : Docusaurus ne réorganise pas les autres éléments de votre barre latérale.

Utilisez les préfixes de nombre#

Un moyen simple de trier une barre latérale générée automatiquement est de préfixer les docs et les dossiers par des préfixes de nombre :

docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Hard
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md

Pour faciliter son adoption, Docusaurus prend en charge plusieurs formats de préfixes numériques.

Par défaut, Docusaurus supprimera le préfixe de nombre de l'identifiant du doc, du titre, du libellé et des chemins de l'url.

attention

Préférez l'utilisation de métadonnées supplémentaires.

Mettre à jour un préfixe de nombres peut être ennuyeux, car cela peut nécessiter la mise à jour de plusieurs liens markdown existants :

docs/02-Tutorial Easy/01-First Part.md
- Check the [Tutorial End](../04-End.md);
+ Check the [Tutorial End](../05-End.md);

Personnalisez le générateur d'éléments de la barre latérale#

Vous pouvez fournir une fonction personnalisée sidebarItemsGenerator dans la configuration du plugin docs (ou du preset) :

docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
}) {
// Exemple : retourne une liste codée en dur des éléments statiques de la barre latérale
return [
{type: 'doc', id: 'doc1'},
{type: 'doc', id: 'doc2'},
];
},
},
],
],
};
astuce

Réutilisez et améliorez le générateur par défaut au lieu d'écrire un générateur à partir de zéro.

Ajoutez, mettez à jour, filtrez, réordonnez les éléments de la barre latérale en fonction de votre cas d'utilisation :

docusaurus.config.js
// Inverse l'ordre des éléments de la barre latérale (y compris les éléments de catégorie imbriqués)
function reverseSidebarItems(items) {
// Inverse les éléments dans les catégories
const result = items.map((item) => {
if (item.type === 'category') {
return {...item, items: reverseSidebarItems(item.items)};
}
return item;
});
// Inverse les éléments au niveau actuel
result.reverse();
return result;
}
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator,
...args
}) {
const sidebarItems = await defaultSidebarItemsGenerator(args);
return reverseSidebarItems(sidebarItems);
},
},
],
],
};

Barre latérale masquable#

Grâce à l'option activée themeConfig.hideableSidebar, vous pouvez masquer l'intégralité de la barre latérale, ce qui vous permet de mieux concentrer vos utilisateurs 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
module.exports = {
themeConfig: {
// highlight-starrt
hideableSidebar: true,
},
};

Passage de props personnalisés#

Pour transmettre des props personnalisés à un élément « swizzlé » de la barre latérale, ajoutez l'objet optionnel customProps à l'un des éléments :

{
type: 'doc',
id: 'doc1',
customProps: {
/* props */
}
}

Exemple de barres latérales complexes#

Exemple du monde réel du site Docusaurus :

sidebars.js
module.exports = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
collapsed: false,
items: ['installation', 'configuration', 'typescript-support'],
},
{
type: 'category',
label: 'Guides',
items: [
'guides/creating-pages',
{
Docs: [
'guides/docs/introduction',
'guides/docs/create-doc',
'guides/docs/sidebar',
'guides/docs/versioning',
'guides/docs/markdown-features',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
items: [
'guides/markdown-features/introduction',
'guides/markdown-features/react',
'guides/markdown-features/tabs',
'guides/markdown-features/code-blocks',
'guides/markdown-features/admonitions',
'guides/markdown-features/headings',
'guides/markdown-features/inline-toc',
'guides/markdown-features/assets',
'guides/markdown-features/plugins',
],
},
'styling-layout',
'static-assets',
'search',
'browser-support',
'deployment',
{
type: 'category',
label: 'Internationalization',
items: [
{
type: 'doc',
id: 'i18n/introduction',
label: 'Introduction',
},
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
],
},
{
type: 'category',
label: 'Advanced Guides',
items: ['using-plugins', 'using-themes', 'presets'],
},
{
type: 'category',
label: 'Migrating from v1 to v2',
items: [
'migration/migration-overview',
'migration/migration-automated',
'migration/migration-manual',
'migration/migration-versioned-sites',
'migration/migration-translated-sites',
],
},
],
api: [
'cli',
'docusaurus-core',
'api/docusaurus.config.js',
'lifecycle-apis',
{
type: 'category',
label: 'Plugins',
items: [
'api/plugins/plugins-overview',
'api/plugins/plugin-content-docs',
'api/plugins/plugin-content-blog',
'api/plugins/plugin-content-pages',
'api/plugins/plugin-client-redirects',
'api/plugins/plugin-debug',
'api/plugins/plugin-google-analytics',
'api/plugins/plugin-google-gtag',
'api/plugins/plugin-ideal-image',
'api/plugins/plugin-pwa',
'api/plugins/plugin-sitemap',
],
},
{
type: 'category',
label: 'Themes',
items: [
'api/themes/themes-overview',
'api/themes/theme-configuration',
'api/themes/theme-classic',
'api/themes/theme-bootstrap',
'api/themes/theme-live-codeblock',
'api/themes/theme-search-algolia',
],
},
],
};
Modifier cette page