Plugins

Plugins são os blocos de construção de recursos de um site do Docusaurus 2. Cada plugin lida com seu próprio recurso. Plugins podem funcionar e ser distribuídos como parte do bundle através de presets.

Plugins disponíveis

Mantemos uma lista de plugins oficiais, mas a comunidade também criou alguns plugins não oficiais.

Instalando um plugin

Um plugin geralmente é um pacote npm, então você os instala como outros pacotes npm usando npm.

npm

npm install --save docusaurus-plugin-name

Yarn

yarn add docusaurus-plugin-name

Em seguida, adicione-o ao seu site na opção plugins do docusaurus.config.js:

docusaurus.config.js

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

O Docusaurus também pode carregar plugins do seu diretório local, você pode fazer algo assim:

docusaurus.config.js

const path = require('path');

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

Configurando plugins

Para o uso mais básico de plugins, você pode fornecer apenas o nome do plugin ou o caminho absoluto para o plugin.

No entanto, plugins podem ter opções especificadas envolvendo o nome e um objeto de opções em um array dentro de sua configuração. Este estilo é geralmente chamado de Babel Style.

docusaurus.config.js

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

Exemplo:

docusaurus.config.js

module.exports = {
  plugins: [
    // Basic usage.
    '@docusaurus/plugin-google-analytics',

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

Plugins de multi-instância e ids de plugin

Todos os plugins de conteúdo do Docusaurus suportam vários plugins.

O plugin Docs tem documentação adicional multi-instância

É necessário atribuir um id exclusivo para cada instância do plugin.

Por padrão, o Id do plugin é default.

docusaurus.config.js

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

note

No máximo, uma instância de plugin pode ser a "instância padrão do plugin", omitindo o atributo id ou usando id: 'default'.

Design dos plugins

A implementação do sistema de plug-ins pelo Docusaurus nos fornece uma maneira conveniente de entrar no ciclo de vida do site para modificar o que acontece durante o desenvolvimento/construção, o que envolve (mas não se limita a) estender a configuração do webpack, modificar os dados que estão sendo carregados e criar novos componentes a serem usados em uma página.

Criando plugins

Um plugin é uma função que recebe dois parâmetros: context e options.

Ele retorna um objeto de instância de plugin, contendo APIs de ciclo de vida.

Pode ser definido como uma função ou um módulo.

Definição funcional

Você pode usar um plugin como uma função, diretamente no arquivo de configuração do Docusaurus:

docusaurus.config.js

module.exports = {
  // ...
  plugins: [
    function myPlugin(context, options) {
      // ...
      return {
        name: 'my-plugin',
        async loadContent() {
          // ...
        },
        async contentLoaded({content, actions}) {
          // ...
        },
        /* other lifecycle API */
      };
    },
  ],
};

Definição do módulo

Você pode usar um plugin como módulo, carregando-o a partir de um arquivo separado ou pacote NPM:

docusaurus.config.js

module.exports = {
  // ...
  plugins: [
    // without options:
    './my-plugin',
    // or with options:
    ['./my-plugin', options],
  ],
};

Então na pasta my-plugin você pode criar um index.js como esse

my-plugin.js

module.exports = function myPlugin(context, options) {
  // ...
  return {
    name: 'my-plugin',
    async loadContent() {
      /* ... */
    },
    async contentLoaded({content, actions}) {
      /* ... */
    },
    /* other lifecycle API */
  };
};

context

context é plugin-agnostic, e o mesmo objeto será passado para todos os plugins usados em um site do Docusaurus. O objeto context contém os seguintes campos:

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

options

options é o segundo parâmetro opcional quando os plugins são usados. options são específicas do plugin e são especificadas pelos usuários quando os usam em docusaurus.config.js. Alternativamente, se a predefinição contiver o plugin, a predefinição estará encarregada de passar as opções corretas para o plugin. Cabe a cada plugin definir quais opções são necessárias.

Valor retornado

O valor do objeto retornado deve implementar as APIs do ciclo de vida.