3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-06-05 12:22:45 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(v2): write abit about plugin api

Browse source
This commit is contained in:
endiliey 2019-05-01 19:48:55 +08:00
parent a1ee1ab140
commit ec221f5b7c
4 changed files with 109 additions and 119 deletions
Download patch file Download diff file Expand all files Collapse all files

110
packages/docusaurus/plugins/README.md
View file

@ -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
}
}
```

105
website/docs/plugins-api.md
View file

@ -3,7 +3,110 @@ id: plugins-api
title: Plugins 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 #### References

2
website/sidebars.js
View file

@ -30,7 +30,7 @@ module.exports = {
'cli', 'cli',
'docusaurus-core', 'docusaurus-core',
'docusaurus.config.js', 'docusaurus.config.js',
'plugins', 'plugins-api',
], ],
Contributing: ['how-to-contribute', 'motivation', 'design-principles'], Contributing: ['how-to-contribute', 'motivation', 'design-principles'],
}, },

11
yarn.lock
View file

@ -13174,13 +13174,10 @@ unbzip2-stream@^1.0.9:
buffer "^5.2.1" buffer "^5.2.1"
through "^2.3.8" through "^2.3.8"
underscore.string@~3.3.5: underscore.string@~2.4.0:
version "3.3.5" version "2.4.0"
resolved "https://registry.npmjs.org/underscore.string/-/underscore.string-3.3.5.tgz" resolved "https://registry.yarnpkg.com/underscore.string/-/underscore.string-2.4.0.tgz#8cdd8fbac4e2d2ea1e7e2e8097c42f442280f85b"
integrity sha512-g+dpmgn+XBneLmXXo+sGlW5xQEt4ErkS3mgeN2GFbremYeMBSJKr9Wf2KJplQVaiPY/f7FN6atosWYNm9ovrYg== integrity sha1-jN2PusTi0uoefi6Al8QvRCKA+Fs=
dependencies:
sprintf-js "^1.0.3"
util-deprecate "^1.0.2"
underscore@^1.7.0: underscore@^1.7.0:
version "1.9.1" version "1.9.1"