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 :
- Define a file that exports a dictionary of sidebar objects.
- Pass this object into the
@docusaurus/plugin-docs
plugin directly or via@docusaurus/preset-classic
.
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:
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 :
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).
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.
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 :
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
Complex sidebars example
Un exemple du monde réel du site Docusaurus :
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;