diff --git a/v2/lib/load/config.js b/v2/lib/load/config.js index 161e65b546..563c331c37 100644 --- a/v2/lib/load/config.js +++ b/v2/lib/load/config.js @@ -25,8 +25,6 @@ const REQUIRED_FIELDS = [ const OPTIONAL_FIELDS = [ 'algolia', - 'chainWebpack', - 'configureWebpack', 'customDocsPath', 'customFields', 'defaultLanguage', diff --git a/v2/lib/load/index.js b/v2/lib/load/index.js index d64fc47918..2f2b9b8b6f 100644 --- a/v2/lib/load/index.js +++ b/v2/lib/load/index.js @@ -75,12 +75,26 @@ module.exports = async function load(siteDir) { const context = {env, siteDir, siteConfig}; // Initialize plugins. - const plugins = pluginConfigs.map(({name, options}) => { - // TODO: Resolve using node_modules as well. - // eslint-disable-next-line - const Plugin = require(path.resolve(__dirname, '../../plugins', name)); - return new Plugin(options, context); - }); + const pluginDir = path.resolve(__dirname, '../../plugins'); + const plugins = pluginConfigs.map( + ({name, path: pluginPath = path.join(pluginDir, name), options}) => { + let Plugin; + // If it exist in provided path or official plugin directory + if (pluginPath && fs.existsSync(pluginPath)) { + // eslint-disable-next-line + Plugin = require(pluginPath); + } else { + // Resolve using node_modules as well. + try { + // eslint-disable-next-line + Plugin = require(name); + } catch (e) { + throw new Error(`'${name}' plugin cannot be found.`); + } + } + return new Plugin(options, context); + }, + ); // Plugin lifecycle - loadContents(). // Currently plugins run lifecycle in parallel and are not order-dependent. We could change diff --git a/v2/plugins/README.md b/v2/plugins/README.md new file mode 100644 index 0000000000..0d8506d312 --- /dev/null +++ b/v2/plugins/README.md @@ -0,0 +1,78 @@ +# 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. However, you don't need to install official plugin provided by Docusaurus team because it comes by default. + +```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: '../v1/website/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) { + + // 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 loadContents() { + // Content loading hook that runs the first time plugin is loaded + // expect a content data structure to be returned + } + + async generateRoutes({metadata, actions}) { + // This is routes generation hook + } + + getPathsToWatch() { + // path to watch + } +} +```