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.

info

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)

http://localhost:3000

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

http://localhost:3000

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>

http://localhost:3000

Exemple d'élément de détails

Changez-moi !

Ceci est le contenu détaillé

Détail imbriqué ! Quelques surprises à l'intérieur...

😲😲😲😲😲

remarque

En pratique, il ne s'agit pas vraiment d'éléments HTML, mais d'éléments React JSX, que nous aborderons ensuite !