Utiliser plusieurs barres latérales
You can create a sidebar for each set of Markdown files that you want to group together.
Prenons l'exemple suivant :
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.
Understanding sidebar association
Following the example above, if a commonDoc
is included in both sidebars:
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 :
- 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?
- 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 :
module.exports = {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
Et puis ajouter un frontmatter :
---
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 :
---
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 :
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 :
---
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
item
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 :
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
forcommonDoc
(ref
is ignored in sidebar association) - Setting
pagination_next: doc5
fordoc2
and settingpagination_prev: doc2
fordoc5
(ref
is ignored in pagination generation)