É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 :

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

remarque

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.

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.

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 :

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

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 :

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',
    },
  ],
};

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 :

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'],
      },
    ],
  },
};

Liens de catégorie

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 la page des Guides Docusaurus.

astuce

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.

sidebars.js

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.

docs/sidebar/index.md

import DocCardList from '@theme/DocCardList';

<DocCardList />

http://localhost:3000

📄️ É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.

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 é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

sidebars.js

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

Raccourci

sidebars.js

export default {
  sidebar: [
    '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.

Écriture courante

sidebars.js

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

Raccourci

sidebars.js

export default {
  sidebar: [
    {
      'Pour commencer': ['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.

Avant

sidebars.js

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

Après

sidebars.js

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