Créer un doc
Créez un fichier Markdown greeting.md et placez-le dans le répertoire docs.
website # répertoire racine de votre site
├── docs
│ └── greeting.md
├── src
│ └── pages
├── docusaurus.config.js
├── ...
---
description: Créer une page de documentation avec un contenu riche.
---
# Bonjour de la part de Docusaurus
Êtes-vous prêt à créer le site de documentation de votre projet open source ?
## Les titres
apparaîtront dans la table des matières en haut à droite
Ainsi, vos utilisateurs sauront de quoi il s'agit sans avoir à faire défiler la page ou même sans la lire.
## Par défaut, seuls les h2 et h3 figureront dans la table des matières.
Vous pouvez configurer les niveaux de titres de la table des matières soit par document, soit dans la configuration du thème.
Les titres sont bien espacés de manière à ce que la hiérarchie soit claire.
- Les listes vous aideront à
- présenter les points clés
- que vous voulez que vos utilisateurs retiennent
- et vous pouvez les imbriquer
- plusieurs fois
Tous les fichiers préfixés par un underscore (_) sous le répertoire docs sont traités comme des pages « partielles » et seront ignorés par défaut.
Pour en savoir plus sur l'importation de pages partielles.
Front matter du Doc
Le front matter est utilisé pour fournir des métadonnées supplémentaires pour votre page de doc. Le frontmatter est optionnel — Docusaurus pourra déduire toutes les métadonnées nécessaires sans le frontmatter. Par exemple, la fonctionnalité des tags de doc introduite ci-dessous nécessite l'utilisation du front matter. Pour connaître tous les champs possibles, consultez la documentation de l'API.
Tags de doc
En option, vous pouvez ajouter des tags à vos pages de docs, ce qui introduit une autre dimension de catégorisation en plus de la barre latérale des docs. Les tags sont passés dans le frontmatter comme une liste de libellés :
---
id: doc-with-tags
title: Un doc avec des tags
tags:
- Démo
- Pour commencer
---
Les tags peuvent également être déclarés avec tags: [Demo, Pour commencer].
Pour en savoir plus sur toutes les syntaxes de tableau Yaml.
Organisation de la structure des dossiers
La façon dont les fichiers Markdown sont organisés sous le dossier docs peut avoir plusieurs impacts sur la génération de contenu Docusaurus. Cependant, la plupart d'entre eux peuvent être découplés de la structure des fichiers.
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 le front matter. 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
L'ID est utilisé pour faire référence à un document lors de l'écriture manuelle de barres latérales ou lors de l'utilisation de composants ou de hooks liés à la mise en page de la documentation.
URL du doc
Par défaut, l'emplacement de l'URL d'un document est son chemin de fichier relatif au dossier docs. Utilisez slug du front matter 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 dans /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 le Mode Docs uniquement pour savoir comment supprimer la partie /docs de l'URL.
Il est possible d'utiliser :
- des slugs absolus :
slug: /mySlug,slug: /... - des slugs relatifs :
slug: mySlug,slug: ./../mySlug...
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 front matter :
---
id: my-home-doc
slug: /
---
Lorem ipsum
Barres latérales
Lors de l'utilisation de barres latérales générées automatiquement, la structure du fichier déterminera la structure de la barre latérale.
Notre recommandation pour l'organisation du système de fichiers est la suivante : faites en sorte que votre système de fichiers reflète la structure de la barre latérale (afin de ne pas avoir à écrire à la main votre fichier sidebars.js), et utilisez slug du front matter pour personnaliser les URL de chaque document.