Aller au contenu principal
Version: 2.0.0-beta.10 🚧

Plugins MDX

Parfois, vous pouvez souhaiter étendre ou modifier la syntaxe Markdown. Par exemple :

  • Comment intégrer des vidéos youtube en utilisant la syntaxe image (![](https://youtu.be/yKNxeF4KMsY)) ?
  • Comment donner un style différent aux liens qui se trouvent sur leur propre ligne, par exemple, comme une carte de visite ?
  • Comment faire pour que chaque page commence par un avis de droit d'auteur ?

Et la réponse est : créer un plugin MDX ! MDX dispose d'un système intégré de plugins qui peut être utilisé pour personnaliser la façon dont les fichiers Markdown seront analysés et transformés en JSX. Il y a trois cas d'utilisation typiques des plugins MDX :

  • Utilisation des plugins remark existants ou rehype;
  • Création de plugins remark/rehype pour transformer les éléments générés par la syntaxe MDX existante;
  • Création de plugins remark/rehype pour introduire de nouvelles syntaxes dans MDX.

Si vous jouez avec le terrain de jeu MDX, vous remarquerez que la transpilation MDX comporte deux étapes intermédiaires : Markdown AST (MDAST), et Hypertext AST (HAST), avant d'arriver à la sortie JSX finale. Les plugins MDX sont également fournis sous deux formes :

  • Remark : traite l'AST du Markdown.
  • Rehype : traite l'AST de Hypertext.
astuce

Utilisez des plugins pour introduire une syntaxe plus courte pour les éléments JSX les plus couramment utilisés dans votre projet. La syntaxe admonition que nous proposons est également générée par un plugin de Remark, et vous pourriez faire de même pour votre propre cas d'utilisation.

Plugins par défaut

Docusaurus injecte quelques plugins Remark par défaut pendant le traitement du Markdown. Ces plugins pourraient :

  • Générer la table des matières;
  • Ajouter des liens d'ancrage à chaque titre;
  • Transformer les images et les liens qui appellent require().

Ce sont tous des cas d'utilisation typiques des plugins Remark, qui peuvent également être une source d'inspiration si vous voulez implémenter votre propre plugin.

Installation des plugins

Un plugin MDX est généralement un paquet npm, donc vous les installez comme les autres paquets npm en utilisant npm. Prenons l'exemple du plugin de math.

remarque

Il y a récemment une tendance dans l'écosystème Remark/Rehype à migrer vers les modules ES, que Docusaurus ne supporte pas encore. Veuillez vous assurer que la version de votre plugin installée est compatible CommonJS avant que nous ne supportons officiellement ESM.

En quoi remark-math et rehype-katex sont-ils différents ?

Au cas où vous vous demandez comment Remark et Rehype sont différents, voici un bon exemple. remark-math opère sur l'AST du Markdown, où il repère du texte comme $...$, et tout ce qu'il fait est de transformer cela en JSX <span class="math-inline">...</span> sans faire trop de choses avec le contenu. Cette fonction dissocie l'extraction des formules mathématiques de leur rendu, ce qui signifie que vous pouvez échanger KaTeX\KaTeX avec d'autres moteurs de rendu mathématiques, comme MathJax (avec rehype-mathjax), juste en remplaçant le plugin Rehype.

Next, the rehype-katex operates on the Hypertext AST where everything has been converted to HTML-like tags already. It traverses all the elements with math class, and uses KaTeX\KaTeX to parse and render the content to actual HTML.

Ensuite, ajoutez-les aux options du plugin via le plugin ou la configuration prédéfinie dans docusaurus.config.js :

docusaurus.config.js
const math = require('remark-math');
const katex = require('rehype-katex');

module.exports = {
title: 'Docusaurus',
tagline: 'Construisez des sites web optimisés rapidement, concentrez-vous sur votre contenu',
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [math],
rehypePlugins: [katex],
},
},
],
],
};

Configuration des plugins

Certains plugins peuvent être configurés et recevoir leurs propres options. Dans ce cas, utilisez la syntaxe [plugin, pluginOptions] , comme ceci :

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [math],
rehypePlugins: [
[katex, {strict: false}],
],
},
},
],
],
};

Vous devriez consulter la documentation de votre plugin pour les options qu'il prend en charge.

Création de nouveaux plugins rehype/remark

S'il n'existe pas de package existant qui réponde à votre besoin de personnalisation, vous pouvez créer votre propre plugin MDX.

remarque

La présentation ci-dessous n'est pas un guide complet pour la création d'un plugin, mais simplement une illustration de la manière de le faire fonctionner avec Docusaurus. Consultez la documentation Remark ou Rehype pour une explication plus approfondie de leur fonctionnement.

Par exemple, créons un plugin qui visite chaque entête h2 et ajoute un préfixe Section X.. Tout d'abord, créez le fichier source de votre plugin n'importe où - vous pouvez même le publier en tant que paquet NPM distinct et l'installer comme expliqué ci-dessus. Nous placerions le nôtre dans src/remark/section-prefix.js. Un plugin remark/rehype est juste une fonction qui reçoit les options et retourne un transformer qui opère sur l'AST.

const visit = require('unist-util-visit');

const plugin = (options) => {
const transformer = async (ast) => {
let number = 1;
visit(ast, 'heading', (node) => {
if (node.depth === 2 && node.children.length > 0) {
if (node.children[0].type === 'text') {
node.children[0].value = `Section ${number}. ${node.children[0].value}`;
} else {
node.children.unshift({
type: 'text',
value: `Section ${number}. `,
});
}
number++;
}
});
};
return transformer;
};

module.exports = plugin;

Vous pouvez maintenant importer votre plugin dans docusaurus.config.js et l'utiliser comme un plugin installé !

docusaurus.config.js
const sectionPrefix = require('./src/remark/section-prefix');

module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [sectionPrefix],
},
},
],
],
};
remarque

The default plugins of Docusaurus would operate before the custom remark plugins, and that means the images or links have been converted to JSX with require() calls already. For example, in the example above, the table of contents generated is still the same even when all h2 headings are now prefixed by Section X., because the TOC-generating plugin is called before our custom plugin. If you need to process the MDAST before the default plugins do, use the beforeDefaultRemarkPlugins and beforeDefaultRehypePlugins.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
beforeDefaultRemarkPlugins: [sectionPrefix],
},
},
],
],
};

This would make the table of contents generated contain the Section X. prefix as well.