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.

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // Dossier source pour générer la barre latérale (relative à docs)
};

Docusaurus peut générer une barre latérale complète à partir de votre dossier docs :

sidebars.js

module.exports = {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' signifie le dossier docs courant
    },
  ],
};

Un élément autogenerated est converti par Docusaurus en une section de barre latérale (également abordée dans raccourci de catégorie)  : une liste d'éléments de type doc ou category, de sorte que vous pouvez éclater plusieurs éléments autogenerated depuis plusieurs répertoires, en les intercalant avec des éléments de barre latérale ordinaires, dans un seul niveau de barre latérale.

Un exemple réel

Considérer cette structure de fichiers :

docs
├── api
│   ├── product1-api
│   │   └── api.md
│   └── product2-api
│       ├── basic-api.md
│       └── pro-api.md
├── intro.md
└── tutorials
    ├── advanced
    │   ├── advanced1.md
    │   ├── advanced2.md
    │   └── read-more
    │       ├── resource1.md
    │       └── resource2.md
    ├── easy
    │   ├── easy1.md
    │   └── easy2.md
    ├── tutorial-end.md
    ├── tutorial-intro.md
    └── tutorial-medium.md

Supposons que chaque identifiant de la documentation ne soit que son nom de fichier. Si vous définissez une barre latérale générée automatiquement comme ceci :

sidebars.js

module.exports = {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        {
          type: 'autogenerated',
          dirName: 'tutorials/easy', // Génère une barre latérale à partir de docs/tutorials/easy
        },
        'tutorial-medium',
        {
          type: 'autogenerated',
          dirName: 'tutorials/advanced', // Génère une barre latérale à partir de docs/tutorials/hard
        },
        'tutorial-end',
      ],
    },
    {
      type: 'autogenerated',
      dirName: 'api', // Génère une barre latérale à partir de docs/api
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

Elle serait résolue ainsi :

sidebars.js

module.exports = {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        // Deux fichiers dans docs/tutorials/easy
        'easy1',
        'easy2',
        'tutorial-medium',
        // Deux fichiers et un dossier dans docs/tutorials/hard
        'advanced1',
        'advanced2',
        {
          type: 'category',
          label: 'read-more',
          items: ['resource1', 'resource2'],
        },
        'tutorial-end',
      ],
    },
    // Deux dossiers dans docs/api
    {
      type: 'category',
      label: 'product1-api',
      items: ['api'],
    },
    {
      type: 'category',
      label: 'product2-api',
      items: ['basic-api', 'pro-api'],
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

Notez que les répertoires de sources générés automatiquement ne deviennent pas des catégories : seuls les éléments qu'ils contiennent le sont. C'est ce que nous entendons par « section de barre latérale ».

Convention d'indexation des catégories

Docusaurus peut lier automatiquement une catégorie à son document d'index.

Un document d'index de catégorie est un document qui suit l'une de ces conventions de nom de fichier :

• Nommé comme index (insensible à la casse) : docs/Guides/index.md
• Nommé comme README (insensible à la casse) : docs/Guides/README.mdx
• Même nom que le dossier parent : docs/Guides/Guides.md

Cela revient à utiliser une catégorie avec un lien de doc :

sidebars.js

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'Guides/index'},
      items: [],
    },
  ],
};

astuce

Le fait de nommer votre document d'introduction README.md le fait apparaître lorsque vous parcourez le dossier à l'aide de l'interface GitHub, tandis que l'utilisation de index.md rend le comportement plus conforme à la façon dont les fichiers HTML sont servis.

astuce

Si un dossier n'a qu'une page d'index, il sera transformé en lien au lieu d'une catégorie. Ceci est utile pour la collocation des ressources :

some-doc
├── index.md
├── img1.png
└── img2.png

Personnalisation de l'indexation des catégories

Il est possible d'exclure n'importe laquelle des conventions de l'index des catégories, ou de définir encore plus de conventions. Vous pouvez injecter votre propre isCategoryIndex dans le callback sidebarItemsGenerator. Par exemple, vous pouvez également choisir intro comme autre nom de fichier éligible pour devenir automatiquement l'index de la catégorie.

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // L'implémentation par défaut du sélecteur, donnée ci-dessous
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex(doc) {
              return (
                // Choisissez également intro.md en plus de ceux par défaut
                doc.fileName.toLowerCase() === 'intro' ||
                defaultCategoryIndexMatcher(doc)
              );
            },
          });
        },
      },
    ],
  ],
};

Ou choisir de ne pas avoir de convention d'index de catégorie.

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // L'implémentation par défaut du sélecteur, donnée ci-dessous
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex() {
              // Aucun doc ne sera automatiquement choisi comme index de catégorie
              return false;
            },
          });
        },
      },
    ],
  ],
};

Le sélecteur isCategoryIndex sera fournie avec trois champs :

• fileName, le nom du fichier sans extension et avec la casse préservée
• directories, la liste des noms de répertoires du niveau le plus bas au niveau le plus haut, par rapport au répertoire racine des docs
• extension, l'extension du fichier, avec un point au début.

Par exemple, pour un fichier doc guides/sidebar/autogenerated.md, les props que le sélecteur reçoit sont

const props = {
  fileName: 'autogenerated',
  directories: ['sidebar', 'guides'],
  extension: '.md',
};

L'implémentation par défaut est :

function isCategoryIndex({fileName, directories}) {
  const eligibleDocIndexNames = [
    'index',
    'readme',
    directories[0].toLowerCase(),
  ];
  return eligibleDocIndexNames.includes(fileName.toLowerCase());
}

Métadonnées de la barre latérale générées automatiquement

Pour les définitions de barres latérales écrites à la main, vous fournirez des métadonnées aux éléments de la barre latérale par le biais de sidebars.js; pour les définitions « autogenerated », Docusaurus les lira à partir du fichier respectif de l'élément. En plus, vous voudrez peut-être ajuster la position relative de chaque élément car par défaut, les éléments à l'intérieure d'une section d'une barre latérale seront générés dans l'ordre alphabétique (en utilisant les noms des fichiers et des dossiers).

Métadonnées de l'élément doc

Les attributs label, className, et customProps sont déclarés respectivement dans le front matter sous sidebar_label, sidebar_class_name et sidebar_custom_props. La position peut être spécifiée de la même manière, dans le font matter via sidebar_position.

docs/tutorials/tutorial-easy.md

---
sidebar_position: 2
sidebar_label: Facile
sidebar_class_name: green
---

# Tutoriel facile

C'est le tutoriel facile !

Métadonnées de l'élément de category

Ajouter un fichier _category_.json ou _category_.yml dans le dossier respectif. Vous pouvez spécifier les métadonnées de la catégorie ainsi que les métadonnées de la position. label, className, position, et customProps seront par défaut les valeurs respectives du doc liée à la catégorie, s'il y en a une.

JSON

docs/tutorials/_category_.json

{
  "position": 2.5,
  "label": "Tutoriel",
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "Aperçu du tutoriel"
  },
  "customProps": {
    "description": "Cette description peut être utilisée dans le DocCard swizzlé"
  }
}

YAML

docs/tutorials/_category_.yml

position: 2.5 # la position flottante est prise en charge
label: 'Tutoriel'
collapsible: true # rend la catégorie repliable
collapsed: false # garde la catégorie ouverte par défaut
className: red
link:
  type: generated-index
  title: Aperçu du tutoriel
customProps:
  description: Cette description peut être utilisée dans le DocCard swizzlé

info

Si le link est explicitement spécifié, Docusaurus n'appliquera aucune convention par défaut.

Les liens vers les docs peuvent être spécifiés de manière relative, par exemple, si la catégorie est générée avec le répertoire guides, "link": {"type": "doc", "id": "intro"} sera résolu vers l'ID guides/intro, ne retombant sur intro que si un doc avec l'ancien ID n'existe pas.

Vous pouvez également utiliser link: null pour ne pas respecter les conventions par défaut et ne pas générer de page d'index de catégorie.

info

Les métadonnées de position ne sont utilisées qu'à l'intérieur d'une section de barre latérale : Docusaurus ne réorganise pas les autres éléments de votre barre latérale.

Utilisation des préfixes de nombre

Une façon simple d'ordonner une barre latérale générée automatiquement est de préfixer les documents et les dossiers par des préfixes numériques, ce qui les fait également apparaître dans le système de fichiers dans le même ordre lorsqu'ils sont triés par nom de fichier :

docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Hard
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md

Pour faciliter son adoption, Docusaurus prend en charge plusieurs formats de préfixes numériques.

Par défaut, Docusaurus supprimera le préfixe de nombre de l'identifiant du doc, du titre, du libellé et des chemins de l'URL.

attention

Préférez l'utilisation de métadonnées supplémentaires.

Mettre à jour un préfixe de nombres peut être ennuyeux, car cela peut nécessiter la mise à jour de plusieurs liens Markdown existants :

docs/02-Tutorial Easy/01-First Part.md

- Check the [Tutorial End](../04-End.mdx);
+ Check the [Tutorial End](../05-End.mdx);

Personnalisation du générateur d'éléments de la barre latérale

Vous pouvez fournir une fonction personnalisée sidebarItemsGenerator dans la configuration du plugin docs (ou du preset) :

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          defaultSidebarItemsGenerator,
          numberPrefixParser,
          item,
          version,
          docs,
          categoriesMetadata,
          isCategoryIndex,
        }) {
          // Exemple : retourne une liste codée en dur des éléments statiques de la barre latérale
          return [
            {type: 'doc', id: 'doc1'},
            {type: 'doc', id: 'doc2'},
          ];
        },
      },
    ],
  ],
};

astuce

Réutiliser et améliorer le générateur par défaut au lieu d'écrire un générateur à partir de zéro : le générateur par défaut que nous fournissons fait 250 lignes de long.

Ajoutez, mettez à jour, filtrez, réordonnez les éléments de la barre latérale en fonction de votre cas d'utilisation :

docusaurus.config.js

// Inverse l'ordre des éléments de la barre latérale (y compris les éléments de catégorie imbriqués)
function reverseSidebarItems(items) {
  // Inverse les éléments dans la catégorie
  const result = items.map((item) => {
    if (item.type === 'category') {
      return {...item, items: reverseSidebarItems(item.items)};
    }
    return item;
  });
  // Inverse les éléments du niveau actuel
  result.reverse();
  return result;
}

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return reverseSidebarItems(sidebarItems);
        },
      },
    ],
  ],
};