Aller au contenu principal
Version : 2.0.0-beta.21 🚧

Introduction de la documentation

La fonction de documentation fournit aux utilisateurs un moyen d'organiser les fichiers Markdown dans un format hiérarchique.

info

Consultez la documentation de référence de l'API du plugin des docs pour une liste exhaustive des options.

ID du document

Chaque document a un id unique. Par défaut, l'id d'un document est le nom du document (sans l'extension) relatif au répertoire racine de la documentation.

Par exemple, greeting.md a pour id greeting et guide/hello.md a pour id guide/hello.

website # Répertoire racine de votre site
└── docs
├── greeting.md
└── guide
└── hello.md

Cependant, la dernière partie de l'id peut être définie par l'utilisateur dans la partie supérieure. Par exemple, si le contenu de guide/hello.md est défini comme ci-dessous, son id final est guide/part1.

---
id: part1
---

Lorem ipsum

Personnalisation des URL de doc

Par défaut, l'emplacement de l'URL d'un document est son chemin de fichier relatif au dossier docs. Utilisez slug du frontmatter pour modifier l'URL d'un document.

Par exemple, supposons que la structure de votre site ressemble à ceci :

website # Répertoire racine de votre site
└── docs
└── guide
└── hello.md

Par défaut hello.md sera disponible à /docs/guide/hello. Vous pouvez changer l'emplacement de son URL en /docs/bonjour :

---
slug: /bonjour
---

Lorem ipsum

slug sera ajouté au routeBasePath du plugin doc, qui est /docs par défaut. Consultez Mode Docs uniquement pour savoir comment supprimer la partie /docs de l'URL.

remarque

Il est possible d'utiliser :

  • des slugs absolus : slug: /mySlug, slug: /...
  • des slugs relatifs : slug: mySlug, slug: ./../mySlug...

Docs de la page d'accueil

Si vous voulez qu'un document soit disponible à la racine, et que vous avez un chemin comme https://docusaurus.io/docs/, vous pouvez utiliser le slug du frontmatter :

---
id: my-home-doc
slug: /
---

Lorem ipsum

Mode Docs-uniquement

Un site Docusaurus récemment initialisé a la structure suivante :

example.com/                                -> généré à partir de `src/pages/index.js`

example.com/docs/intro -> généré à partir de `docs/intro.md`
example.com/docs/tutorial-basics/... -> généré à partir de `docs/tutorial-basics/...`
...

example.com/blog/2021/08/26/welcome -> généré à partir de `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post -> généré à partir de `blog/2021-08-01-mdx-blog-post.mdx`
...

Toutes les docs seront servis sous la sous route docs/. Mais que se passe-t-il si votre site n'a que des docs, ou si vous voulez prioriser vos docs en les plaçant à la racine ?

Supposons que vous ayez les éléments suivants dans votre configuration :

docusaurus.config.js
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
/* options du plugin docs */
},
blog: {
/* options du plugin blog */
},
// ...
},
],
};

Pour entrer en mode docs-uniquement, changez le comme ceci :

docusaurus.config.js
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
routeBasePath: '/', // Sert les docs à la racine du site
/* autres options du plugin docs */
},
blog: false, // Facultatif : désactive le plugin du blog
// ...
},
],
};

Notez que vous ne devez pas nécessairement renoncer à utiliser les plugins de blog ou autres ; tout ce que fait routeBasePath: '/', c'est qu'au lieu de servir les documents par l'intermédiaire de https://example.com/docs/some-doc, ils sont maintenant à la racine du site : https://example.com/some-doc. Le blog, s'il est activé, peut toujours être consulté via la sous-route blog/.

N'oubliez pas de mettre une page à la racine (https://example.com/) en ajoutant le frontmatter :

docs/intro.md
---
slug: /
---

Cette page sera la page d'accueil lorsque les utilisateurs visiteront https://example.com/.
attention

Si vous avez ajouté slug: / à un doc pour en faire la page d'accueil, vous devez supprimer la page d'accueil existante à . src/pages/index.js, sinon il y aura deux fichiers correspondant à la même route !

Maintenant, la structure du site sera comme ceci :

example.com/                       -> généré à partir de `docs/intro.md`
example.com/tutorial-basics/... -> généré à partir de `docs/tutorial-basics/...`
...
astuce

Il y a aussi un « mode blog-uniquement » pour ceux qui ne veulent utiliser que la fonction blog de Docusaurus 2. Vous pouvez utiliser la même méthode décrite ci-dessus. Suivez les instructions de configuration sur le mode Blog-only.