Fonctionnalités Markdown
Docusaurus utilise Markdown comme principal format de création de contenu.
Vous pouvez apprendre Markdown en 10 minutes.
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.
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.
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
.mdutiliseront le format CommonMark - Les fichiers
.mdxutiliseront le format MDX
La prise en charge de CommonMark est expérimentale et présente actuellement quelques limitations.
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](/)
Markdown est déclaratif
Certains peuvent supposer une correspondance de 1 pour 1 entre Markdown et HTML, par exemple,  deviendra toujours <img src="/img/docusaurus.png" alt="Preview" />, tel quel. Cependant, ce n'est pas le cas.
La syntaxe Markdown  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
---
La documentation de l'API de chaque plugin officiel énumère les attributs pris en charge :
Utilisez la fonction parseFrontMatter de la config du Markdown pour fournir votre propre analyseur de contenu ou pour améliorer l'analyseur par défaut.
Il est possible de réutiliser l'analyseur par défaut et de l'intégrer à votre propre logique propriétaire. Cela permet de mettre en œuvre des transformations pratiques du front matter, des raccourcis, ou de s'intégrer à des systèmes externes utilisant le front matter que les plugins de Docusaurus ne prennent pas en charge.
export default {
markdown: {
parseFrontMatter: async (params) => {
// Réutiliser l'analyseur par défaut
const result = await params.defaultParseFrontMatter(params);
// Traiter les placeholders de description de la page de garde
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// Créer votre propre raccourci pour les pages de garde
if (result.frontMatter.i_do_not_want_docs_pagination) {
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// Renommer un front matter non supporté provenant d'un autre système
if (result.frontMatter.cms_seo_summary) {
result.frontMatter.description = result.frontMatter.cms_seo_summary;
delete result.frontMatter.cms_seo_summary;
}
return result;
},
},
};
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>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>