Aller au contenu principal
Version: Canary 🚧

Fonctionnalités Markdown

Docusaurus utilise Markdown comme principal format de création de contenu.

Apprendre le Markdown

Docusaurus utilise des outils modernes pour vous aider à créer une documentation interactive.

Le compilateur MDX transforme les fichiers Markdown en composants, et vous permet d'utiliser le JSX dans votre contenu Markdown. Cela vous permet d'intercaler facilement des composants React dans votre contenu et de créer des expériences d'apprentissage agréables.

Utilisez le terrain de jeu MDX

Le terrain de jeu MDX est votre nouveau meilleur ami !

C'est un outil de débogage très utile qui montre comment le compilateur MDX transforme Markdown en React.

Options : sélectionnez le bon format (MDX ou CommonMark) et les plugins suivants que Docusaurus utilise : remark-gfm, remark-directive, rehype-raw.

MDX vs. CommonMark

Docusaurus compile les fichiers .md et .mdx en composants React en utilisant le compilateur MDX, mais la syntaxe peut être interprétée différemment en fonction de vos paramètres.

Le compilateur MDX prend en charge 2 formats :

  • Le format MDX : un analyseur puissant permettant l'utilisation de JSX
  • Le format CommonMark : un analyseur Markdown conforme à la norme qui n'autorise pas l'utilisation de JSX

Par défaut, Docusaurus v3 utilise le format MDX pour tous les fichiers (y compris les fichiers .md) pour des raisons historiques.

Il est possible d'opter pour CommonMark en utilisant le paramètre siteConfig.markdown.format ou le format : md du front matter.

comment utiliser CommonMark

Si vous prévoyez d'utiliser CommonMark, nous vous recommandons le paramètre siteConfig.markdown.format: 'detect'. Le format approprié sera sélectionné automatiquement, basé sur les extensions de fichier :

  • Les fichiers .md utiliseront le format CommonMark
  • Les fichiers .mdx utiliseront le format MDX

Fonctionnalités standard

Markdown est une syntaxe vous permettant d'écrire du contenu formaté dans une syntaxe lisible.

### 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

img alt

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
---
info

La documentation de l'API de chaque plugin officiel énumère les attributs pris en charge :

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>Basculez moi !</summary>
<div>
<div>Voici le contenu détaillé</div>
<br/>
<details>
<summary>
Interrupteur imbriqué ! Quelques surprises à l'intérieur...
</summary>
<div>😲😲😲😲😲</div>
</details>
</div>
</details>
http://localhost:3000

Exemple d'élément de détails

Basculez moi !
Voici le contenu détaillé

Interrupteur imbriqué ! Quelques surprises à l'intérieur...

😲😲😲😲😲