É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" />', // 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 :
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.