MDX et React
Utilisation de JSX dans le Markdown
Docusaurus a un support intégré pour MDX v1, ceci vous permet d'écrire du JSX dans vos fichiers Markdown et de les rendre sous forme de composants React.
Bien que Docusaurus analyse les fichiers .md
et .mdx
en utilisant MDX, certaines syntaxes sont traitées légèrement différemment par des outils tiers. Pour une analyse syntaxique plus précise et un meilleur support des éditeurs, nous recommandons d'utiliser l'extension .mdx
pour les fichiers contenant de la syntaxe MDX.
Consultez les docs MDX pour voir ce que vous pouvez faire avec MDX.
Exportation des composants
Pour définir un composant personnalisé dans un fichier MDX, vous devez l'exporter : seuls les paragraphes qui commencent par export
seront analysés comme des composants au lieu de prose.
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus vert</Highlight> et <Highlight color="#1877F2">Facebook bleu</Highlight> sont mes couleurs préférées.
Je peux écrire du **Markdown** à côté de mon _JSX_ !
Remarquez comment il rend à la fois le balisage de votre composant React et la syntaxe Markdown :
Je peux écrire du Markdown à côté de mon JSX !
Puisque tous les fichiers doc sont analysés en utilisant MDX, tout ce qui ressemble au HTML est en fait du JSX. Par conséquent, si vous devez donner un style en ligne à un composant, suivez le modèle JSX et fournissez des objets de style.
/* Au lieu de cela : */
<span style="background-color: red">Foo</span>
/* Utilisez ceci : */
<span style={{backgroundColor: 'red'}}>Foo</span>
Ce comportement est différent de Docusaurus 1. Consultez également la section Migration de la v1 vers la v2.
De plus, MDX n'est pas 100% compatible avec CommonMark. Utilisez le terrain de jeu MDX pour vous assurer que votre syntaxe est valide en MDX.
Importation des composants
Vous pouvez également importer vos propres composants définis dans d'autres fichiers ou composants tiers installés via npm.
<!-- Composant du thème Docusaurus -->
import TOCInline from '@theme/TOCInline';
<!-- Composant externe -->
import Button from '@mui/material/Button';
<!-- Composant personnalisé -->
import BrowserWindow from '@site/src/components/BrowserWindow';
L'alias @site
pointe vers le répertoire de votre site web, habituellement où se trouve le fichier docusaurus.config.js
. L'utilisation d'un alias au lieu des chemins relatifs ('../.. src/components/BrowserWindow'
) vous évite de mettre à jour les chemins d'importation lors du déplacement des fichiers, de la documentation versionnée et de la traduction.
Si la déclaration de composants dans le format Markdown est très pratique pour les cas simples, elle devient difficile à maintenir en raison de la prise en charge limitée des éditeurs, des risques d'erreurs d'analyse et de la faible réutilisation. Utilisez un fichier .js
séparé lorsque votre composant implique une logique JavaScript complexe :
import React from 'react';
export default function Highlight({children, color}) {
return (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
}
import Highlight from '@site/src/components/Highlight';
<Highlight color="#25c2a0">Docusaurus vert</Highlight>
Si vous utilisez le même composant dans un grand nombre de fichiers, vous n'avez pas besoin de l'importer partout, pensez à l'ajouter à la portée globale. Voir ci-dessous
Portée des composants MDX
En plus de l'importation d'un composant et l'exportation d'un composant, une troisième façon d'utiliser un composant dans MDX est de l'enregistrer dans la portée globale, qui le rendra automatiquement disponible dans tous les fichiers MDX, sans aucune instruction d'importation.
Par exemple, à partir de ce fichier MDX :
- une
- liste !
Et quelques <Highlight>balisage personnalisé</Highlight>...
Il sera compilé à un composant React contenant des éléments ul
, li
, p
et Highlight
. Highlight
n'est pas un élément html natif : vous devez fournir votre propre implémentation de composants React pour lui.
Dans Docusaurus, la portée du composant MDX est fournie par le fichier @theme/MDXComponents
. Ce n'est pas un composant React, en soi, contrairement à la plupart des autres exportations sous l'alias @theme/
: c'est un enregistrement de noms de balises comme Highlight
vers leurs implémentations de composants React.
Si vous swizzlez ce composant, vous trouverez toutes les balises qui ont été implémentées, et vous pouvez personnaliser davantage notre implémentation en swizzlant les sous-composants respectifs, comme @theme/MDXComponents/Code
(qui est utilisé pour implémenter la fonctionnalité Blocs de code Markdown).
Si vous souhaitez enregistrer des noms de balises supplémentaires (comme la balise <Highlight>
ci-dessus), vous devez envisager d'envelopper @theme/MDXComponents
, afin de ne pas avoir à maintenir tous les correspondances existantes. Puisque le CLI swizzle n'autorise pas encore l'enveloppe des fichiers non-composants, vous devriez créer manuellement l'enveloppe :
import React from 'react';
// Importe le mapper original
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';
export default {
// Réutilise la correspondance par défaut
...MDXComponents,
// Ajoute la balise "highlight" à notre composant <Highlight> };
// `Highlight` recevra tous les props qui ont été passés à `<Highlight>` dans MDX
Highlight,
};
Et maintenant, vous pouvez librement utiliser <Highlight>
dans chaque page, sans écrire l'instruction d'importation :
Je peux facilement utiliser <Highlight color="#25c2a0">Docusaurus vert</Highlight> partout !
Je peux utiliser facilement Docusaurus vert partout !
Nous utilisons des noms de balises en majuscules comme Highlight
.
A partir de MDX v2+ (Docusaurus v3+), les noms de balises minuscules sont toujours affichés en tant qu'éléments html natifs et n'utiliseront aucun mapping de composants que vous fournirez.
Cette fonctionnalité est propulsée par un fournisseur de wrapper. Si vous importez Markdown dans une page React, vous devez fournir ce fournisseur vous-même via le composant de thème MDXContent
.
import React from 'react';
import FeatureDisplay from './_featureDisplay.mdx';
import MDXContent from '@theme/MDXContent';
export default function LandingPage() {
return (
<div>
<MDXContent>
<FeatureDisplay />
</MDXContent>
</div>
);
}
Si vous n'enveloppez pas votre MDX importé avec MDXContent
, la portée globale ne sera pas disponible.
Interopérabilité de Markdown et JSX
Docusaurus v2 utilise MDX v1, qui a beaucoup de cas connus où le contenu ne peut pas être correctement analysé comme du Markdown. Utilisez le terrain de jeu MDX pour vous assurer que votre syntaxe est valide en MDX.
Exemples d'échecs d'analyse
Un paragraphe commençant par une balise JSX sera entièrement vu comme une chaîne JSX :
- Problème
- Solution de contournement
<span style={{color: 'red'}}>Texte mis en évidence</span> mais ensuite _Markdown_ **ne fonctionne pas**
Texte mis en évidence mais ensuite Markdown ne fonctionne pas
Utilisez JSX pour le reste de la ligne, ou préfixez la ligne avec du texte brut :
<span style={{color: 'red'}}>Utiliser du JSX pour le paragraphe</span> afin de ne plus <i>se soucier</i> du <b>Markdown</b>
​<span style={{color: 'red'}}>