Version : Canary 🚧

Utilisation de Plugins

Le noyau de Docusaurus ne fournit aucune fonctionnalité propre. Toutes les fonctionnalités sont déléguées à des plugins individuels : la fonctionnalité docs fournie par le plugin docs ; la fonctionnalité blog fournie par le plugin blog ; ou les pages individuelles fournies par le plugin pages. S'il n'y a pas de plugins installés, le site ne contiendra pas de routes.

Vous n'aurez peut-être pas besoin d'installer les plugins les plus courants un par un : ils peuvent être distribués sous forme de paquet dans un preset. Pour la plupart des utilisateurs, les plugins sont configurés via la configuration du preset.

Nous maintenons une liste de plugins officiels, mais la communauté a également créé des s plugins non officiels. Si vous souhaitez ajouter une fonctionnalité quelconque : génération automatique de pages de documentation, exécution de scripts personnalisés, intégration d'autres services... n'oubliez pas de consulter la liste : quelqu'un l'a peut-être implémentée pour vous !

Si vous vous sentez énergique, vous pouvez également lire le guide du plugin ou les références de la méthode du plugin pour savoir comment faire un plugin vous-même.

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
Yarn
pnpm

npm install --save docusaurus-plugin-name

yarn add docusaurus-plugin-name

pnpm add docusaurus-plugin-name

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

docusaurus.config.js
export default {
  // ...
  plugins: ['@docusaurus/plugin-content-pages'],
};

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

docusaurus.config.js
export default {
  // ...
  plugins: ['./src/plugins/docusaurus-local-plugin'],
};

Les chemins doivent être absolus ou relatifs par rapport au fichier de configuration.

Configuration des plugins

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

Cependant, les plugins peuvent avoir des options spécifiées en encapsulant le nom et un objet d'options dans un tuple à deux membres dans votre configuration. Ce style est généralement appelé « Style Babel ».

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

Exemple :

docusaurus.config.js
export default {
  plugins: [
    // Utilisation de base.
    '@docusaurus/plugin-debug',

    // Avec l'objet options (style babel)
    [
      '@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. Par exemple, il peut être utile d'avoir plusieurs instances de plugin docs ou plusieurs blogs. Il est nécessaire d'affecter un ID unique à chaque instance de plugin, et par défaut, l'ID du plugin est default.

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-1',
        // d'autres options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-2',
        // d'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'.

Utilisation des thèmes

Les thèmes sont chargés exactement de la même manière que les plugins. Du point de vue du consommateur, les entrées themes et plugins sont interchangeables lors de l'installation et de la configuration d'un plugin. La seule nuance est que les thèmes sont chargés après les plugins, et il est possible pour un thème de remplacer les composants du thème par défaut d'un plugin.

astuce

Les options themes et plugins conduisent à des résolutions de raccourcis différentes, donc si vous voulez profiter des raccourcis, assurez-vous d'utiliser la bonne saisie !

docusaurus.config.js
export default {
  // ...
  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

Utiliser les presets

Les presets sont des paquets de plugins et de thèmes. Par exemple, au lieu de vous laisser enregistrer et configurer @docusaurus/plugin-content-docs, @docusaurus/plugin-content-blog, etc. les uns après les autres dans le fichier de configuration, nous avons le preset @docusaurus/preset-classic qui vous permet de les configurer en un seul et même endroit centralisé.

`@docusaurus/preset-classic`

Le preset classic est expédié par défaut aux nouveaux sites web Docusaurus créés avec create-docusaurus. Il contient les thèmes et plugins suivants :

Le preset classic transmettra chaque entrée d'option au plugin/thème respectif.

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Débogage par défaut à true dans dev, false dans prod
        debug: undefined,
        // Sera passé à @docusaurus/theme-classic.
        theme: {
          customCss: ['./src/css/custom.css'],
        },
        // Sera passé à @docusaurus/plugin-content-docs (false pour désactiver)
        docs: {},
        // Sera passé à @docusaurus/plugin-content-blog (false pour désactiver)
        blog: {},
        // Sera passé à @docusaurus/plugin-content-pages (false pour désactiver)
        pages: {},
        // Sera passé à @docusaurus/plugin-sitemap (false pour désactiver)
        sitemap: {},
        // Sera passé à @docusaurus/plugin-google-gtag (seulement activée si explicitement spécifiée)
        gtag: {},
        // Sera passé à @docusaurus/plugin-google-tag-manager (seulement activée si explicitement spécifiée)
        googleTagManager: {},
        // DEPRECIE : Sera passé à @docusaurus/plugin-google-analytics (seulement activée si explicitement spécifiée)
        googleAnalytics: {},
      },
    ],
  ],
};

