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

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./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 :

📄️ Éléments de la barre latérale

Nous avons introduit trois types d'éléments dans l'exemple dans la section précédente autogenerated, que nous expliquerons plus en détail plus tard.

📄️ 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 :

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

module.exports = {
  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

module.exports = {
  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

module.exports = {
  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,
  },
};

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 :

docusaurus.config.js

module.exports = {
  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;