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 may work and be distributed as part of a bundle via presets.

Creating plugins

A plugin is a function that takes two parameters: context and options. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the plugin method references section.

Function definition

You can use a plugin as a function directly included in the Docusaurus config file:

docusaurus.config.js

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

Module definition

You can use a plugin as a module path referencing a separate file or npm package:

docusaurus.config.js

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

Then in the folder my-plugin, you can create an index.js such as this:

my-plugin/index.js

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

---

You can view all plugins installed in your site using the debug plugin's metadata panel.

Plugins come as several types:

• package: an external package you installed
• project: a plugin you created in your project, given to Docusaurus as a local file path
• local: a plugin created using the function definition
• synthetic: a "fake plugin" Docusaurus created internally, so we take advantage of our modular architecture and don't let the core do much special work. You won't see this in the metadata because it's an implementation detail.

You can access them on the client side with useDocusaurusContext().siteMetadata.pluginVersions.

Plugin design

Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page.

Theme design

When plugins have loaded their content, the data is made available to the client side through actions like createData + addRoute or setGlobalData. This data has to be serialized to plain strings, because plugins and themes run in different environments. Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through ReactDOM.render...

Themes provide the set of UI components to render the content. Most content plugins need to be paired with a theme in order to be actually useful. A interface do usuário é uma camada separada do esquema de dados, o que facilita a troca de design.

For example, a Docusaurus blog may consist of a blog plugin and a blog theme.

note

This is a contrived example: in practice, @docusaurus/theme-classic provides the theme for docs, blog, and layouts.

docusaurus.config.js

module.exports = {
  themes: ['theme-blog'],
  plugins: ['plugin-content-blog'],
};

And if you want to use Bootstrap styling, you can swap out the theme with theme-blog-bootstrap (another fictitious non-existing theme):

docusaurus.config.js

module.exports = {
  themes: ['theme-blog-bootstrap'],
  plugins: ['plugin-content-blog'],
};

Now, although the theme receives the same data from the plugin, how the theme chooses to render the data as UI can be drastically different.

While themes share the exact same lifecycle methods with plugins, themes' implementations can look very different from those of plugins based on themes' designed objectives.

Os temas são projetados para completar a compilação do seu site Docusaurus e fornecer os componentes usados pelo seu site, plugins e os próprios temas. A theme still acts like a plugin and exposes some lifecycle methods, but most likely they would not use loadContent, since they only receive data from plugins, but don't generate data themselves; themes are typically also accompanied by an src/theme directory full of components, which are made known to the core through the getThemePath lifecycle.

Para resumir:

• Temas compartilham os mesmos métodos de ciclo de vida com Plugins
• Os temas são executados após todos os plugins existentes
• Themes add component aliases by providing getThemePath.