Aller au contenu principal
Version: 2.0.0-alpha.72

Barre latérale

Pour générer une barre latérale sur votre site Docusaurus :

  1. Définir un fichier qui exporte un objet sidebar.
  2. Passer cet objet directement dans le plugin @docusaurus/plugin-docs ou via @docusaurus/preset-classic.
docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// Chemin relatif du fichier des barres latérales par rapport au répertoire du site.
sidebarPath: require.resolve('./sidebars.js'),
},
// ...
},
],
],
};

Objet sidebar#

Un objet sidebar contient les éléments de la barre latérale et il est défini comme ceci :

type Sidebar = {
[sidebarId: string]:
| {
[sidebarCategory: string]: SidebarItem[];
}
| SidebarItem[];
};

Par exemple :

sidebars.js
module.exports = {
docs: [
{
type: 'category',
label: 'Getting Started',
items: ['greeting'],
},
{
type: 'category',
label: 'Docusaurus',
items: ['doc1'],
},
],
};

Dans cet exemple, notez ce qui suit :

  • La clé docs est l'id de la barre latérale. L'id peut être n'importe quelle valeur, pas nécessairement docs.
  • Getting Started est une catégorie dans la barre latérale.
  • greeting et doc1 sont tous les deux des éléments de la barre latérale.

La notation abrégée peut également être utilisée :

sidebars.js
module.exports = {
docs: {
'Getting started': ['greeting'],
Docusaurus: ['doc1'],
},
};
remarque

La notation abrégée s'appuie sur l'ordre d'itération des clés d'objets JavaScript pour le nom de la catégorie. Lorsque vous utilisez cette notation, gardez à l'esprit que EcmaScript ne garantit pas Object.keys({a,b}) === ['a','b'], mais c'est généralement vrai.

Utiliser plusieurs barres latérales#

Vous pouvez avoir plusieurs barres latérales pour différents fichiers Markdown en ajoutant plus de clés de premier niveau à l'objet exporté.

Exemple :

sidebars.js
module.exports = {
firstSidebar: {
'Category A': ['doc1'],
},
secondSidebar: {
'Category A': ['doc2'],
'Category B': ['doc3'],
},
};

Par défaut, la page du document que l'utilisateur est en train de lire affichera la barre latérale dont elle fait partie. Un sibarItem a un type qui définit ce à quoi l'élément est lié.

Par exemple, avec l'exemple ci-dessus, lors de l'affichage de la page doc2 , la barre latérale contiendra uniquement les éléments de secondSidebar. Un autre exemple de barres latérales multiples est les sections API et Docs sur le site Web de Docusaurus.

Pour plus d'informations sur les barres latérales et leur relation avec les pages de document, consultez le lien de documentation de la barre de navigation.

Comprendre les éléments de la barre latérale#

Comme le nom l'indique, SidebarItem est un élément défini dans une barre latérale. Un SibarItem a un type qui définit ce à quoi l'élément est lié.

type prend en charge les valeurs suivantes

Lien vers une page de doc#

Définir type à doc pour lier à une page de documentation. C'est le type par défaut.

type SidebarItemDoc =
| string
| {
type: 'doc';
id: string;
};

Exemple :

{
type: 'doc',
id: 'doc1', // string - document id
}

Utiliser juste le Document ID est également valide, ce qui suit est équivalent à ce qui précède :

'doc1'; // string - document id

L'utilisation de ce type liera le doc lié à la barre latérale actuelle. Cela signifie que si vous accédez à la page doc1 , la barre latérale affichée sera la barre latérale qui contient cette page de documentation.

Dans l'exemple ci-dessous, doc1 est lié à firstSidebar.

sidebars.js
module.exports = {
firstSidebar: {
'Category A': ['doc1'],
},
secondSidebar: {
'Category A': ['doc2'],
'Category B': ['doc3'],
},
};

Création d'un lien générique#

Définir type à link pour lier vers une page de non-documentation. Par exemple, pour créer un lien externe.

type SidebarItemLink = {
type: 'link';
label: string;
href: string;
};

Exemple :

{
type: 'link',
label: 'Custom Label', // Le libellé qui doit être affiché (string).
href: 'https://example.com' // L'URL cible (string).
}

Création d'un lien vers une page sans barre latérale#

Définir type à ref pour lier une page de documentation sans la lier à une barre latérale. Cela signifie que la barre latérale disparaît lorsque l'utilisateur affiche la page liée.

type SidebarItemRef = {
type: 'ref';
id: string;
};

Exemple :

{
type: 'ref',
id: 'doc1', // Document id (string).
}

Création d'une hiérarchie#

Il s'agit du type d'élément de la barre latérale qui crée une hiérarchie dans la barre latérale. Définir le type avec category.

type SidebarItemCategory = {
type: 'category';
label: string; // Texte du libellé de la barre latérale.
items: SidebarItem[]; // Tableau d'éléments de la barre latérale.
collapsed: boolean; // Définit la catégorie à réduire ou à développer par défaut
};

Exemple :

sidebars.js
module.exports = {
docs: [
{
...
},
{
type: 'category',
label: 'Guides',
items: [
'guides/creating-pages',
{
Docs: ['docs-introduction', 'docs-sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};

Remarquee : il est possible d'utiliser la syntaxe de raccourci pour créer des catégories imbriquées :

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: [
'docs-introduction',
'docs-sidebar',
'markdown-features',
'versioning',
],
},
],
},
};

Catégories repliables#

Pour les sites dont le contenu est assez important, nous préconisons l'option de développer/réduire une catégorie pour afficher son contenu. Les catégories sont repliables par défaut. Si vous voulez qu'elles soient toujours développés, mettez themeConfig.sidebarCollapsible à false :

docusaurus.config.js
module.exports = {
// ...
themeConfig: {
sidebarCollapsible: false,
// ...
},
};

Catégories développées par défaut#

Pour les documents comportant des catégories repliables, vous pouvez souhaiter un contrôle plus précis sur certaines catégories. Si vous voulez que des catégories spécifiques soient toujours développées, vous pouvez définir collapsed à false :

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};

Barre latérale masquable#

Grâce à l'option activée themeConfig.hideableSidebar, vous pouvez masquer l'intégralité de la barre latérale, ce qui vous permet de mieux concentrer vos utilisateurs 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: {
hideableSidebar: true,
// ...
},
};

Passage de props personnalisés#

Pour transmettre des props personnalisés à un élément « swizzlé » de la barre latérale, ajoutez l'objet optionnel customProps à l'un des éléments :

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