Installation des presets

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

npm
Yarn
pnpm

npm install --save @docusaurus/preset-classic

yarn add @docusaurus/preset-classic

pnpm add @docusaurus/preset-classic

Puis, ajoutez-le dans l'option presets de docusaurus.config.js de votre site :

docusaurus.config.js
export default {
  // ...
  presets: ['@docusaurus/preset-classic'],
};

Les chemins du preset peuvent être relatifs à celui du fichier de configuration :

docusaurus.config.js
export default {
  // ...
  presets: ['./src/presets/docusaurus-local-preset'],
};

Création de presets

Un preset est une fonction ayant la même forme que le constructeur de plugin. Il devrait retourner un objet de { plugins: PluginConfig[], themes: PluginConfig[] }, de la même manière qu'ils sont acceptés dans la configuration du site. Par exemple, vous pouvez spécifier un prest qui inclut les thèmes et plugins suivants:

src/presets/docusaurus-preset-multi-docs.js
export default function preset(context, opts = {}) {
  return {
    themes: [['docusaurus-theme-awesome', opts.theme]],
    plugins: [
      // Utilisation de trois plugins docs en même temps !
      // Assigne un ID unique pour chacun sans demander à l'utilisateur de le faire
      ['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
    ],
  };
}

Puis dans votre configuration de Docusaurus, vous pouvez configurer le preset :

docusaurus.config.js
export default {
  presets: [
    [
      './src/presets/docusaurus-preset-multi-docs.js',
      {
        theme: {hello: 'world'},
        docs1: {path: '/docs'},
        docs2: {path: '/community'},
        docs3: {path: '/api'},
      },
    ],
  ],
};

Cela équivaut à :

docusaurus.config.js
export default {
  themes: [['docusaurus-theme-awesome', {hello: 'world'}]],
  plugins: [
    ['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}],
  ],
};

Ceci est particulièrement utile lorsque certains plugins et thèmes sont destinés à être utilisés ensemble. Vous pouvez même lier leurs options entre eux, par exemple en transmettant une option à plusieurs plugins.

Raccourcis de module

Docusaurus prend en charge les raccourcis pour les plugins, les thèmes et les presets. Lorsqu'il voit un nom de plugin/ thème/preset, il essaie de charger l'un des éléments suivants, dans cet ordre :

[name] (comme content-docs)
@docusaurus/[moduleType]-[name] (comme @docusaurus/plugin-content-docs)
docusaurus-[moduleType]-[name] (comme docusaurus-plugin-content-docs)

où moduleType est soit 'preset', 'theme' ou 'plugin', selon le champ dans lequel le nom du module est déclaré. Le premier nom de module trouvé est chargé.

Si le nom est scopé (commençant par @), le nom est d'abord divisé en scope et nom de paquet par le premier slash :

@scope
^----^
 scope  (aucun nom !)

@scope/awesome
^----^ ^-----^
 scope   nom

@scope/awesome/main
^----^ ^----------^
 scope     nom

S'il n'y a pas de nom (comme @jquery), [scope]/docusaurus-[moduleType] (par exemple @jquery/docusaurus-plugin) est chargé. Sinon, les tentatives suivantes sont effectuées :

[scope]/[name] (comme @jquery/content-docs)
[scope]/docusaurus-[moduleType]-[name] (comme @jquery/docusaurus-plugin-content-docs)

Voici quelques exemples, pour un plugin enregistré dans le champ plugins. Notez que contrairement à ESLint ou Babel où une convention de nommage cohérente pour les plugins est imposée, Docusaurus permet une plus grande liberté de nommage, les résolutions ne sont donc pas certaines, mais suivent la priorité définie ci-dessus.

Déclaration	Peut être résolu comme suit
`awesome`	`docusaurus-plugin-awesome`
`sitemap`	`@docusaurus/plugin-sitemap`
`@my-company`	`@my-company/docusaurus-plugin` (la seule résolution possible !)
`@my-company/awesome`	`@my-company/docusaurus-plugin-awesome`
`@my-company/awesome/web`	`@my-company/docusaurus-plugin-awesome/web`

Installation d'un plugin​

Configuration des plugins​

ID de plugins et de plugins multi-instance​

Utilisation des thèmes​

Utiliser les presets​

@docusaurus/preset-classic​

Installation des presets​

Création de presets​

Raccourcis de module​