Version : 2.4.0

Utilisation de Plugins

The Docusaurus core doesn't provide any feature of its own. All features are delegated to individual plugins: the docs feature provided by the docs plugin; the blog feature provided by the blog plugin; or individual pages provided by the pages plugin. S'il n'y a pas de plugins installés, le site ne contiendra pas de routes.

You may not need to install common plugins one-by-one though: they can be distributed as a bundle in a preset. Pour la plupart des utilisateurs, les plugins sont configurés via la configuration du preset.

We maintain a list of official plugins, but the community has also created some unofficial plugins. If you want to add any feature: autogenerating doc pages, executing custom scripts, integrating other services... be sure to check out the list: someone may have implemented it for you!

If you are feeling energetic, you can also read the plugin guide or plugin method references for how to make a plugin yourself.

Installing a 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

Then you add it in your site's docusaurus.config.js's plugins option:

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

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

docusaurus.config.js
module.exports = {
  // ...
  plugins: ['./src/plugins/docusaurus-local-plugin'],
};

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

Configuring 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
module.exports = {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-xxx',
      {
        /* options */
      },
    ],
  ],
};

Exemple :

docusaurus.config.js
module.exports = {
  plugins: [
    // Basic usage.
    '@docusaurus/plugin-debug',

    // With options object (babel style)
    [
      '@docusaurus/plugin-sitemap',
      {
        changefreq: 'weekly',
      },
    ],
  ],
};

Multi-instance plugins and plugin IDs

Tous les plugins de contenu Docusaurus peuvent supporter plusieurs instances de plugins. For example, it may be useful to have multiple docs plugin instances or multiple blogs. It is required to assign a unique ID to each plugin instance, and by default, the plugin ID is default.

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

remarque

At most one plugin instance can be the "default plugin instance", by omitting the id attribute, or using id: 'default'.

Using themes

Les thèmes sont chargés exactement de la même manière que les plugins. From the consumer perspective, the themes and plugins entries are interchangeable when installing and configuring a plugin. The only nuance is that themes are loaded after plugins, and it's possible for a theme to override a plugin's default theme components.

astuce

The themes and plugins options lead to different shorthand resolutions, so if you want to take advantage of shorthands, be sure to use the right entry!

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

Using presets

Les presets sont des paquets de plugins et de thèmes. For example, instead of letting you register and configure @docusaurus/plugin-content-docs, @docusaurus/plugin-content-blog, etc. one after the other in the config file, we have @docusaurus/preset-classic preset allows you to configure them in one centralized place.

`@docusaurus/preset-classic`

The classic preset is shipped by default to new Docusaurus websites created with 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
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Debug defaults to true in dev, false in prod
        debug: undefined,
        // Will be passed to @docusaurus/theme-classic.
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
        // Will be passed to @docusaurus/plugin-content-docs (false to disable)
        docs: {},
        // Will be passed to @docusaurus/plugin-content-blog (false to disable)
        blog: {},
        // Will be passed to @docusaurus/plugin-content-pages (false to disable)
        pages: {},
        // Will be passed to @docusaurus/plugin-content-sitemap (false to disable)
        sitemap: {},
        // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
        gtag: {},
        // Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
        googleTagManager: {},
        // DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
        googleAnalytics: {},
      },
    ],
  ],
};

Installing 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

Then, add it in your site's docusaurus.config.js's presets option:

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

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

docusaurus.config.js
module.exports = {
  // ...
  presets: ['./src/presets/docusaurus-local-preset'],
};

Creating presets

A preset is a function with the same shape as the plugin constructor. It should return an object of { plugins: PluginConfig[], themes: PluginConfig[] }, in the same as how they are accepted in the site config. Par exemple, vous pouvez spécifier un prest qui inclut les thèmes et plugins suivants:

src/presets/docusaurus-preset-multi-docs.js
module.exports = function preset(context, opts = {}) {
  return {
    themes: [['docusaurus-theme-awesome', opts.theme]],
    plugins: [
      // Using three docs plugins at the same time!
      // Assigning a unique ID for each without asking the user to do it
      ['@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
module.exports = {
  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
module.exports = {
  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.

Module shorthands

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] (like content-docs)
@docusaurus/[moduleType]-[name] (like @docusaurus/plugin-content-docs)
docusaurus-[moduleType]-[name] (like docusaurus-plugin-content-docs)

where moduleType is one of 'preset', 'theme', 'plugin', depending on which field the module name is declared in. Le premier nom de module trouvé est chargé.

If the name is scoped (beginning with @), the name is first split into scope and package name by the first slash:

@scope
^----^
 scope  (no name!)

@scope/awesome
^----^ ^-----^
 scope   name

@scope/awesome/main
^----^ ^----------^
 scope     name

If there is no name (like @jquery), [scope]/docusaurus-[moduleType] (i.e. @jquery/docusaurus-plugin) is loaded. Sinon, les tentatives suivantes sont effectuées :

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

Below are some examples, for a plugin registered in the plugins field. Note that unlike ESLint or Babel where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.

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

Utilisation de Plugins

Installing a plugin​

Configuring plugins​

Multi-instance plugins and plugin IDs​

Using themes​

Using presets​

@docusaurus/preset-classic​

Installing presets​

Creating presets​

Module shorthands​