This page explains the plugin system's lifecycle in Docusaurus, covering plugin initialization, validation, and the sequence of lifecycle hooks that plugins implement. It also details preset expansion, plugin ordering, and the swizzle command.
Plugins are the fundamental building blocks of Docusaurus. The plugin lifecycle defines a predictable sequence of phases through which each plugin progresses, from initialization through content loading and webpack configuration to static output.
A Docusaurus plugin is a function (or a module exporting one) that returns a Plugin object. Plugins are identified by a unique combination of their name and id.
Diagram: Plugin Code Entities and Structure
Sources: packages/docusaurus-types/src/plugin.d.ts124-180 packages/docusaurus-types/src/plugin.d.ts205-216 packages/docusaurus/src/server/plugins/init.ts26-50
The initialization phase occurs when Docusaurus starts. It involves loading plugin configurations from docusaurus.config.js, expanding presets, validating options, and instantiating plugins.
Plugins are loaded in a specific order. Presets (like preset-classic) expand into a collection of plugins and themes.
@docusaurus/theme-classic packages/docusaurus-preset-classic/src/index.ts48-51@docusaurus/plugin-content-docs, @docusaurus/plugin-content-blog packages/docusaurus-preset-classic/src/index.ts78-86docusaurus.config.js packages/docusaurus/src/server/plugins/init.ts192-202The initPlugins function orchestrates the setup packages/docusaurus/src/server/plugins/init.ts192-202
Diagram: Plugin Initialization Data Flow
Key Logic:
null to explicitly disable themselves based on context or options packages/docusaurus/src/server/plugins/init.ts148-150validateOptions ensures all plugins have an id (defaulting to default) packages/docusaurus/src/server/plugins/init.ts118-121themeConfig. This validation happens before the plugin constructor is called packages/docusaurus/src/server/plugins/init.ts132-138Sources: packages/docusaurus/src/server/plugins/init.ts71-186 packages/docusaurus-types/src/plugin.d.ts205-216
Plugins implement specific hooks called by the Docusaurus engine during the build process.
loadContent: The primary hook for data ingestion. It returns arbitrary data (the "Content") packages/docusaurus-types/src/plugin.d.ts126contentLoaded: Receives the loaded content and an actions object.
addRoute: Registers a new URL path packages/docusaurus-types/src/plugin.d.ts51setGlobalData: Makes data available to the client-side via useGlobalData packages/docusaurus-types/src/plugin.d.ts53allContentLoaded: A global hook executed after all plugins have finished contentLoaded. It allows plugins to access data from other plugins via allContent packages/docusaurus-types/src/plugin.d.ts132-135configureWebpack: Modifies the internal Webpack/Rspack configuration. It provides utilities like getStyleLoaders and getJSLoader packages/docusaurus-types/src/plugin.d.ts145-150postBuild: Executed after the static site is generated. It receives routesBuildMetadata to perform tasks like sitemap generation or search indexing packages/docusaurus-types/src/plugin.d.ts136-141injectHtmlTags: Allows adding scripts, styles, or meta tags to the HTML head or body packages/docusaurus-types/src/plugin.d.ts157-161Sources: packages/docusaurus-types/src/plugin.d.ts50-54 packages/docusaurus-types/src/plugin.d.ts124-180 packages/docusaurus/src/server/plugins/plugins.ts73-137
Swizzling is the mechanism for overriding theme components. It is managed by the swizzle command packages/docusaurus/src/commands/swizzle/index.ts14
| Action | Description |
|---|---|
wrap | Creates a wrapper around the original theme component using @theme-init/ComponentName. This allows adding logic around a component without duplicating its code packages/docusaurus/src/commands/swizzle/actions.ts113-167 |
eject | Copies the original source code to the user's src/theme directory for full customization packages/docusaurus/src/commands/swizzle/actions.ts49-111 |
The SwizzleConfig allows theme authors to define which components are safe to swizzle packages/docusaurus-types/src/plugin.d.ts215
Sources: packages/docusaurus/src/commands/swizzle/actions.ts17-30 packages/docusaurus/src/commands/swizzle/__tests__/index.test.ts86-114
During the build, plugins register routes which are then processed for Static Site Generation (SSG).
Diagram: Route Generation to Static Output
The executeSSG function handles the parallel rendering of pages. If ssgWorkerThreads is enabled in the configuration, it uses a Tinypool thread pool to distribute rendering tasks across multiple CPU cores packages/docusaurus/src/ssg/ssgExecutor.ts101-139
Sources: packages/docusaurus/src/ssg/ssgExecutor.ts174-208 packages/docusaurus/src/server/plugins/plugins.ts191-228
The lifecycle is triggered via the Docusaurus CLI.
bin/docusaurus.mjs script initializes environment variables and calls runCLI packages/docusaurus/bin/docusaurus.mjs14-44build or start invoke loadContext, which in turn triggers initPlugins and the subsequent lifecycle hooks packages/docusaurus/src/server/plugins/init.ts192-202Sources: packages/docusaurus/bin/docusaurus.mjs1-47 packages/docusaurus/src/server/plugins/init.ts1-25
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.