Aller au contenu principal
Version: 2.0.0-beta.4

Plugins

Les plugins sont les éléments de construction des fonctionnalités d'un site Docusaurus 2. Chaque plugin gère sa propre fonctionnalité. Les plugins peuvent fonctionner et être distribués dans le cadre d'un bundle via presets.

Plugins disponibles#

Nous maintenons une liste de plugins officiels, mais la communauté a également créé des plugins non officiels.

Installation d'un plugin#

Un plugin est généralement un paquet npm, donc vous les installez comme les autres paquets npm en utilisant npm.

npm install --save docusaurus-plugin-name

Puis vous l'ajoutez dans l'option plugins dans docusaurus.config.js de votre site :

docusaurus.config.js
module.exports = {  // ...  plugins: ['@docusaurus/plugin-content-pages'],};

Docusaurus peut également charger des plugins depuis votre répertoire local, vous pouvez faire quelque chose comme ceci :

docusaurus.config.js
const path = require('path');
module.exports = {  // ...  plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],};

Configuration des plugins#

Pour l'utilisation la plus basique des plugins, vous pouvez fournir juste le nom du plugin ou le chemin absolu vers le plugin.

Cependant, les plugins peuvent avoir des options spécifiées en enveloppant le nom et un objet d'options dans un tableau dans votre configuration. Ce style s'appelle généralement Babel Style.

docusaurus.config.js
module.exports = {  // ...  plugins: [    [      '@docusaurus/plugin-xxx',      {        /* options */      },    ],  ],};

Exemple :

docusaurus.config.js
module.exports = {  plugins: [    // Basic usage.    '@docusaurus/plugin-google-analytics',
    // Avec l'objet options (babel style)    [      '@docusaurus/plugin-sitemap',      {        changefreq: 'weekly',      },    ],  ],};

Id de plugins et de plugins multi-instance#

Tous les plugins de contenu Docusaurus peuvent supporter plusieurs instances de plugins.

Le plugin Docs a de la documentation supplémentaire sur la multi-instance

Il est nécessaire d'assigner un id unique à chaque instance de plugin.

Par défaut, l'id du plugin est default.

docusaurus.config.js
module.exports = {  plugins: [    [      '@docusaurus/plugin-xxx',      {        id: 'plugin-xxx-1',        // autres options      },    ],    [      '@docusaurus/plugin-xxx',      {        id: 'plugin-xxx-2',        // autres options      },    ],  ],};
remarque

Au maximum une instance de plugin peut être « l'instance de plugin default », en omettant l'attribut id, ou en utilisant id : 'default'.

Conception des plugins#

L'implémentation du système de plugins de Docusaurus nous fournit un moyen pratique de nous connecter au cycle de vie du site web pour modifier ce qui se passe pendant le développement/construction, ce qui implique (mais pas seulement) l'extension de la configuration de webpack, la modification des données chargées et la création de nouveaux composants à utiliser dans une page.

Création de plugins#

Un plugin est une fonction qui prend deux paramètres : contexte et options.

Il retourne un objet d'instance de plugin, contenant les API de cycle de vie du plugin.

Il peut être défini comme une fonction ou un module.

Définition d'une fonction#

Vous pouvez utiliser un plugin comme fonction, directement dans le fichier de configuration de Docusaurus :

docusaurus.config.js
module.exports = {  // ...  plugins: [    // highligh-start    function myPlugin(context, options) {      // ...      return {        name: 'my-plugin',        async loadContent() {          // ...        },        async contentLoaded({content, actions}) {          // ...        },        /* autre API du cycle de vie */      };    },  ],};

Définition du module#

Vous pouvez utiliser un plugin comme module, le charger à partir d'un fichier séparé ou d'un paquet NPM :

docusaurus.config.js
module.exports = {  // ...  plugins: [    // sans options :    './my-plugin',    // ou avec options :    ['./my-plugin', options],  ],};

Puis dans le dossier my-plugin vous pouvez créer un index.js comme celui-ci

my-plugin.js
module.exports = function myPlugin(context, options) {  // ...  return {    name: 'my-plugin',    async loadContent() {      /* ... */    },    async contentLoaded({content, actions}) {      /* ... */    },    /* autre API du cycle de vie */  };};

context#

context est agnostique par rapport aux plugins et le même objet sera passé dans tous les plugins utilisés pour un site web Docusaurus. L'objet context contient les champs suivants :

interface LoadContext {  siteDir: string;  generatedFilesDir: string;  siteConfig: DocusaurusConfig;  outDir: string;  baseUrl: string;}

options#

options est le deuxième paramètre optionnel lorsque les plugins sont utilisés. options est spécifique à un plugin et est spécifié par les utilisateurs lorsqu'ils les utilisent dans docusaurus.config.js. En revanche, si le preset contient le plugin, le preset se chargera alors de passer les bonnes options au plugin. Il appartient à chaque plugin de définir les options qu'il prend.

Valeur de retour#

La valeur de l'objet retourné doit implémenter les API du cycle de vie.