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 sous la forme d'une carte sociale ?
• 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 existants remark 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.

npm

npm install --save remark-math@3 rehype-katex@4

Yarn

yarn add remark-math@3 rehype-katex@4

pnpm

pnpm add remark-math@3 rehype-katex@4

remarque

Il y a récemment une tendance dans l'écosystème Remark/Rehype à migrer vers ES Modules, un nouveau système de modules JavaScript, 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. Sinon, vous pouvez lire l'utilisation dynamique de import() comme solution de contournement dans le tutoriel d'installation de rehype-katex.

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 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$ avec d'autres moteurs de rendu mathématiques, comme MathJax (avec rehype-mathjax), juste en remplaçant le plugin Rehype.

Ensuite, le rehype-katex fonctionne sur l'AST Hypertext où tout a déjà été converti en balises HTML . Il traverse tous les éléments de la classe math et utilise $\\KaTeX$ pour analyser et rendre le contenu en 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) {
        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],
        },
      },
    ],
  ],
};

astuce

Le transformer a un second paramètre vfile qui est utile si vous avez besoin d'accéder au chemin du fichier Markdown actuel.

const plugin = (options) => {
  const transformer = async (ast, vfile) => {
    ast.children.unshift({
      type: 'text',
      value: `Le chemin du fichier actuel est ${vfile.path}`,
    });
  };
  return transformer;
};

Notre plugin transformImage utilise ce paramètre, par exemple, pour transformer les références d'image relatives aux appels à require().

remarque

Les plugins par défaut de Docusaurus fonctionnent avant les plugins Remark personnalisés, ce qui signifie que les images ou les liens ont déjà été convertis en JSX avec des appels require(). Par exemple, dans l'exemple ci-dessus, la table des matières générée reste la même, même si tous les titres h2 sont maintenant préfixés par Section X., car le plugin de génération de la table des matières est appelé avant notre plugin personnalisé. Si vous devez traiter le MDAST avant les plugins par défaut, utilisez beforeDefaultRemarkPlugins et beforeDefaultRehypePlugins.

docusaurus.config.js

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

Ainsi, la table des matières générée comprendra également le préfixe Section X..