Barre latérale

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

• Group multiple related documents
• Display a sidebar on each of those documents
• Provide paginated navigation, with next/previous button

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

1. Define a file that exports a dictionary of sidebar objects.
2. Pass this object into the @docusaurus/plugin-docs plugin directly or 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

We have introduced three types of item types in the example in the previous section autogenerated, which we will explain in detail later.

📄️ Autogenerated

Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.

📄️ Utiliser plusieurs barres latérales

You can create a sidebar for each set of Markdown files that you want to group together.

Default sidebar

If the sidebarPath is unspecified, Docusaurus automatically generates a sidebar for you, by using the filesystem structure of the docs folder:

sidebars.js

module.exports = {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
    },
  ],
};

Vous pouvez également définir vos barres latérales de manière explicite.

Sidebar object

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

This is a sidebars file that exports one sidebar, called 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.

A sidebars file can contain multiple sidebar objects, identified by their object keys.

type SidebarsFile = {
  [sidebarID: string]: Sidebar;
};

Theme configuration

Hideable sidebar

By enabling the themeConfig.docs.sidebar.hideable option, you can make the entire sidebar hideable, allowing users to better focus on the content. 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,
      },
    },
  },
};

Auto-collapse sidebar categories

The themeConfig.docs.sidebar.autoCollapseCategories option would collapse all sibling categories when expanding one category. 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,
      },
    },
  },
};

Passing custom props

To pass in custom props to a swizzled sidebar item, add the optional customProps object to any of the items:

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

Sidebar Breadcrumbs

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

Complex sidebars example

Un exemple du monde réel du site Docusaurus :

sidebars.js

const sidebars = {
  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: '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',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};
module.exports = sidebars;