MDX et React

Utilisation de JSX dans Markdown

Docusaurus a un support intégré pour MDX, ceci vous permet d'écrire du JSX dans vos fichiers Markdown et de les rendre sous forme de composants React.

remarque

Bien que les fichiers .md et .mdx soient analysés à l'aide de MDX, certaines syntaxes sont traitées de manière légèrement différente. 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.

caution

MDX n'est pas 100% compatible avec CommonMark.

Utilisez le terrain de jeu de MDX pour vous assurer que votre syntaxe est un MDX valide.

Essayez ce bloc ici :

export const Highlight = ({children, color}) => (  <span    style={{      backgroundColor: color,      borderRadius: '2px',      color: '#fff',      padding: '0.2rem',    }}>    {children}  </span>);
<Highlight color="#25c2a0">Docusaurus en vert</Highlight> et <Highlight color="#1877F2">Facebook en bleu</Highlight> sont mes couleurs préférées.
Je peux écrire en **Markdown** a côté de mon _JSX_ !

Remarquez comment il rend à la fois le balisage de votre composant React et la syntaxe Markdown :

http://localhost:3000

Docusaurus en vert and Facebook en bleu sont mes couleurs préférées.

Je peux écrire en Markdown a côté de mon JSX !

Vous pouvez également importer vos propres composants définis dans d'autres fichiers ou composants tiers installés via npm ! Consultez les docs MDX pour voir ce que vous pouvez faire avec MDX.

caution

Comme tous les fichiers doc sont analysés à l'aide de MDX, tout HTML est interprété comme 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. Ce comportement est différent de Docusaurus 1. Consulter aussi la Migration de v1 vers v2.

Importation d'extraits de code

Vous pouvez non seulement importer un fichier contenant une définition de composant, mais aussi importer n'importe quel fichier de code sous forme de texte brut, puis l'insérer dans un bloc de code, grâce à Webpack raw-loader. Afin d'utiliser raw-loader, vous devez d'abord l'installer dans votre projet :

npm

npm install --save raw-loader

Yarn

yarn add raw-loader

Vous pouvez maintenant importer des extraits de code d'un autre fichier tel quel :

myMarkdownFile.mdx

import CodeBlock from '@theme/CodeBlock';import MyComponentSource from '!!raw-loader!./myComponent';
<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>

http://localhost:3000

/** * Copyright (c) Facebook, Inc. and its affiliates. * * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. */
import React, {useState} from 'react';
export default function MyComponent() {  const [bool, setBool] = useState(false);  return (    <div>      <p>MyComponent rendered !</p>      <p>bool={bool ? 'true' : 'false'}</p>      <p>        <button onClick={() => setBool((b) => !b)}>toggle bool</button>      </p>    </div>  );}

Vous pouvez également passer la prop title au composant CodeBlock afin de l'afficher comme entête au-dessus de votre bloc de code :

<CodeBlock className="language-jsx" title="/src/myComponent">  {MyComponentSource}</CodeBlock>

remarque

Vous devez utiliser <CodeBlock> plutôt que le triptyque Markdown ```, car ce dernier expédiera tout son contenu tel quel, mais vous voulez que JSX insère le texte importé ici.

avertissement

Cette fonctionnalité est expérimentale et pourrait faire l'objet de modifications de l'API à l'avenir.

Importation de Markdown

Vous pouvez utiliser des fichiers Markdown comme composants et les importer ailleurs, soit dans des fichiers Markdown, soit dans des pages React.

Par convention, l'utilisation du _ pour le préfixe du nom de fichier ne créera aucune page doc et signifie que le fichier Markdown est un « partiel », à importer par d'autres fichiers.

_markdown-partial-example.mdx

<span>Bonjour {props.name}</span>
Ceci est du texte du contenu de `_markdown-partial-example.mdx`.

someOtherDoc.mdx

import PartialExample from './_markdown-partial-example.mdx';
<PartialExample name="Sebastien" />;

http://localhost:3000

Bonjour Sebastien

Ceci est du texte du contenu de _markdown-partial-example.md.

De cette façon, vous pouvez réutiliser le contenu entre plusieurs pages et éviter de dupliquer le contenu.

caution

La table des matières ne contient pas actuellement les titres Markdown importés. Il s'agit d'une limitation technique que nous essayons de résoudre (issue).