Fonctionnalités Markdown
La documentation est l'une des interactions entre votre produit et vos utilisateurs. Un ensemble de documents bien écrit et bien organisé aide vos utilisateurs à comprendre rapidement votre produit. Notre objectif est ici d'aider vos utilisateurs à trouver et à comprendre les informations dont ils ont besoin, le plus rapidement possible.
Docusaurus 2 utilise des outils modernes pour vous aider à composer facilement votre documentation intéractive. Vous pouvez intégrer des composants React, ou construire des blocs de codage en ligne dans lesquels vos utilisateurs peuvent jouer avec le code sur place. Commencez à partager vos moments de créativité avec le code dont votre public ne peut se passer. C'est peut-être le moyen le plus efficace d'attirer des utilisateurs potentiels.
Cette section suppose que vous utilisez les plugins officiels de contenu Docusaurus.
Fonctionnalités standard
Markdown est une syntaxe vous permettant d'écrire du contenu formaté dans une syntaxe lisible.
Nous utilisons MDX comme moteur d'analyse, qui peut faire bien plus que d'analyser la syntaxe standard de Markdown, comme le rendu des composants React à l'intérieur de vos documents.
### Ma section du Doc
Message « Hello world » avec du texte en **gras**, du texte en _italique_ et un [link](/)
![img alt](/img/docusaurus.png)
Ma section du Doc
Message « Hello world » avec du texte en gras, du texte en italique et un lien
Markdown est déclaratif
Certains peuvent supposer une correspondance de 1 pour 1 entre Markdown et HTML, par exemple, ![Preview](/img/docusaurus.png)
deviendra toujours <img src="/img/docusaurus.png" alt="Preview" />
, tel quel. Cependant, ce n'est pas le cas.
La syntaxe Markdown ![message](url)
indique seulement de manière déclarative à Docusaurus qu'une image doit être insérée ici, mais nous pouvons faire d'autres choses comme transformer un chemin de fichier en chemin d'URL, donc le balisage généré peut différer de la sortie d'autres moteurs de rendu Markdown, ou d'une transcription manuelle naïve vers le code JSX/HTML équivalent.
En général, vous ne devez assumer que la sémantique du balisage (les délimitations ```
deviennent des blocs de code et les >
deviennent des citations, etc.), mais pas la sortie compilée.
Front matter
Le frontmatter est utilisé pour ajouter des métadonnées à votre fichier Markdown. Tous les plugins de contenu ont leur propre schéma de frontmatter, et utilisent le frontmatter pour enrichir les métadonnées par défaut déduites du contenu ou d'une autre configuration.
Le frontmatter est fourni en haut du fichier, entourée de trois tirets ---
. Le contenu est analysé comme du YAML.
---
title: Mon titre de doc
plus_de_donnees:
- peut être fourni
- comme: objets
ou: tableaux
---
Citations
Les citations Markdown sont joliment stylisées :
> Site de Documentation Open Source facile à maintenir.
>
> — Docusaurus
Site de Documentation Open Source facile à maintenir.
— Docusaurus
Détails
Markdown peut intégrer des éléments HTML, et les éléments HTML details
sont joliment stylisés :
### Exemple d'élément de détails
<details>
<summary>Changez-moi !</summary>
<div>
<div>Ceci est le contenu détaillé</div>
<br/>
<details>
<summary>
Détail imbriqué ! Quelques surprises à l'intérieur...
</summary>
<div>😲😲😲😲😲</div>
</details>
</div>
</details>
Exemple d'élément de détails
Changez-moi !
Détail imbriqué ! Quelques surprises à l'intérieur...
En pratique, il ne s'agit pas vraiment d'éléments HTML, mais d'éléments React JSX, que nous aborderons ensuite !