Éléments de la barre latérale
Nous avons introduit trois types d'éléments dans l'exemple dans la section précédente : doc, category et link, dont l'utilisation est assez intuitive. Nous présenterons explicitement leurs API. Il y a aussi un quatrième type : autogenerated, que nous expliquerons plus en détail plus tard.
- Doc : lien vers une page de doc, l'associant à la barre latérale
- Link : lien vers une page interne ou externe
- Category : crée un menu déroulant des éléments de la barre latérale
- Autogenerated : génère automatiquement une barre latérale
- HTML : rend du HTML pur dans la position de l'élément
- *Ref : lien vers une page de doc, sans faire participer l'élément à la génération de la navigation
Doc : lien vers un doc
Utilisez le type doc pour créer un lien vers une page doc et ajouter ce doc à une barre latérale :
type SidebarItemDoc =
// Syntaxe normale
| {
type: 'doc';
id : string;
label: string; // Texte libellé de la barre latérale
className?: string; // Nom de la classe pour le libellé de la barre latérale
customProps?: Record<string, unknown>; // props personnalisés
}
// Syntaxe abrégée
| string ; // raccourci docId
Exemple :
module.exports = {
mySidebar: [
// Syntaxe normale :
{
type: 'doc',
id: 'doc1', // ID du document
label: 'Pour commencer', // libellé de la barre latérale
},
// Syntaxe abrégée :
'doc2', // ID du document
],
};
Si vous utilisez le raccourci de doc ou la barre latérale autogenerated , vous perdrez la possibilité de personnaliser l'étiquette de la barre latérale à travers la définition de l'élément. Vous pouvez toutefois utiliser le frontmatter Markdown sidebar_label au sein de ce doc, qui a une priorité supérieure à la clé label dans l'élément de la barre latérale. De même, vous pouvez utiliser sidebar_custom_props pour déclarer des métadonnées personnalisées pour une page de doc.
Un élément doc définit une association de barre latérale implicite. N'affectez pas le même doc à plusieurs barres latérales : utilisez plutôt un ref.
Les props personnalisés de la barre latérale sont un moyen utile de propager des métadonnées arbitraires sur les documents du côté client, afin que vous puissiez obtenir des informations supplémentaires lorsque vous utilisez un hook lié aux documents qui récupère un objet doc.
Link : lien vers n'importe quelle page
Utilisez le type link pour créer un lien vers une page (interne ou externe) qui n'est pas un doc.
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
};
Exemple :
module.exports = {
myLinksSidebar: [
// Lien externe
{
type: 'link',
label: 'Facebook', // Le libellé du lien
href: 'https://facebook.com', // L'URL externe
},
// Lien interne
{
type: 'link',
label: 'Accueil', // Le libellé du lien
href: '/', // Le chemin interne
},
],
};
HTML : rendre un balisage personnalisé
Utilisez le type html pour afficher du HTML personnalisé dans la balise <li> de l'élément.
Cela peut être utile pour insérer des éléments personnalisés tels que des divisions, des titres de section, des publicités et des images.
type SidebarItemHtml = {
type: 'html';
value: string;
defaultStyle?: boolean; // Utiliser les styles de l'élément du menu par défaut
className?: string;
};
Exemple :
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: '<img src="sponsor.png" alt="Sponsor" />', // Le HTML à rendre
defaultStyle: true, // Utilise le style par défaut des éléments du menu
},
],
};
L'élément du menu est déjà enveloppé dans une balise <li>, donc si votre élément personnalisé est simple, comme un titre, il suffit de fournir une chaîne comme valeur et d'utiliser la propriété className pour le styliser :
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: 'Concepts de base',
className: 'sidebar-title',
},
],
};
Category : créer une hiérarchie
Utilisez le type category pour créer une hiérarchie des éléments de la barre latérale.
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.
className?: string;
// Options de catégorie :
collapsible: boolean; // Configure la catégorie pour qu'elle soit repliable
collapsed: boolean; // Configure la catégorie pour qu'elle soit initialement réduite ou ouverte par défaut
link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
Exemple :
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
Utilisez la syntaxe raccourci lorsque vous n'avez pas besoin de personnalisations :
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
Liens de catégorie
Avec les liens de catégorie, un clic sur une catégorie peut vous faire accéder à une autre page.
Utilisez les liens de catégorie pour introduire une catégorie de documents.
Les catégories générées automatiquement peuvent utiliser le fichier _category_.yml pour déclarer le lien.
Page d'index générée
Vous pouvez générer automatiquement une page d'index qui affiche tous les enfants directs de cette catégorie. Le slug vous permet de personnaliser la route de la page générée, qui par défaut est /category/[categoryName].
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Guides de Docusaurus',
description: 'En savoir plus sur les concepts Docusaurus les plus importants !',
slug: '/category/docusaurus-guides',
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
Voyez-la en action dans les pages des Guides Docusaurus.
Utilisez les liens generated-index comme moyen rapide d'obtenir un document d'introduction.
Lien de doc
Une catégorie peut créer un lien vers un document existant.
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'introduction'},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
Voyez-le en action dans la page d'introduction i18n.
Intégration de l'index généré dans une page de doc
Vous pouvez également intégrer la liste de cartes générée dans une page de doc ordinaire avec le composant DocCardList. Elle affichera tous les éléments de la barre latérale de la catégorie parente du document courant.
import DocCardList from '@theme/DocCardList';
<DocCardList />
📄️ Éléments de la barre latérale
Nous avons introduit trois types d'éléments dans l'exemple dans la section précédente autogenerated, que nous expliquerons plus en détail plus tard.
📄️ Autogenerated
Docusaurus peut créer une barre latérale automatiquement à partir de votre structure de système de fichiers : chaque dossier crée une catégorie de barre latérale et chaque fichier crée un lien de documentation.
📄️ Utiliser plusieurs barres latérales
Vous pouvez créer une barre latérale pour chaque ensemble de fichiers Markdown que vous souhaitez regrouper.
Catégories repliables
Nous prenons en charge l'option permettant de développer/réduire les catégories. Les catégories sont repliables par défaut, mais vous pouvez désactiver le pliage avec collapsible: false.
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
items: [
'creating-pages',
{
type: 'category',
collapsible: false,
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
Pour rendre toutes les catégories non pliables par défaut, définissez l'option sidebarCollapsible dans plugin-content-docs à false :
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
L'option dans sidebars.js a la priorité sur la configuration du plugin, il est donc possible de rendre certaines catégories pliables lorsque sidebarCollapsible est défini à false globalement.
Catégories développées par défaut
Les catégories repliables sont réduites par défaut. Si vous voulez qu'elles soient développées au premier rendu, vous pouvez définir collapsed à false :
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
Similaire à collapsible, vous pouvez également définir la configuration globale options.sidebarCollapsed à false. Les options individuelles collapsed dans sidebars.js auront toujours la priorité sur cette configuration.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
Lorsqu'une catégorie a collapsed : true mais collapsible : false (soit par sidebars.js, soit par la configuration du plugin), ce dernier prend le dessus et la catégorie est toujours rendue comme développée.
Utilisation de raccourcis
Vous pouvez exprimer les éléments typiques de la barre latérale sans beaucoup de personnalisation de manière plus concise avec des syntaxes de raccourci. Il y a deux parties à ceci : raccourci de doc et raccourci de catégorie.
Raccourci de doc
Un élément de type doc peut être simplement une chaîne représentant son ID :
- Longhand
- Shorthand
module.exports = {
sidebar: [
{
type: 'doc',
id: 'myDoc',
},
],
};
module.exports = {
sidebar: [
'myDoc',
],
};
Il est donc possible de simplifier l'exemple ci-dessus ainsi :
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Pour commencer',
items: [
'doc1',
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
'doc2',
'doc3',
],
},
{
type: 'link',
label: 'En savoir plus',
href: 'https://example.com',
},
],
};
Raccourci de catégorie
Un élément de catégorie peut être représenté par un objet dont la clé est son label, et la valeur est un tableau de sous-éléments.
- Longhand
- Shorthand
module.exports = {
sidebar: [
{
type: 'category',
label: 'Démarrage',
items: ['doc1', 'doc2'],
},
],
};
module.exports = {
sidebar: [
{
'Démarrage': ['doc1', 'doc2'],
},
],
};
Cela nous permet de simplifier cet exemple en :
module.exports = {
mySidebar: [
{
'Pour commencer': ['doc1'],
},
{
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'En savoir plus',
href: 'https://example.com',
},
],
};
Chaque objet raccourci après cette transformation contiendra exactement une entrée. Considérez maintenant l'exemple simplifié ci-dessous :
module.exports = {
mySidebar: [
{
'Pour commencer': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'En savoir plus',
href: 'https://example.com',
},
],
};
Notez comment les deux catégories consécutives sont comprimées en un seul objet avec deux entrées. Cette syntaxe génère une section de barre latérale : vous ne devez pas voir cet objet comme un élément en vrac - cet objet est déplié, chaque entrée devenant un élément distinct, et ils sont raccordés ensemble avec le reste des éléments (dans ce cas, le lien « En savoir plus ») pour former le niveau final de la barre latérale. Les sections de barres latérales sont également importantes lorsqu'on parle de barres latérales autogénérées.
Chaque fois que vous avez un tableau d'éléments qui est réduit à un arcccourci d'une catégorie, vous pouvez également omettre le tableau qui l'entoure.
- Before
- After
module.exports = {
sidebar: [
{
'Démarrage': ['doc1'],
Docusaurus: [
{
'Guides de base': ['doc2', 'doc3'],
'Guides avancés': ['doc4', 'doc5'],
},
],
},
],
};
module.exports = {
sidebar: {
'Démarrage': ['doc1'],
Docusaurus: {
'Guides de base': ['doc2', 'doc3'],
'Guides avancés': ['doc4', 'doc5'],
},
},
};