mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
492 lines
14 KiB
Text
492 lines
14 KiB
Text
---
|
|
sidebar_position: 1
|
|
toc_max_heading_level: 4
|
|
---
|
|
|
|
# Lifecycle APIs
|
|
|
|
During the build, plugins are loaded in parallel to fetch their own contents and render them to routes. Plugins may also configure webpack or post-process the generated files.
|
|
|
|
## `async loadContent()` {#loadContent}
|
|
|
|
Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc.) or do some server processing. The return value is the content it needs.
|
|
|
|
For example, this plugin below returns a random integer between 1 and 10 as content.
|
|
|
|
```js title="docusaurus-plugin/src/index.js"
|
|
export default function (context, options) {
|
|
return {
|
|
name: 'docusaurus-plugin',
|
|
// highlight-start
|
|
async loadContent() {
|
|
return 1 + Math.floor(Math.random() * 10);
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|
|
|
|
## `async contentLoaded({content, actions})` {#contentLoaded}
|
|
|
|
The data that was loaded in `loadContent` will be consumed in `contentLoaded`. It can be rendered to routes, registered as global data, etc.
|
|
|
|
### `content` {#content}
|
|
|
|
`contentLoaded` will be called _after_ `loadContent` is done. The return value of `loadContent()` will be passed to `contentLoaded` as `content`.
|
|
|
|
### `actions` {#actions}
|
|
|
|
`actions` contain three functions:
|
|
|
|
#### `addRoute(config: RouteConfig): void` {#addRoute}
|
|
|
|
Create a route to add to the website.
|
|
|
|
```ts
|
|
export type RouteConfig = {
|
|
/**
|
|
* With leading slash. Trailing slash will be normalized by config.
|
|
*/
|
|
path: string;
|
|
/**
|
|
* Component used to render this route, a path that the bundler can `require`.
|
|
*/
|
|
component: string;
|
|
/**
|
|
* Props. Each entry should be `[propName]: pathToPropModule` (created with
|
|
* `createData`)
|
|
*/
|
|
modules?: RouteModules;
|
|
/**
|
|
* The route context will wrap the `component`. Use `useRouteContext` to
|
|
* retrieve what's declared here. Note that all custom route context declared
|
|
* here will be namespaced under {@link RouteContext.data}.
|
|
*/
|
|
context?: RouteModules;
|
|
/**
|
|
* Nested routes config, useful for "layout routes" having subroutes.
|
|
*/
|
|
routes?: RouteConfig[];
|
|
/**
|
|
* React router config option: `exact` routes would not match subroutes.
|
|
*/
|
|
exact?: boolean;
|
|
/**
|
|
* React router config option: `strict` routes are sensitive to the presence
|
|
* of a trailing slash.
|
|
*/
|
|
strict?: boolean;
|
|
/**
|
|
* Used to sort routes.
|
|
* Higher-priority routes will be matched first.
|
|
*/
|
|
priority?: number;
|
|
/**
|
|
* Optional route metadata
|
|
*/
|
|
metadata?: RouteMetadata;
|
|
/**
|
|
* Extra props; will be available on the client side.
|
|
*/
|
|
[propName: string]: unknown;
|
|
};
|
|
|
|
/**
|
|
* Plugin authors can assign extra metadata to the created routes
|
|
* It is only available on the Node.js side, and not sent to the browser
|
|
* Optional: plugin authors are encouraged but not required to provide it
|
|
*
|
|
* Some plugins might use this data to provide additional features.
|
|
* This is the case of the sitemap plugin to provide support for "lastmod".
|
|
* See also: https://github.com/facebook/docusaurus/pull/9954
|
|
*/
|
|
export type RouteMetadata = {
|
|
/**
|
|
* The source code file path that led to the creation of the current route
|
|
* In official content plugins, this is usually a Markdown or React file
|
|
* This path is expected to be relative to the site directory
|
|
*/
|
|
sourceFilePath?: string;
|
|
/**
|
|
* The last updated date of this route
|
|
* This is generally read from the Git history of the sourceFilePath
|
|
* but can also be provided through other means (usually front matter)
|
|
*
|
|
* This has notably been introduced for adding "lastmod" support to the
|
|
* sitemap plugin, see https://github.com/facebook/docusaurus/pull/9954
|
|
*/
|
|
lastUpdatedAt?: number;
|
|
};
|
|
|
|
type RouteModules = {
|
|
[module: string]: Module | RouteModules | RouteModules[];
|
|
};
|
|
|
|
type Module =
|
|
| {
|
|
path: string;
|
|
__import?: boolean;
|
|
query?: ParsedUrlQueryInput;
|
|
}
|
|
| string;
|
|
```
|
|
|
|
#### `createData(name: string, data: any): Promise<string>` {#createData}
|
|
|
|
A declarative callback to create static data (generally JSON or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
|
|
|
|
For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`:
|
|
|
|
```jsx title="website/src/components/Friends.js"
|
|
import React from 'react';
|
|
|
|
export default function FriendsComponent({friends}) {
|
|
return <div>Your friends are {friends.join(',')}</div>;
|
|
}
|
|
```
|
|
|
|
```js title="docusaurus-friends-plugin/src/index.js"
|
|
export default function friendsPlugin(context, options) {
|
|
return {
|
|
name: 'docusaurus-friends-plugin',
|
|
// highlight-start
|
|
async contentLoaded({content, actions}) {
|
|
const {createData, addRoute} = actions;
|
|
// Create friends.json
|
|
const friends = ['Yangshun', 'Sebastien'];
|
|
const friendsJsonPath = await createData(
|
|
'friends.json',
|
|
JSON.stringify(friends),
|
|
);
|
|
|
|
// Add the '/friends' routes, and ensure it receives the friends props
|
|
addRoute({
|
|
path: '/friends',
|
|
component: '@site/src/components/Friends.js',
|
|
modules: {
|
|
// propName -> JSON file path
|
|
friends: friendsJsonPath,
|
|
},
|
|
exact: true,
|
|
});
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|
|
|
|
#### `setGlobalData(data: any): void` {#setGlobalData}
|
|
|
|
This function permits one to create some global plugin data that can be read from any page, including the pages created by other plugins, and your theme layout.
|
|
|
|
This data becomes accessible to your client-side/theme code through the [`useGlobalData`](../../docusaurus-core.mdx#useGlobalData) and [`usePluginData`](../../docusaurus-core.mdx#usePluginData) hooks.
|
|
|
|
:::warning
|
|
|
|
Global data is... global: its size affects the loading time of all pages of your site, so try to keep it small. Prefer `createData` and page-specific data whenever possible.
|
|
|
|
:::
|
|
|
|
For example, this plugin below creates a `/friends` page which displays `Your friends are: Yangshun, Sebastien`:
|
|
|
|
```jsx title="website/src/components/Friends.js"
|
|
import React from 'react';
|
|
import {usePluginData} from '@docusaurus/useGlobalData';
|
|
|
|
export default function FriendsComponent() {
|
|
const {friends} = usePluginData('docusaurus-friends-plugin');
|
|
return <div>Your friends are {friends.join(',')}</div>;
|
|
}
|
|
```
|
|
|
|
```js title="docusaurus-friends-plugin/src/index.js"
|
|
export default function friendsPlugin(context, options) {
|
|
return {
|
|
name: 'docusaurus-friends-plugin',
|
|
// highlight-start
|
|
async contentLoaded({content, actions}) {
|
|
const {setGlobalData, addRoute} = actions;
|
|
// Create friends global data
|
|
setGlobalData({friends: ['Yangshun', 'Sebastien']});
|
|
|
|
// Add the '/friends' routes
|
|
addRoute({
|
|
path: '/friends',
|
|
component: '@site/src/components/Friends.js',
|
|
exact: true,
|
|
});
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|
|
|
|
## `configureWebpack(config, isServer, utils, content)` {#configureWebpack}
|
|
|
|
Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the second argument.
|
|
|
|
:::warning
|
|
|
|
The API of `configureWebpack` will be modified in the future to accept an object (`configureWebpack({config, isServer, utils, content})`)
|
|
|
|
:::
|
|
|
|
### `config` {#config}
|
|
|
|
`configureWebpack` is called with `config` generated according to client/server build. You may treat this as the base config to be merged with.
|
|
|
|
### `isServer` {#isServer}
|
|
|
|
`configureWebpack` will be called both in server build and in client build. The server build receives `true` and the client build receives `false` as `isServer`.
|
|
|
|
### `utils` {#utils}
|
|
|
|
`configureWebpack` also receives an util object:
|
|
|
|
- `getStyleLoaders(isServer: boolean, cssOptions: {[key: string]: any}): Loader[]`
|
|
- `getJSLoader(isServer: boolean, cacheOptions?: {}): Loader | null`
|
|
|
|
You may use them to return your webpack configuration conditionally.
|
|
|
|
For example, this plugin below modify the webpack config to transpile `.foo` files.
|
|
|
|
```js title="docusaurus-plugin/src/index.js"
|
|
export default function (context, options) {
|
|
return {
|
|
name: 'custom-docusaurus-plugin',
|
|
// highlight-start
|
|
configureWebpack(config, isServer, utils) {
|
|
const {getJSLoader} = utils;
|
|
return {
|
|
module: {
|
|
rules: [
|
|
{
|
|
test: /\.foo$/,
|
|
use: [getJSLoader(isServer), 'my-custom-webpack-loader'],
|
|
},
|
|
],
|
|
},
|
|
};
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|
|
|
|
### `content` {#content-1}
|
|
|
|
`configureWebpack` will be called both with the content loaded by the plugin.
|
|
|
|
### Merge strategy {#merge-strategy}
|
|
|
|
We merge the Webpack configuration parts of plugins into the global Webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
|
|
|
|
It is possible to specify the merge strategy. For example, if you want a webpack rule to be prepended instead of appended:
|
|
|
|
```js title="docusaurus-plugin/src/index.js"
|
|
export default function (context, options) {
|
|
return {
|
|
name: 'custom-docusaurus-plugin',
|
|
configureWebpack(config, isServer, utils) {
|
|
return {
|
|
// highlight-start
|
|
mergeStrategy: {'module.rules': 'prepend'},
|
|
module: {rules: [myRuleToPrepend]},
|
|
// highlight-end
|
|
};
|
|
},
|
|
};
|
|
}
|
|
```
|
|
|
|
Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details.
|
|
|
|
### Configuring dev server {#configuring-dev-server}
|
|
|
|
The dev server can be configured through returning a `devServer` field.
|
|
|
|
```js title="docusaurus-plugin/src/index.js"
|
|
export default function (context, options) {
|
|
return {
|
|
name: 'custom-docusaurus-plugin',
|
|
configureWebpack(config, isServer, utils) {
|
|
return {
|
|
// highlight-start
|
|
devServer: {
|
|
open: '/docs', // Opens localhost:3000/docs instead of localhost:3000/
|
|
},
|
|
// highlight-end
|
|
};
|
|
},
|
|
};
|
|
}
|
|
```
|
|
|
|
## `configurePostCss(options)` {#configurePostCss}
|
|
|
|
Modifies [`postcssOptions` of `postcss-loader`](https://webpack.js.org/loaders/postcss-loader/#postcssoptions) during the generation of the client bundle.
|
|
|
|
Should return the mutated `postcssOptions`.
|
|
|
|
By default, `postcssOptions` looks like this:
|
|
|
|
```js
|
|
const postcssOptions = {
|
|
ident: 'postcss',
|
|
plugins: [require('autoprefixer')],
|
|
};
|
|
```
|
|
|
|
Example:
|
|
|
|
```js title="docusaurus-plugin/src/index.js"
|
|
export default function (context, options) {
|
|
return {
|
|
name: 'docusaurus-plugin',
|
|
// highlight-start
|
|
configurePostCss(postcssOptions) {
|
|
// Appends new PostCSS plugin.
|
|
postcssOptions.plugins.push(require('postcss-import'));
|
|
return postcssOptions;
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|
|
|
|
## `postBuild(props)` {#postBuild}
|
|
|
|
Called when a (production) build finishes.
|
|
|
|
```ts
|
|
interface Props {
|
|
siteDir: string;
|
|
generatedFilesDir: string;
|
|
siteConfig: DocusaurusConfig;
|
|
outDir: string;
|
|
baseUrl: string;
|
|
headTags: string;
|
|
preBodyTags: string;
|
|
postBodyTags: string;
|
|
routesPaths: string[];
|
|
plugins: Plugin<any>[];
|
|
content: Content;
|
|
}
|
|
```
|
|
|
|
Example:
|
|
|
|
```js title="docusaurus-plugin/src/index.js"
|
|
export default function (context, options) {
|
|
return {
|
|
name: 'docusaurus-plugin',
|
|
// highlight-start
|
|
async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
|
|
// Print out to console all the rendered routes.
|
|
routesPaths.map((route) => {
|
|
console.log(route);
|
|
});
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|
|
|
|
## `injectHtmlTags({content})` {#injectHtmlTags}
|
|
|
|
Inject head and/or body HTML tags to Docusaurus generated HTML.
|
|
|
|
`injectHtmlTags` will be called both with the content loaded by the plugin.
|
|
|
|
```ts
|
|
function injectHtmlTags(): {
|
|
headTags?: HtmlTags;
|
|
preBodyTags?: HtmlTags;
|
|
postBodyTags?: HtmlTags;
|
|
};
|
|
|
|
type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
|
|
|
|
type HtmlTagObject = {
|
|
/**
|
|
* Attributes of the HTML tag
|
|
* E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
|
|
*/
|
|
attributes?: {
|
|
[attributeName: string]: string | boolean;
|
|
};
|
|
/**
|
|
* The tag name e.g. `div`, `script`, `link`, `meta`
|
|
*/
|
|
tagName: string;
|
|
/**
|
|
* The inner HTML
|
|
*/
|
|
innerHTML?: string;
|
|
};
|
|
```
|
|
|
|
Example:
|
|
|
|
```js title="docusaurus-plugin/src/index.js"
|
|
export default function (context, options) {
|
|
return {
|
|
name: 'docusaurus-plugin',
|
|
loadContent: async () => {
|
|
return {remoteHeadTags: await fetchHeadTagsFromAPI()};
|
|
},
|
|
// highlight-start
|
|
injectHtmlTags({content}) {
|
|
return {
|
|
headTags: [
|
|
{
|
|
tagName: 'link',
|
|
attributes: {
|
|
rel: 'preconnect',
|
|
href: 'https://www.github.com',
|
|
},
|
|
},
|
|
...content.remoteHeadTags,
|
|
],
|
|
preBodyTags: [
|
|
{
|
|
tagName: 'script',
|
|
attributes: {
|
|
charset: 'utf-8',
|
|
src: '/noflash.js',
|
|
},
|
|
},
|
|
],
|
|
postBodyTags: [`<div> This is post body </div>`],
|
|
};
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|
|
|
|
Tags will be added as follows:
|
|
|
|
- `headTags` will be inserted before the closing `</head>` tag after scripts added by config.
|
|
- `preBodyTags` will be inserted after the opening `<body>` tag before any child elements.
|
|
- `postBodyTags` will be inserted before the closing `</body>` tag after all child elements.
|
|
|
|
## `getClientModules()` {#getClientModules}
|
|
|
|
Returns an array of paths to the [client modules](../../advanced/client.mdx#client-modules) that are to be imported into the client bundle.
|
|
|
|
As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user:
|
|
|
|
```js title="my-theme/src/index.js"
|
|
export default function (context, options) {
|
|
const {customCss, customJs} = options || {};
|
|
return {
|
|
name: 'name-of-my-theme',
|
|
// highlight-start
|
|
getClientModules() {
|
|
return [customCss, customJs];
|
|
},
|
|
// highlight-end
|
|
};
|
|
}
|
|
```
|