Plugins MDX
Parfois, vous pouvez souhaiter étendre ou modifier la syntaxe Markdown. Par exemple :
- How do I embed youtube videos using the image syntax (
)? - 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 has a built-in plugin system that can be used to customize how the Markdown files will be parsed and transformed to JSX. Il y a trois cas d'utilisation typiques des plugins MDX :
- Using existing remark plugins or rehype plugins;
- 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.
If you play with the MDX playground, you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. Les plugins MDX sont également fournis sous deux formes :
Utilisez des plugins pour introduire une syntaxe plus courte pour les éléments JSX les plus couramment utilisés dans votre projet. The admonition syntax that we offer is also generated by a Remark plugin, and you could do the same for your own use case.
Default plugins
Docusaurus injects some default Remark plugins during Markdown processing. Ces plugins pourraient :
- Générer la table des matières;
- Ajouter des liens d'ancrage à chaque titre;
- Transform images and links to
require()calls. - …
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.
Installing plugins
Un plugin MDX est généralement un paquet npm, donc vous les installez comme les autres paquets npm en utilisant npm. Take the math plugins as an example.
- npm
- Yarn
- pnpm
npm install --save [email protected] [email protected]
yarn add [email protected] [email protected]
pnpm add [email protected] [email protected]
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. Alternatively, you can read about using dynamic import() as a workaround in the tutorial of installing rehype-katex.
How are remark-math and rehype-katex different?
Au cas où vous vous demandez comment Remark et Rehype sont différents, voici un bon exemple. remark-math operates on the Markdown AST, where it sees text like $...$, and all it does is transform that to the JSX <span class="math math-inline">...</span> without doing too much with the content. This decouples the extraction of math formulae from their rendering, which means you can swap out with other math renderers, like MathJax (with rehype-mathjax), just by replacing the Rehype plugin.
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 to parse and render the content to actual HTML.
Next, add them to the plugin options through plugin or preset config in 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],
},
},
],
],
};
Configuring plugins
Certains plugins peuvent être configurés et recevoir leurs propres options. In that case, use the [plugin, pluginOptions] syntax, like this:
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.
Creating new rehype/remark plugins
S'il n'existe pas de package existant qui réponde à votre besoin de personnalisation, vous pouvez créer votre propre plugin MDX.
For example, let's make a plugin that visits every h2 heading and adds a Section X. prefix. 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. We would put ours at src/remark/section-prefix.js. A remark/rehype plugin is just a function that receives the options and returns a transformer that operates on the 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;
You can now import your plugin in docusaurus.config.js and use it just like an installed plugin!
const sectionPrefix = require('./src/remark/section-prefix');
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [sectionPrefix],
},
},
],
],
};
The transformer has a second parameter vfile which is useful if you need to access the current Markdown file's path.
const plugin = (options) => {
const transformer = async (ast, vfile) => {
ast.children.unshift({
type: 'text',
value: `The current file path is ${vfile.path}`,
});
};
return transformer;
};
Our transformImage plugin uses this parameter, for example, to transform relative image references to require() calls.
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.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
beforeDefaultRemarkPlugins: [sectionPrefix],
},
},
],
],
};
This would make the table of contents generated contain the Section X. prefix as well.