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
Prise en charge expérimentale de CommonMark

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](/)

![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 :

améliorez votre front matter

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.

docusaurus.config.js
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
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 :

### Details element example

<details>
<summary>Toggle me!</summary>

This is the detailed content

```js
console.log("Markdown features including the code block are available");
```

You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
<details>
<summary>Nested toggle! Some surprise inside...</summary>

😲😲😲😲😲
</details>
</details>
http://localhost:3000

Details element example

Toggle me!

This is the detailed content

console.log("Markdown features including the code block are available");

You can use Markdown here including bold and italic text, and inline link

Nested toggle! Some surprise inside...

😲😲😲😲😲

info
  • You should not break lines between the starting or ending tag of the <summary> element and its content or an extra <p> element is inserted.
  • Blank lines between the <summary> element and the first paragraph of the detailed content are optional in Docusaurus but strongly recommended to ensure MDX portability with other site generators.
  • Blank lines between the nested <details> element and the paragraphs just around it are optional.