From ec221f5b7cb83caf944c1325668667361be2adb3 Mon Sep 17 00:00:00 2001 From: endiliey Date: Wed, 1 May 2019 19:48:55 +0800 Subject: [PATCH] docs(v2): write abit about plugin api --- packages/docusaurus/plugins/README.md | 110 -------------------------- website/docs/plugins-api.md | 105 +++++++++++++++++++++++- website/sidebars.js | 2 +- yarn.lock | 11 +-- 4 files changed, 109 insertions(+), 119 deletions(-) delete mode 100644 packages/docusaurus/plugins/README.md diff --git a/packages/docusaurus/plugins/README.md b/packages/docusaurus/plugins/README.md deleted file mode 100644 index 4e397222f5..0000000000 --- a/packages/docusaurus/plugins/README.md +++ /dev/null @@ -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 finish - } - - // TODO - async postStart(props) { - // docusaurus 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 - } -} -``` diff --git a/website/docs/plugins-api.md b/website/docs/plugins-api.md index c388e6d91c..1773e970ef 100644 --- a/website/docs/plugins-api.md +++ b/website/docs/plugins-api.md @@ -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 finish + } + + // TODO + async postStart(props) { + // docusaurus 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 diff --git a/website/sidebars.js b/website/sidebars.js index fa962680f4..de77ec0c41 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -30,7 +30,7 @@ module.exports = { 'cli', 'docusaurus-core', 'docusaurus.config.js', - 'plugins', + 'plugins-api', ], Contributing: ['how-to-contribute', 'motivation', 'design-principles'], }, diff --git a/yarn.lock b/yarn.lock index e16224444e..b4fbcdc533 100644 --- a/yarn.lock +++ b/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"