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 :
export default {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' signifie le dossier docs actuel
},
],
};
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 :
export default {
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/advanced
},
'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 :
export default {
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/advanced
'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 :
export default {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'Guides/index'},
items: [],
},
],
};
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.
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.
export default {
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.
export default {
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éedirectories
, la liste des noms de répertoires du niveau le plus bas au niveau le plus haut, par rapport au répertoire racine des docsextension
, 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
.
---
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
- YAML
{
"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é"
}
}
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é
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.
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 Advanced
│ ├── 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.
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 :
- 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) :
export default {
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'},
];
},
},
],
],
};
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 :
// 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;
}
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
const sidebarItems = await defaultSidebarItemsGenerator(args);
return reverseSidebarItems(sidebarItems);
},
},
],
],
};