Version: 2.0.0-beta.7

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 :

Définir un fichier qui exporte un objet sidebar.
Passer 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.

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.

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

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
      className?: string; // Nom de la classe pour le 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 du frontmatter de 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.

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.

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;
  className?: 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
    },
  ],
};

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.
  className?: string;

  // Options de catégorie :
  collapsible: boolean; // Configure la catégorie pour qu'elle soit repliable
  collapsed: boolean; // Définit la catégorie à être initialement réduite ou ouverte par défaut
};

Exemple :

sidebars.js

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      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

Nous prenons en charge l'option permettant de développer/réduire les catégories. Les catégories sont repliables par défaut, mais vous pouvez désactiver le pliage avec collapsible: false.

sidebars.js

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

Pour rendre toutes les catégories non pliables par défaut, définissez l'option sidebarCollapsible dans plugin-docs à false :

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};

remarque

L'option dans sidebars.js a la priorité sur la configuration du plugin, il est donc possible de rendre certaines catégories pliables lorsque sidebarCollapsible est défini à false globalement.

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

Les catégories repliables sont réduites par défaut. Si vous voulez qu'elles soient développées au premier rendu, 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'],
      },
    ],
  },
};

Similaire à collapsible, vous pouvez également définir la configuration globale options.sidebarCollapsed à false. Les options individuelles collapsed dans sidebars.js auront toujours la priorité sur cette configuration.

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};

caution

Lorsqu'une catégorie a collapsed : true mais collapsible : false (soit par sidebars.js, soit par la configuration du plugin), ce dernier prend le dessus et la catégorie est toujours rendue comme développée.

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

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: Easy
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,
  "className": "red"
}

docs/tutorials/_category_.yml

label: 'Tutorial'
position: 2.5 # la position flottante est prise en charge
collapsible: true # rend la catégorie repliable
collapsed: false # garde 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.

caution

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

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: {
    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

// @ts-check
const sidebars = {
  docs: [
    'introduction',
    {
      type: 'category',
      label: 'Getting Started',
      collapsed: false,
      items: [
        'installation',
        'configuration',
        'playground',
        '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',
            'guides/markdown-features/math-equations',
            'guides/markdown-features/head-metadatas',
          ],
        },
        '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-live-codeblock',
        'api/themes/theme-search-algolia',
      ],
    },
  ],
};
module.exports = sidebars;

Barre latérale

Barre latérale par défaut

Objet sidebar

astuce

Utiliser plusieurs barres latérales

astuce

remarque

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

Doc : lien vers un doc

remarque

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

Link : lien vers n'importe quelle page

Category : créer une hiérarchie

astuce

Catégories repliables

remarque

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

caution

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

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

info

Utilisez les préfixes de nombre

caution

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

astuce

Barre latérale masquable

Passage de props personnalisés

Exemple de barres latérales complexes

Barre latérale par défaut​

Objet sidebar​

astuce

Utiliser plusieurs barres latérales​

astuce

remarque

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

Doc : lien vers un doc​

remarque

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

Link : lien vers n'importe quelle page​

Category : créer une hiérarchie​

astuce

Catégories repliables​

remarque

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

caution

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

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

info

Utilisez les préfixes de nombre​

caution

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

astuce

Barre latérale masquable​

Passage de props personnalisés​

Exemple de barres latérales complexes​

Barre latérale par défaut

Objet sidebar

Utiliser plusieurs barres latérales

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

Doc : lien vers un doc

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

Link : lien vers n'importe quelle page

Category : créer une hiérarchie

Catégories repliables

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

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

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

Utilisez les préfixes de nombre

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

Barre latérale masquable

Passage de props personnalisés

Exemple de barres latérales complexes