É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 :
export default {
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 sidebar_label du front matter Markdown 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 implicite de barre latérale. 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;
description?: string;
};
Exemple :
export default {
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 :
export default {
myHtmlSidebar: [
{
type: 'html',
value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
defaultStyle: true, // Use the default menu item styling
},
],
};
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 :
export default {
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;
description?: 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 :
export default {
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 :
export default {
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].
export default {
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 la page 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.
export default {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'introduction'},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
Voyez-la en action sur 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.
export default {
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 :
export default {
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 :
export default {
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.
export default {
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 éléments à ce sujet : raccourcis de doc et raccourcis de catégorie.
Raccourci de doc
Un élément de type doc peut être simplement une chaîne représentant son ID :
- Écriture courante
- Raccourci
export default {
sidebar: [
{
type: 'doc',
id: 'myDoc',
},
],
};
export default {
sidebar: [
'myDoc',
],
};
Il est donc possible de simplifier l'exemple ci-dessus ainsi :
export default {
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.
- Écriture courante
- Raccourci
export default {
sidebar: [
{
type: 'category',
label: 'Pour commencer',
items: ['doc1', 'doc2'],
},
],
};
export default {
sidebar: [
{
'Pour commencer': ['doc1', 'doc2'],
},
],
};
Cela nous permet de simplifier cet exemple en :
export default {
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 :
export default {
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
export default {
sidebar: [
{
'Démarrage': ['doc1'],
Docusaurus: [
{
'Guides de base': ['doc2', 'doc3'],
'Guides avancés': ['doc4', 'doc5'],
},
],
},
],
};
export default {
sidebar: {
'Démarrage': ['doc1'],
Docusaurus: {
'Guides de base': ['doc2', 'doc3'],
'Guides avancés': ['doc4', 'doc5'],
},
},
};