Aller au contenu principal
Version: Canary 🚧

É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

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 :

sidebars.js
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 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.

remarque

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.

astuce

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.

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 :

sidebars.js
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
    },
  ],
};

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 :

sidebars.js
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
    },
  ],
};
astuce

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 :

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Concepts de base',
      className: 'sidebar-title',
    },
  ],
};

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 :

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};
astuce

Utilisez la syntaxe raccourci lorsque vous n'avez pas besoin de personnalisations :

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

Avec les liens de catégorie, un clic sur une catégorie peut vous faire accéder à une autre page.

astuce

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].

sidebars.js
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 les pages des Guides Docusaurus.

astuce

Utilisez les liens generated-index comme moyen rapide d'obtenir un document d'introduction.

Une catégorie peut créer un lien vers un document existant.

sidebars.js
export default {
  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.

docs/sidebar/index.md
import DocCardList from '@theme/DocCardList';

<DocCardList />
http://localhost:3000

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.

sidebars.js
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 :

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};
remarque

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 :

sidebars.js
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.

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};
attention

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 :

sidebars.js
export default {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

Il est donc possible de simplifier l'exemple ci-dessus ainsi :

sidebars.js
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.

sidebars.js
export default {
  sidebar: [
    {
      type: 'category',
      label: 'Pour commencer',
      items: ['doc1', 'doc2'],
    },
  ],
};

Cela nous permet de simplifier cet exemple en :

sidebars.js
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 :

sidebars.js
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.

sidebars.js
export default {
  sidebar: [
    {
      'Démarrage': ['doc1'],
      Docusaurus: [
        {
          'Guides de base': ['doc2', 'doc3'],
          'Guides avancés': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};