3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-11 08:07:26 +02:00
Code Issues Projects Releases Packages Wiki Activity

refactor(v2): change plugin api (#1547)

Browse source 
* misc(v2): new plugin format example

* refactor(v2): make all plugins a function returning objects

* misc: add CHANGELOG

* misc(v2): update CHANGELOG

* misc(v2): fix tests

* misc(v2): convert swizzle command

* misc(v2): convert sitemap back to commonjs
This commit is contained in:
Yangshun Tay 2019-06-02 20:37:22 -07:00 • committed by GitHub
parent 9feb7b2c64
commit 6a814ac64a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
18 changed files with 709 additions and 725 deletions
Download patch file Download diff file Expand all files Collapse all files

66
packages/docusaurus-plugin-content-blog/src/index.js
View file

@ -31,30 +31,24 @@ const DEFAULT_OPTIONS = {
blogTagsPostsComponent: '@theme/BlogTagsPostsPage', blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
}; };
class DocusaurusPluginContentBlog { module.exports = function(context, opts) {
constructor(context, opts) { const options = {...DEFAULT_OPTIONS, ...opts};
this.options = {...DEFAULT_OPTIONS, ...opts}; const contentPath = path.resolve(context.siteDir, options.path);
this.context = context;
this.contentPath = path.resolve(this.context.siteDir, this.options.path);
}
getName() { return {
return 'docusaurus-plugin-content-blog'; name: 'docusaurus-plugin-content-blog',
}
getPathsToWatch() { getPathsToWatch() {
const {include = []} = this.options; const {include = []} = options;
const globPattern = include.map( const globPattern = include.map(pattern => `${contentPath}/${pattern}`);
pattern => `${this.contentPath}/${pattern}`,
);
return [...globPattern]; return [...globPattern];
} },
// Fetches blog contents and returns metadata for the necessary routes. // Fetches blog contents and returns metadata for the necessary routes.
async loadContent() { async loadContent() {
const {postsPerPage, include, routeBasePath} = this.options; const {postsPerPage, include, routeBasePath} = options;
const {siteConfig} = this.context; const {siteConfig} = context;
const blogDir = this.contentPath; const blogDir = contentPath;
if (!fs.existsSync(blogDir)) { if (!fs.existsSync(blogDir)) {
return null; return null;
@ -126,7 +120,9 @@ class DocusaurusPluginContentBlog {
totalCount, totalCount,
previousPage: page !== 0 ? blogPaginationPermalink(page - 1) : null, previousPage: page !== 0 ? blogPaginationPermalink(page - 1) : null,
nextPage: nextPage:
page < numberOfPages - 1 ? blogPaginationPermalink(page + 1) : null, page < numberOfPages - 1
? blogPaginationPermalink(page + 1)
: null,
}, },
items: blogPosts items: blogPosts
.slice(page * postsPerPage, (page + 1) * postsPerPage) .slice(page * postsPerPage, (page + 1) * postsPerPage)
@ -166,7 +162,8 @@ class DocusaurusPluginContentBlog {
}); });
}); });
const blogTagsListPath = Object.keys(blogTags).length > 0 ? tagsPath : null; const blogTagsListPath =
Object.keys(blogTags).length > 0 ? tagsPath : null;
return { return {
blogPosts, blogPosts,
@ -174,7 +171,7 @@ class DocusaurusPluginContentBlog {
blogTags, blogTags,
blogTagsListPath, blogTagsListPath,
}; };
} },
async contentLoaded({content: blogContents, actions}) { async contentLoaded({content: blogContents, actions}) {
if (!blogContents) { if (!blogContents) {
@ -186,7 +183,7 @@ class DocusaurusPluginContentBlog {
blogPostComponent, blogPostComponent,
blogTagsListComponent, blogTagsListComponent,
blogTagsPostsComponent, blogTagsPostsComponent,
} = this.options; } = options;
const {addRoute, createData} = actions; const {addRoute, createData} = actions;
const { const {
@ -252,9 +249,10 @@ class DocusaurusPluginContentBlog {
exact: true, exact: true,
modules: { modules: {
items: items.map(postID => { items: items.map(postID => {
const {metadata: postMetadata, metadataPath} = blogItemsToModules[ const {
postID metadata: postMetadata,
]; metadataPath,
} = blogItemsToModules[postID];
// To tell routes.js this is an import and not a nested object to recurse. // To tell routes.js this is an import and not a nested object to recurse.
return { return {
content: { content: {
@ -299,9 +297,10 @@ class DocusaurusPluginContentBlog {
exact: true, exact: true,
modules: { modules: {
items: items.map(postID => { items: items.map(postID => {
const {metadata: postMetadata, metadataPath} = blogItemsToModules[ const {
postID metadata: postMetadata,
]; metadataPath,
} = blogItemsToModules[postID];
return { return {
content: { content: {
__import: true, __import: true,
@ -335,11 +334,11 @@ class DocusaurusPluginContentBlog {
}, },
}); });
} }
} },
getThemePath() { getThemePath() {
return path.resolve(__dirname, './theme'); return path.resolve(__dirname, './theme');
} },
configureWebpack(config, isServer, {getBabelLoader, getCacheLoader}) { configureWebpack(config, isServer, {getBabelLoader, getCacheLoader}) {
return { return {
@ -347,7 +346,7 @@ class DocusaurusPluginContentBlog {
rules: [ rules: [
{ {
test: /(\.mdx?)$/, test: /(\.mdx?)$/,
include: [this.contentPath], include: [contentPath],
use: [ use: [
getCacheLoader(isServer), getCacheLoader(isServer),
getBabelLoader(isServer), getBabelLoader(isServer),
@ -360,7 +359,6 @@ class DocusaurusPluginContentBlog {
], ],
}, },
}; };
} },
} };
};
module.exports = DocusaurusPluginContentBlog;

5
packages/docusaurus-plugin-content-docs/src/__tests__/index.test.js
View file

@ -6,7 +6,7 @@
*/ */
import path from 'path'; import path from 'path';
import DocusaurusPluginContentDocs from '../index'; import pluginContentDocs from '../index';
describe('loadDocs', () => { describe('loadDocs', () => {
test('simple website', async () => { test('simple website', async () => {
@ -17,7 +17,7 @@ describe('loadDocs', () => {
url: 'https://docusaurus.io', url: 'https://docusaurus.io',
}; };
const sidebarPath = path.join(siteDir, 'sidebars.json'); const sidebarPath = path.join(siteDir, 'sidebars.json');
const plugin = new DocusaurusPluginContentDocs( const plugin = pluginContentDocs(
{ {
siteDir, siteDir,
siteConfig, siteConfig,
@ -41,6 +41,7 @@ describe('loadDocs', () => {
title: 'Hello, World !', title: 'Hello, World !',
description: `Hi, Endilie here :)`, description: `Hi, Endilie here :)`,
}); });
expect(docsMetadata['foo/bar']).toEqual({ expect(docsMetadata['foo/bar']).toEqual({
category: 'Test', category: 'Test',
id: 'foo/bar', id: 'foo/bar',

64
packages/docusaurus-plugin-content-docs/src/index.js
View file

@ -25,31 +25,27 @@ const DEFAULT_OPTIONS = {
docItemComponent: '@theme/DocItem', docItemComponent: '@theme/DocItem',
}; };
class DocusaurusPluginContentDocs { module.exports = function(context, opts) {
constructor(context, opts) { const options = {...DEFAULT_OPTIONS, ...opts};
this.options = {...DEFAULT_OPTIONS, ...opts}; const contentPath = path.resolve(context.siteDir, options.path);
this.context = context; let globalContents = {};
this.contentPath = path.resolve(this.context.siteDir, this.options.path);
this.content = {};
}
getName() { return {
return 'docusaurus-plugin-content-docs'; name: 'docusaurus-plugin-content-docs',
}
contentPath,
getPathsToWatch() { getPathsToWatch() {
const {include = []} = this.options; const {include = []} = options;
const globPattern = include.map( const globPattern = include.map(pattern => `${contentPath}/${pattern}`);
pattern => `${this.contentPath}/${pattern}`, return [...globPattern, options.sidebarPath];
); },
return [...globPattern, this.options.sidebarPath];
}
// Fetches blog contents and returns metadata for the contents. // Fetches blog contents and returns metadata for the contents.
async loadContent() { async loadContent() {
const {include, routeBasePath, sidebarPath} = this.options; const {include, routeBasePath, sidebarPath} = options;
const {siteConfig} = this.context; const {siteConfig} = context;
const docsDir = this.contentPath; const docsDir = contentPath;
if (!fs.existsSync(docsDir)) { if (!fs.existsSync(docsDir)) {
return null; return null;
@ -101,7 +97,7 @@ class DocusaurusPluginContentDocs {
permalinkToId[permalink] = id; permalinkToId[permalink] = id;
}); });
this.content = { globalContents = {
docs, docs,
docsDir, docsDir,
docsSidebars, docsSidebars,
@ -109,14 +105,15 @@ class DocusaurusPluginContentDocs {
permalinkToId, permalinkToId,
}; };
return this.content; return globalContents;
} },
async contentLoaded({content, actions}) { async contentLoaded({content, actions}) {
if (!content) { if (!content) {
return; return;
} }
const {docLayoutComponent, docItemComponent, routeBasePath} = this.options;
const {docLayoutComponent, docItemComponent, routeBasePath} = options;
const {addRoute, createData} = actions; const {addRoute, createData} = actions;
const routes = await Promise.all( const routes = await Promise.all(
@ -138,7 +135,7 @@ class DocusaurusPluginContentDocs {
); );
const docsBaseRoute = normalizeUrl([ const docsBaseRoute = normalizeUrl([
this.context.siteConfig.baseUrl, context.siteConfig.baseUrl,
routeBasePath, routeBasePath,
]); ]);
const docsMetadataPath = await createData( const docsMetadataPath = await createData(
@ -154,11 +151,11 @@ class DocusaurusPluginContentDocs {
docsMetadata: docsMetadataPath, docsMetadata: docsMetadataPath,
}, },
}); });
} },
getThemePath() { getThemePath() {
return path.resolve(__dirname, './theme'); return path.resolve(__dirname, './theme');
} },
configureWebpack(config, isServer, {getBabelLoader, getCacheLoader}) { configureWebpack(config, isServer, {getBabelLoader, getCacheLoader}) {
return { return {
@ -166,7 +163,7 @@ class DocusaurusPluginContentDocs {
rules: [ rules: [
{ {
test: /(\.mdx?)$/, test: /(\.mdx?)$/,
include: [this.contentPath], include: [contentPath],
use: [ use: [
getCacheLoader(isServer), getCacheLoader(isServer),
getBabelLoader(isServer), getBabelLoader(isServer),
@ -174,9 +171,9 @@ class DocusaurusPluginContentDocs {
{ {
loader: path.resolve(__dirname, './markdown/index.js'), loader: path.resolve(__dirname, './markdown/index.js'),
options: { options: {
siteConfig: this.context.siteConfig, siteConfig: context.siteConfig,
docsDir: this.content.docsDir, docsDir: globalContents.docsDir,
sourceToPermalink: this.content.sourceToPermalink, sourceToPermalink: globalContents.sourceToPermalink,
}, },
}, },
], ],
@ -184,7 +181,6 @@ class DocusaurusPluginContentDocs {
], ],
}, },
}; };
} },
} };
};
module.exports = DocusaurusPluginContentDocs;

4
packages/docusaurus-plugin-content-pages/src/__tests__/index.test.js
View file

@ -7,7 +7,7 @@
import path from 'path'; import path from 'path';
import DocusaurusPluginContentPages from '../index'; import pluginContentPages from '../index';
describe('docusaurus-plugin-content-pages', () => { describe('docusaurus-plugin-content-pages', () => {
test('simple pages', async () => { test('simple pages', async () => {
@ -17,7 +17,7 @@ describe('docusaurus-plugin-content-pages', () => {
url: 'https://docusaurus.io', url: 'https://docusaurus.io',
}; };
const siteDir = path.join(__dirname, '__fixtures__', 'website'); const siteDir = path.join(__dirname, '__fixtures__', 'website');
const plugin = new DocusaurusPluginContentPages({ const plugin = pluginContentPages({
siteDir, siteDir,
siteConfig, siteConfig,
}); });

39
packages/docusaurus-plugin-content-pages/src/index.js
View file

@ -16,29 +16,25 @@ const DEFAULT_OPTIONS = {
include: ['**/*.{js,jsx}'], // Extensions to include. include: ['**/*.{js,jsx}'], // Extensions to include.
}; };
class DocusaurusPluginContentPages { module.exports = function(context, opts) {
constructor(context, opts) { const options = {...DEFAULT_OPTIONS, ...opts};
this.options = {...DEFAULT_OPTIONS, ...opts}; const contentPath = path.resolve(context.siteDir, options.path);
this.context = context;
this.contentPath = path.resolve(this.context.siteDir, this.options.path);
}
getName() { return {
return 'docusaurus-plugin-content-pages'; name: 'docusaurus-plugin-content-pages',
}
contentPath,
getPathsToWatch() { getPathsToWatch() {
const {include = []} = this.options; const {include = []} = options;
const globPattern = include.map( const globPattern = include.map(pattern => `${contentPath}/${pattern}`);
pattern => `${this.contentPath}/${pattern}`,
);
return [...globPattern]; return [...globPattern];
} },
async loadContent() { async loadContent() {
const {include} = this.options; const {include} = options;
const {siteConfig} = this.context; const {siteConfig} = context;
const pagesDir = this.contentPath; const pagesDir = contentPath;
if (!fs.existsSync(pagesDir)) { if (!fs.existsSync(pagesDir)) {
return null; return null;
@ -58,7 +54,7 @@ class DocusaurusPluginContentPages {
source, source,
}; };
}); });
} },
async contentLoaded({content, actions}) { async contentLoaded({content, actions}) {
if (!content) { if (!content) {
@ -84,7 +80,6 @@ class DocusaurusPluginContentPages {
}); });
}), }),
); );
} },
} };
};
module.exports = DocusaurusPluginContentPages;

30
packages/docusaurus-plugin-sitemap/src/__tests__/createSitemap.test.js Normal file
View file

@ -0,0 +1,30 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import createSitemap from '../createSitemap';
describe('createSitemap', () => {
test('simple site', () => {
const sitemap = createSitemap({
siteConfig: {
url: 'https://example.com',
},
routesPaths: ['/', '/test'],
});
expect(sitemap).toContain(
`<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">`,
);
});
test('empty site', () => {
expect(() => {
createSitemap({});
}).toThrowErrorMatchingInlineSnapshot(
`"Url in docusaurus.config.js cannot be empty/undefined"`,
);
});
});

36
packages/docusaurus-plugin-sitemap/src/__tests__/index.test.js
View file

@ -1,36 +0,0 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import DocusaurusPluginSitemap from '../index';
describe('docusaurus-plugin-sitemap', () => {
describe('createSitemap', () => {
test('simple site', async () => {
const context = {
siteConfig: {
url: 'https://example.com',
},
routesPaths: ['/', '/test'],
};
const plugin = new DocusaurusPluginSitemap(context, null);
const sitemap = await plugin.createSitemap(context);
expect(sitemap).toContain(
`<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">`,
);
});
test('empty site', async () => {
const context = {};
const plugin = new DocusaurusPluginSitemap(context, null);
expect(
plugin.createSitemap(context),
).rejects.toThrowErrorMatchingInlineSnapshot(
`"Url in docusaurus.config.js cannot be empty/undefined"`,
);
});
});
});

33
packages/docusaurus-plugin-sitemap/src/createSitemap.js Normal file
View file

@ -0,0 +1,33 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
const sitemap = require('sitemap');
module.exports = function createSitemap({
siteConfig = {},
routesPaths,
options = {},
}) {
const {url: hostname} = siteConfig;
if (!hostname) {
throw new Error('Url in docusaurus.config.js cannot be empty/undefined');
}
const urls = routesPaths.map(routesPath => ({
url: routesPath,
changefreq: options.changefreq,
priority: options.priority,
}));
return sitemap
.createSitemap({
hostname,
cacheTime: options.cacheTime,
urls,
})
.toString();
};

48
packages/docusaurus-plugin-sitemap/src/index.js
View file

@ -6,52 +6,29 @@
*/ */
const fs = require('fs'); const fs = require('fs');
const sitemap = require('sitemap');
const path = require('path'); const path = require('path');
const createSitemap = require('./createSitemap');
const DEFAULT_OPTIONS = { const DEFAULT_OPTIONS = {
cacheTime: 600 * 1000, // 600 sec - cache purge period cacheTime: 600 * 1000, // 600 sec - cache purge period
changefreq: 'weekly', changefreq: 'weekly',
priority: 0.5, priority: 0.5,
}; };
class DocusaurusPluginSitemap { module.exports = function(context, opts) {
constructor(context, opts) { const options = {...DEFAULT_OPTIONS, ...opts};
this.options = {...DEFAULT_OPTIONS, ...opts};
this.context = context;
}
getName() { return {
return 'docusaurus-plugin-sitemap'; name: 'docusaurus-plugin-sitemap',
}
async createSitemap({siteConfig = {}, routesPaths}) {
const {url: hostname} = siteConfig;
if (!hostname) {
throw new Error(`Url in docusaurus.config.js cannot be empty/undefined`);
}
const urls = routesPaths.map(routesPath => ({
url: routesPath,
changefreq: this.changefreq,
priority: this.priority,
}));
return sitemap
.createSitemap({
hostname,
cacheTime: this.cacheTime,
urls,
})
.toString();
}
async postBuild({siteConfig = {}, routesPaths = [], outDir}) { async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
// Generate sitemap // Generate sitemap
const generatedSitemap = await this.createSitemap({ const generatedSitemap = createSitemap({
siteConfig, siteConfig,
routesPaths, routesPaths,
}); options,
}).toString();
// Write sitemap file // Write sitemap file
const sitemapPath = path.join(outDir, 'sitemap.xml'); const sitemapPath = path.join(outDir, 'sitemap.xml');
@ -60,7 +37,6 @@ class DocusaurusPluginSitemap {
throw new Error(`Sitemap error: ${err}`); throw new Error(`Sitemap error: ${err}`);
} }
}); });
} },
} };
};
module.exports = DocusaurusPluginSitemap;

12
packages/docusaurus-preset-classic/src/index.js
View file

@ -9,27 +9,27 @@ module.exports = function preset(context, opts = {}) {
return { return {
themes: [ themes: [
{ {
name: '@docusaurus/theme-classic', module: '@docusaurus/theme-classic',
}, },
{ {
name: '@docusaurus/theme-search-algolia', module: '@docusaurus/theme-search-algolia',
}, },
], ],
plugins: [ plugins: [
{ {
name: '@docusaurus/plugin-content-docs', module: '@docusaurus/plugin-content-docs',
options: opts.docs, options: opts.docs,
}, },
{ {
name: '@docusaurus/plugin-content-blog', module: '@docusaurus/plugin-content-blog',
options: opts.blog, options: opts.blog,
}, },
{ {
name: '@docusaurus/plugin-content-pages', module: '@docusaurus/plugin-content-pages',
options: opts.pages, options: opts.pages,
}, },
{ {
name: '@docusaurus/plugin-sitemap', module: '@docusaurus/plugin-sitemap',
options: opts.sitemap, options: opts.sitemap,
}, },
], ],

21
packages/docusaurus-theme-classic/src/index.js
View file

@ -7,21 +7,12 @@
const path = require('path'); const path = require('path');
const DEFAULT_OPTIONS = {}; module.exports = function() {
return {
class DocusaurusThemeClassic { name: 'docusaurus-theme-classic',
constructor(context, opts) {
this.options = {...DEFAULT_OPTIONS, ...opts};
this.context = context;
}
getName() {
return 'docusaurus-theme-classic';
}
getThemePath() { getThemePath() {
return path.resolve(__dirname, './theme'); return path.resolve(__dirname, './theme');
} },
} };
};
module.exports = DocusaurusThemeClassic;

21
packages/docusaurus-theme-search-algolia/src/index.js
View file

@ -7,21 +7,12 @@
const path = require('path'); const path = require('path');
const DEFAULT_OPTIONS = {}; module.exports = function() {
return {
class DocusaurusThemeSearchAlgolia { name: 'docusaurus-theme-search-algolia',
constructor(context, opts) {
this.options = {...DEFAULT_OPTIONS, ...opts};
this.context = context;
}
getName() {
return 'docusaurus-theme-search-algolia';
}
getThemePath() { getThemePath() {
return path.resolve(__dirname, './theme'); return path.resolve(__dirname, './theme');
} },
} };
};
module.exports = DocusaurusThemeSearchAlgolia;

10
packages/docusaurus/CHANGES.md → packages/docusaurus/CHANGELOG.md
View file

@ -1,4 +1,12 @@
# Breaking Changes # Docusaurus 2 Changelog
## 2.0.0-alpha.19
- Changed plugin definitions from classes to functions. Refer to the new plugin docs.
- Added sun and moon emoji to the dark mode toggle.
- Add a sensible default for browserslist config.
## V2 Changelog
### `siteConfig.js` changes ### `siteConfig.js` changes

7
packages/docusaurus/src/commands/swizzle.ts
View file

@ -15,10 +15,9 @@ export async function swizzle(
themeName: string, themeName: string,
componentName?: string, componentName?: string,
): Promise<void> { ): Promise<void> {
const Plugin = importFresh(themeName); const plugin = importFresh(themeName);
const context = {siteDir}; const pluginInstance = plugin({siteDir});
const PluginInstance = new Plugin(context); let fromPath = pluginInstance.getThemePath();
let fromPath = PluginInstance.getThemePath();
if (fromPath) { if (fromPath) {
let toPath = path.resolve(siteDir, 'theme'); let toPath = path.resolve(siteDir, 'theme');

4
packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js
View file

@ -15,14 +15,14 @@ module.exports = {
favicon: 'img/docusaurus.ico', favicon: 'img/docusaurus.ico',
plugins: [ plugins: [
{ {
name: '@docusaurus/plugin-content-docs', module: '@docusaurus/plugin-content-docs',
options: { options: {
path: '../docs', path: '../docs',
sidebarPath: require.resolve('./sidebars.json'), sidebarPath: require.resolve('./sidebars.json'),
}, },
}, },
{ {
name: '@docusaurus/plugin-content-pages', module: '@docusaurus/plugin-content-pages',
}, },
], ],
}; };

4
packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js
View file

@ -15,14 +15,14 @@ module.exports = {
favicon: 'img/docusaurus.ico', favicon: 'img/docusaurus.ico',
plugins: [ plugins: [
{ {
name: '@docusaurus/plugin-content-docs', module: '@docusaurus/plugin-content-docs',
options: { options: {
path: '../docs', path: '../docs',
sidebarPath: require.resolve('./sidebars.json'), sidebarPath: require.resolve('./sidebars.json'),
}, },
}, },
{ {
name: '@docusaurus/plugin-content-pages', module: '@docusaurus/plugin-content-pages',
}, },
], ],
}; };

19
packages/docusaurus/src/server/plugins/index.ts
View file

@ -19,14 +19,10 @@ export async function loadPlugins({
context: LoadContext; context: LoadContext;
}) { }) {
// 1. Plugin Lifecycle - Initialization/Constructor // 1. Plugin Lifecycle - Initialization/Constructor
const plugins = pluginConfigs.map(({name, path: pluginPath, options}) => { const plugins = pluginConfigs.map(({module, options}) => {
let Plugin; // module is any valid module identifier - npm package or locally-resolved path.
if (pluginPath && fs.existsSync(pluginPath)) { const plugin = importFresh(module);
Plugin = importFresh(pluginPath); return plugin(context, options);
} else {
Plugin = importFresh(name);
}
return new Plugin(context, options);
}); });
// 2. Plugin lifecycle - loadContent // 2. Plugin lifecycle - loadContent
@ -51,8 +47,11 @@ export async function loadPlugins({
if (!plugin.contentLoaded) { if (!plugin.contentLoaded) {
return; return;
} }
const pluginName = plugin.getName();
const pluginContentDir = path.join(context.generatedFilesDir, pluginName); const pluginContentDir = path.join(
context.generatedFilesDir,
plugin.name,
);
const actions = { const actions = {
addRoute: config => pluginsRouteConfigs.push(config), addRoute: config => pluginsRouteConfigs.push(config),
createData: async (name, content) => { createData: async (name, content) => {

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

@ -19,11 +19,11 @@ Then you add it in your site's `docusaurus.config.js` plugin arrays:
module.exports = { module.exports = {
plugins: [ plugins: [
{ {
name: '@docusaurus/plugin-content-pages', module: '@docusaurus/plugin-content-pages',
}, },
{ {
// Plugin with options // Plugin with options
name: '@docusaurus/plugin-content-blog', module: '@docusaurus/plugin-content-blog',
options: { options: {
include: ['*.md', '*.mdx'], include: ['*.md', '*.mdx'],
path: 'blog', path: 'blog',
@ -33,81 +33,84 @@ module.exports = {
}; };
``` ```
Docusaurus can also load plugins from your local folder, you can do something like below: Docusaurus can also load plugins from your local directory, you can do something like the following:
```js ```js
const path = require('path');
module.exports = { module.exports = {
plugins: [ plugins: [
{ {
path: '/path/to/docusaurus-local-plugin', module: path.resolve(__dirname, '/path/to/docusaurus-local-plugin'),
}, },
], ],
} };
``` ```
## Basic Plugin Architecture ## Basic Plugin Definition
Plugins are modules which export a function that takes in the context, options and returns a plain JavaScript object that has some properties defined.
For examples, please refer to several official plugins created. For examples, please refer to several official plugins created.
```js ```js
// A JavaScript class const DEFAULT_OPTIONS = {
class DocusaurusPlugin { // Some defaults.
constructor(context, options) { };
// Initialization hook
// options are the plugin options set on config file // A JavaScript function that returns an object.
this.options = {...options}; // `context` is provided by Docusaurus. Example: siteConfig can be accessed from context.
// `opts` is the user-defined options.
module.exports = function(context, opts) {
// Merge defaults with user-defined options.
const options = {...DEFAULT_OPTIONS, ...options};
// context are provided from docusaurus. Example: siteConfig can be accessed from context return {
this.context = context; // Namespace used for directories to cache the intermediate data for each plugin.
} name: 'docusaurus-cool-plugin',
getName() { async loadContent() {
// plugin name identifier
}
async loadContent()) {
// The loadContent hook is executed after siteConfig and env has been loaded // 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 // You can return a JavaScript object that will be passed to contentLoaded hook
} },
async contentLoaded({content, actions}) { async contentLoaded({content, actions}) {
// contentLoaded hook is done after loadContent hook is done // contentLoaded hook is done after loadContent hook is done
// actions are set of functional API provided by Docusaurus. e.g: addRoute // actions are set of functional API provided by Docusaurus. e.g: addRoute
} },
async postBuild(props) { async postBuild(props) {
// after docusaurus <build> finish // after docusaurus <build> finish
} },
// TODO // TODO
async postStart(props) { async postStart(props) {
// docusaurus <start> finish // docusaurus <start> finish
} },
// TODO // TODO
afterDevServer(app, server) { afterDevServer(app, server) {
// https://webpack.js.org/configuration/dev-server/#devserverbefore // https://webpack.js.org/configuration/dev-server/#devserverbefore
} },
// TODO // TODO
beforeDevServer(app, server) { beforeDevServer(app, server) {
// https://webpack.js.org/configuration/dev-server/#devserverafter // https://webpack.js.org/configuration/dev-server/#devserverafter
},
}
configureWebpack(config, isServer) { 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. // Modify internal webpack config. If returned value is an Object, it
} // will be merged into the final config using webpack-merge;
// If the returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
},
getPathsToWatch() { getPathsToWatch() {
// path to watch // Path to watch
} },
} };
};
``` ```
#### References #### References
- https://v1.vuepress.vuejs.org/plugin/option-api.html - https://v1.vuepress.vuejs.org/plugin/option-api.html