mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-03 19:32:35 +02:00
docs(v2): write abit about plugin api
This commit is contained in:
endiliey
parent
a1ee1ab140
commit
ec221f5b7c
4 changed files with 109 additions and 119 deletions
|
|
@ -1,110 +0,0 @@
|
|||
# Docusaurus Plugins
|
||||
|
||||
Plugins are one of the best ways to add functionality to our Docusaurus. Plugins allow third-party developers to extend or modify the default functionality that Docusaurus provides.
|
||||
|
||||
## Installing a Plugin
|
||||
|
||||
A plugin is usually a dependency, so you install them like other packages in node using NPM.
|
||||
|
||||
```bash
|
||||
yarn add docusaurus-plugin-name
|
||||
```
|
||||
|
||||
Then you add it in your site's `docusaurus.config.js` plugin arrays:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
{
|
||||
name: '@docusaurus/plugin-content-pages',
|
||||
},
|
||||
{
|
||||
// Plugin with options
|
||||
name: '@docusaurus/plugin-content-blog',
|
||||
options: {
|
||||
include: ['*.md', '*.mdx'],
|
||||
path: 'blog',
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Docusaurus can also load plugins from your local folder, you can do something like below:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
{
|
||||
path: '/path/to/docusaurus-local-plugin',
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
## Basic Plugin Architecture
|
||||
|
||||
For examples, please refer to several official plugins created.
|
||||
|
||||
```js
|
||||
// A JavaScript class
|
||||
class DocusaurusPlugin {
|
||||
constructor(options, context) {
|
||||
// Initialization hook
|
||||
|
||||
// options are the plugin options set on config file
|
||||
this.options = {...options};
|
||||
|
||||
// context are provided from docusaurus. Example: siteConfig can be accessed from context
|
||||
this.context = context;
|
||||
}
|
||||
|
||||
getName() {
|
||||
// plugin name identifier
|
||||
}
|
||||
|
||||
|
||||
async loadContent()) {
|
||||
// The loadContent hook is executed after siteConfig and env has been loaded
|
||||
// You can return a JavaScript object that will be passed to contentLoaded hook
|
||||
}
|
||||
|
||||
async contentLoaded({content, actions}) {
|
||||
// contentLoaded hook is done after loadContent hook is done
|
||||
// actions are set of functional API provided by Docusaurus. e.g: addRoute
|
||||
}
|
||||
|
||||
async postBuild(props) {
|
||||
// after docusaurus <build> finish
|
||||
}
|
||||
|
||||
// TODO
|
||||
async postStart(props) {
|
||||
// docusaurus <start> finish
|
||||
}
|
||||
|
||||
// TODO
|
||||
afterDevServer(app, server) {
|
||||
// https://webpack.js.org/configuration/dev-server/#devserverbefore
|
||||
}
|
||||
|
||||
// TODO
|
||||
beforeDevServer(app, server) {
|
||||
// https://webpack.js.org/configuration/dev-server/#devserverafter
|
||||
|
||||
}
|
||||
|
||||
configureWebpack(config, isServer) {
|
||||
// Modify internal webpack config. If returned value is an Object, it will be merged into the final config using webpack-merge; If returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
|
||||
}
|
||||
|
||||
// TODO
|
||||
chainWebpack(config, isServer) {
|
||||
// Modify internal webpack config with webpack-chain API
|
||||
}
|
||||
|
||||
getPathsToWatch() {
|
||||
// path to watch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -3,7 +3,110 @@ id: plugins-api
|
|||
title: Plugins
|
||||
---
|
||||
|
||||
TODO: Plugin lifecycle APIs.
|
||||
Plugins are one of the best ways to add functionality to our Docusaurus. Plugins allow third-party developers to extend or modify the default functionality that Docusaurus provides.
|
||||
|
||||
## Installing a Plugin
|
||||
|
||||
A plugin is usually a dependency, so you install them like other packages in node using NPM.
|
||||
|
||||
```bash
|
||||
yarn add docusaurus-plugin-name
|
||||
```
|
||||
|
||||
Then you add it in your site's `docusaurus.config.js` plugin arrays:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
{
|
||||
name: '@docusaurus/plugin-content-pages',
|
||||
},
|
||||
{
|
||||
// Plugin with options
|
||||
name: '@docusaurus/plugin-content-blog',
|
||||
options: {
|
||||
include: ['*.md', '*.mdx'],
|
||||
path: 'blog',
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Docusaurus can also load plugins from your local folder, you can do something like below:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
{
|
||||
path: '/path/to/docusaurus-local-plugin',
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
## Basic Plugin Architecture
|
||||
|
||||
For examples, please refer to several official plugins created.
|
||||
|
||||
```js
|
||||
// A JavaScript class
|
||||
class DocusaurusPlugin {
|
||||
constructor(context, options) {
|
||||
// Initialization hook
|
||||
|
||||
// options are the plugin options set on config file
|
||||
this.options = {...options};
|
||||
|
||||
// context are provided from docusaurus. Example: siteConfig can be accessed from context
|
||||
this.context = context;
|
||||
}
|
||||
|
||||
getName() {
|
||||
// plugin name identifier
|
||||
}
|
||||
|
||||
|
||||
async loadContent()) {
|
||||
// The loadContent hook is executed after siteConfig and env has been loaded
|
||||
// You can return a JavaScript object that will be passed to contentLoaded hook
|
||||
}
|
||||
|
||||
async contentLoaded({content, actions}) {
|
||||
// contentLoaded hook is done after loadContent hook is done
|
||||
// actions are set of functional API provided by Docusaurus. e.g: addRoute
|
||||
}
|
||||
|
||||
async postBuild(props) {
|
||||
// after docusaurus <build> finish
|
||||
}
|
||||
|
||||
// TODO
|
||||
async postStart(props) {
|
||||
// docusaurus <start> finish
|
||||
}
|
||||
|
||||
// TODO
|
||||
afterDevServer(app, server) {
|
||||
// https://webpack.js.org/configuration/dev-server/#devserverbefore
|
||||
}
|
||||
|
||||
// TODO
|
||||
beforeDevServer(app, server) {
|
||||
// https://webpack.js.org/configuration/dev-server/#devserverafter
|
||||
|
||||
}
|
||||
|
||||
configureWebpack(config, isServer) {
|
||||
// Modify internal webpack config. If returned value is an Object, it will be merged into the final config using webpack-merge; If returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
|
||||
}
|
||||
|
||||
getPathsToWatch() {
|
||||
// path to watch
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
#### References
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ module.exports = {
|
|||
'cli',
|
||||
'docusaurus-core',
|
||||
'docusaurus.config.js',
|
||||
'plugins',
|
||||
'plugins-api',
|
||||
],
|
||||
Contributing: ['how-to-contribute', 'motivation', 'design-principles'],
|
||||
},
|
||||
|
|
|
|||
11
yarn.lock
11
yarn.lock
|
|
@ -13174,13 +13174,10 @@ unbzip2-stream@^1.0.9:
|
|||
buffer "^5.2.1"
|
||||
through "^2.3.8"
|
||||
|
||||
underscore.string@~3.3.5:
|
||||
version "3.3.5"
|
||||
resolved "https://registry.npmjs.org/underscore.string/-/underscore.string-3.3.5.tgz"
|
||||
integrity sha512-g+dpmgn+XBneLmXXo+sGlW5xQEt4ErkS3mgeN2GFbremYeMBSJKr9Wf2KJplQVaiPY/f7FN6atosWYNm9ovrYg==
|
||||
dependencies:
|
||||
sprintf-js "^1.0.3"
|
||||
util-deprecate "^1.0.2"
|
||||
underscore.string@~2.4.0:
|
||||
version "2.4.0"
|
||||
resolved "https://registry.yarnpkg.com/underscore.string/-/underscore.string-2.4.0.tgz#8cdd8fbac4e2d2ea1e7e2e8097c42f442280f85b"
|
||||
integrity sha1-jN2PusTi0uoefi6Al8QvRCKA+Fs=
|
||||
|
||||
underscore@^1.7.0:
|
||||
version "1.9.1"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue