Ir para o conteúdo principal
Version: 2.0.0-beta.5 🚧

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 install --save 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: [    // highligh-start    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.