Aller au contenu principal
Version : 2.4.0

Utiliser plusieurs barres latérales

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

astuce

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

Prenons l'exemple suivant :

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

When browsing doc1 or doc2, the tutorialSidebar will be displayed; when browsing doc3 or doc4, the apiSidebar will be displayed.

Following the example above, if a commonDoc is included in both sidebars:

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

How does Docusaurus know which sidebar to display when browsing commonDoc? Réponse : il n'en est rien, et nous ne garantissons pas le choix de la barre latérale.

Lorsque vous ajoutez le doc Y à la barre latérale X, cela crée une liaison bidirectionnelle : la barre latérale X contient un lien vers le doc Y, et lorsque vous parcourez le doc Y, la barre latérale X s'affiche. Mais parfois, nous voulons interrompre l'une ou l'autre de ces liaisons implicites :

  1. How do I generate a link to doc Y in sidebar X without making sidebar X displayed on Y? For example, when I include doc Y in multiple sidebars as in the example above, and I want to explicitly tell Docusaurus to display one sidebar?
  2. How do I make sidebar X displayed when browsing doc Y, but sidebar X shouldn't contain the link to Y? For example, when Y is a "doc home page" and the sidebar is purely used for navigation?

Front matter option displayed_sidebar will forcibly set the sidebar association. Pour le même exemple, vous pouvez toujours utiliser des raccourcis de doc sans aucune configuration spéciale :

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

Et puis ajouter un frontmatter :

commonDoc.md
---
displayed_sidebar: apiSidebar
---

Which explicitly tells Docusaurus to display apiSidebar when browsing commonDoc. En utilisant la même méthode, vous pouvez faire en sorte que la barre latérale X qui ne contient pas le doc Y apparaisse sur le doc Y :

home.md
---
displayed_sidebar: tutorialSidebar
---

Even when tutorialSidebar doesn't contain a link to home, it will still be displayed when viewing home.

If you set displayed_sidebar: null, no sidebar will be displayed whatsoever on this page, and subsequently, no pagination either.

Generating pagination​

Docusaurus utilise la barre latérale pour générer les liens de pagination « suivant » et « précédent » au bas de chaque page de doc. Il utilise strictement la barre latérale qui est affichée : si aucune barre latérale n'est associée, cela ne génère pas non plus de pagination. However, the docs linked as "next" and "previous" are not guaranteed to display the same sidebar: they are included in this sidebar, but in their front matter, they may have a different displayed_sidebar.

If a sidebar is displayed by setting displayed_sidebar front matter, and this sidebar doesn't contain the doc itself, no pagination is displayed.

You can customize pagination with front matter pagination_next and pagination_prev. Considérez cette barre latérale :

sidebars.js
module.exports = {
  tutorial: [
    'introduction',
    {
      installation: ['windows', 'linux', 'macos'],
    },
    'getting-started',
  ],
};

Le lien suivant de la pagination pour « windows » pointe vers « linux », mais cela n'a pas de sens : vous aimeriez que les lecteurs passent à la rubrique « getting-started » après l'installation. Dans ce cas, vous pouvez définir la pagination manuellement :

windows.md
---
pagination_next: getting-started
---

# Installation sous Windows

You can also disable displaying a pagination link with pagination_next: null or pagination_prev: null.

Le libellé de la pagination par défaut est le libellé de la barre latérale. You can use the front matter pagination_label to customize how this doc appears in the pagination.

The ref type is identical to the doc type in every way, except that it doesn't participate in generating navigation metadata. Il ne s'enregistre que comme un lien. When generating pagination and displaying sidebar, ref items are completely ignored.

Ceci est particulièrement utile lorsque vous souhaitez créer un lien vers le même document à partir de plusieurs barres latérales. The document only belongs to one sidebar (the one where it's registered as type: 'doc' or from an autogenerated directory), but its link will appear in all sidebars that it's registered in.

Prenons l'exemple suivant :

sidebars.js
module.exports = {
  tutorialSidebar: {
    'Category A': [
      'doc1',
      'doc2',
      {type: 'ref', id: 'commonDoc'},
      'doc5',
    ],
  },
  apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};
}

You can think of the ref type as the equivalent to doing the following:

  • Setting displayed_sidebar: tutorialSidebar for commonDoc (ref is ignored in sidebar association)
  • Setting pagination_next: doc5 for doc2 and setting pagination_prev: doc2 for doc5 (ref is ignored in pagination generation)