mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-07 05:12:31 +02:00
refactor(v2): change plugin format within docusaurus.config.js to be like plugins (#1568)
* refactor(v2): change plugin format within `docusaurus.config.js` to be like presets * docs(v2): mention customizing CSS
This commit is contained in:
Yangshun Tay
GitHub
parent
0226b892bd
commit
6a905dd736
11 changed files with 221 additions and 242 deletions
|
|
@ -8,31 +8,14 @@
|
|||
module.exports = function preset(context, opts = {}) {
|
||||
return {
|
||||
themes: [
|
||||
{
|
||||
module: '@docusaurus/theme-classic',
|
||||
options: opts.theme,
|
||||
},
|
||||
{
|
||||
module: '@docusaurus/theme-search-algolia',
|
||||
},
|
||||
['@docusaurus/theme-classic', opts.theme],
|
||||
'@docusaurus/theme-search-algolia',
|
||||
],
|
||||
plugins: [
|
||||
{
|
||||
module: '@docusaurus/plugin-content-docs',
|
||||
options: opts.docs,
|
||||
},
|
||||
{
|
||||
module: '@docusaurus/plugin-content-blog',
|
||||
options: opts.blog,
|
||||
},
|
||||
{
|
||||
module: '@docusaurus/plugin-content-pages',
|
||||
options: opts.pages,
|
||||
},
|
||||
{
|
||||
module: '@docusaurus/plugin-sitemap',
|
||||
options: opts.sitemap,
|
||||
},
|
||||
['@docusaurus/plugin-content-docs', opts.docs],
|
||||
['@docusaurus/plugin-content-blog', opts.blog],
|
||||
['@docusaurus/plugin-content-pages', opts.pages],
|
||||
['@docusaurus/plugin-sitemap', opts.sitemap],
|
||||
],
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -2,9 +2,31 @@
|
|||
|
||||
## 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.
|
||||
- UI
|
||||
- Added sun and moon emoji to the dark mode toggle.
|
||||
- Mobile responsive menu.
|
||||
- Right table of contents for docs is now sticky.
|
||||
- Plugins
|
||||
- Changed plugin definitions from classes to functions. Refer to the new plugin docs.
|
||||
- Implement Clients module API.
|
||||
- Change format within `docusaurus.config.js` to be like presets.
|
||||
- Infima CSS is now locked down to specific versions and not relying upon the CDN which reads from trunk.
|
||||
- Customize the CSS by passing options into the classic preset:
|
||||
|
||||
```
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
theme: {
|
||||
customCss: require.resolve('./css/custom.css'),
|
||||
},
|
||||
...
|
||||
},
|
||||
],
|
||||
],
|
||||
```
|
||||
|
||||
## V2 Changelog
|
||||
|
||||
|
|
|
|||
|
|
@ -14,15 +14,13 @@ module.exports = {
|
|||
url: 'https://docusaurus.io',
|
||||
favicon: 'img/docusaurus.ico',
|
||||
plugins: [
|
||||
{
|
||||
module: '@docusaurus/plugin-content-docs',
|
||||
options: {
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
path: '../docs',
|
||||
sidebarPath: require.resolve('./sidebars.json'),
|
||||
},
|
||||
},
|
||||
{
|
||||
module: '@docusaurus/plugin-content-pages',
|
||||
},
|
||||
],
|
||||
'@docusaurus/plugin-content-pages',
|
||||
],
|
||||
};
|
||||
|
|
|
|||
|
|
@ -14,15 +14,13 @@ module.exports = {
|
|||
url: 'https://docusaurus.io',
|
||||
favicon: 'img/docusaurus.ico',
|
||||
plugins: [
|
||||
{
|
||||
module: '@docusaurus/plugin-content-docs',
|
||||
options: {
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
path: '../docs',
|
||||
sidebarPath: require.resolve('./sidebars.json'),
|
||||
},
|
||||
},
|
||||
{
|
||||
module: '@docusaurus/plugin-content-pages',
|
||||
},
|
||||
],
|
||||
'@docusaurus/plugin-content-pages',
|
||||
],
|
||||
};
|
||||
|
|
|
|||
|
|
@ -29,10 +29,7 @@ export interface Plugin<T> {
|
|||
getClientModules?(): string[];
|
||||
}
|
||||
|
||||
export interface PluginConfig {
|
||||
module: string;
|
||||
options?: Object;
|
||||
}
|
||||
export type PluginConfig = [string, Object | undefined] | string;
|
||||
|
||||
export interface PluginContentLoadedActions {
|
||||
addRoute(config: RouteConfig): void;
|
||||
|
|
@ -50,10 +47,18 @@ export async function loadPlugins({
|
|||
pluginsRouteConfigs: RouteConfig[];
|
||||
}> {
|
||||
// 1. Plugin Lifecycle - Initialization/Constructor
|
||||
const plugins: Plugin<any>[] = pluginConfigs.map(({module, options}) => {
|
||||
const plugins: Plugin<any>[] = pluginConfigs.map(pluginItem => {
|
||||
let pluginModuleImport;
|
||||
let pluginOptions = {};
|
||||
if (typeof pluginItem === 'string') {
|
||||
pluginModuleImport = pluginItem;
|
||||
} else if (Array.isArray(pluginItem)) {
|
||||
pluginModuleImport = pluginItem[0];
|
||||
pluginOptions = pluginItem[1] || {};
|
||||
}
|
||||
// module is any valid module identifier - npm package or locally-resolved path.
|
||||
const plugin = importFresh(module);
|
||||
return plugin(context, options);
|
||||
const pluginModule = importFresh(pluginModuleImport);
|
||||
return pluginModule(context, pluginOptions);
|
||||
});
|
||||
|
||||
// 2. Plugin lifecycle - loadContent
|
||||
|
|
|
|||
|
|
@ -1,14 +1,8 @@
|
|||
module.exports = function preset(context, opts = {}) {
|
||||
return {
|
||||
plugins: [
|
||||
{
|
||||
name: '@docusaurus/plugin-content-docs',
|
||||
options: opts.docs,
|
||||
},
|
||||
{
|
||||
name: '@docusaurus/plugin-content-blog',
|
||||
options: opts.blog,
|
||||
},
|
||||
['@docusaurus/plugin-content-docs', opts.docs],
|
||||
['@docusaurus/plugin-content-blog', opts.blog],
|
||||
],
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -1,14 +1,8 @@
|
|||
module.exports = function preset(context, opts = {}) {
|
||||
return {
|
||||
plugins: [
|
||||
{
|
||||
name: '@docusaurus/plugin-content-pages',
|
||||
options: opts.pages,
|
||||
},
|
||||
{
|
||||
name: '@docusaurus/plugin-sitemap',
|
||||
options: opts.sitemap,
|
||||
},
|
||||
['@docusaurus/plugin-content-pages', opts.pages],
|
||||
['@docusaurus/plugin-sitemap', opts.sitemap],
|
||||
],
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -1,16 +1,6 @@
|
|||
module.exports = function preset(context, opts = {}) {
|
||||
return {
|
||||
themes: [
|
||||
{
|
||||
name: '@docusaurus/theme-classic',
|
||||
options: opts.test,
|
||||
},
|
||||
],
|
||||
plugins: [
|
||||
{
|
||||
name: '@docusaurus/plugin-test',
|
||||
options: opts.test,
|
||||
},
|
||||
],
|
||||
themes: [['@docusaurus/theme-classic', opts.test]],
|
||||
plugins: [['@docusaurus/plugin-test', opts.test]],
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -15,11 +15,11 @@ describe('loadPresets', () => {
|
|||
const context = {siteConfig: {}} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
});
|
||||
|
||||
test('string form', () => {
|
||||
|
|
@ -30,20 +30,20 @@ Object {
|
|||
} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-docs",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-blog",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Array [
|
||||
"@docusaurus/plugin-content-docs",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-blog",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
});
|
||||
|
||||
test('string form composite', () => {
|
||||
|
|
@ -57,28 +57,28 @@ Object {
|
|||
} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-docs",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-blog",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-pages",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-sitemap",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Array [
|
||||
"@docusaurus/plugin-content-docs",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-blog",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-pages",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-sitemap",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
});
|
||||
|
||||
test('array form', () => {
|
||||
|
|
@ -89,20 +89,20 @@ Object {
|
|||
} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-docs",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-blog",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Array [
|
||||
"@docusaurus/plugin-content-docs",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-blog",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
});
|
||||
|
||||
test('array form with options', () => {
|
||||
|
|
@ -118,22 +118,22 @@ Object {
|
|||
} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-docs",
|
||||
"options": Object {
|
||||
"path": "../",
|
||||
},
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-blog",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Array [
|
||||
"@docusaurus/plugin-content-docs",
|
||||
Object {
|
||||
"path": "../",
|
||||
},
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-blog",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
});
|
||||
|
||||
test('array form composite', () => {
|
||||
|
|
@ -153,32 +153,32 @@ Object {
|
|||
} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-docs",
|
||||
"options": Object {
|
||||
"path": "../",
|
||||
},
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-blog",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-pages",
|
||||
"options": Object {
|
||||
"path": "../",
|
||||
},
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-sitemap",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Array [
|
||||
"@docusaurus/plugin-content-docs",
|
||||
Object {
|
||||
"path": "../",
|
||||
},
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-blog",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-pages",
|
||||
Object {
|
||||
"path": "../",
|
||||
},
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-sitemap",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
});
|
||||
|
||||
test('mixed form', () => {
|
||||
|
|
@ -195,30 +195,30 @@ Object {
|
|||
} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-docs",
|
||||
"options": Object {
|
||||
"path": "../",
|
||||
},
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-blog",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-pages",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-sitemap",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Array [
|
||||
"@docusaurus/plugin-content-docs",
|
||||
Object {
|
||||
"path": "../",
|
||||
},
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-blog",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-pages",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-sitemap",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
"themes": Array [],
|
||||
}
|
||||
`);
|
||||
});
|
||||
|
||||
test('mixed form with themes', () => {
|
||||
|
|
@ -236,38 +236,38 @@ Object {
|
|||
} as LoadContext;
|
||||
const presets = loadPresets(context);
|
||||
expect(presets).toMatchInlineSnapshot(`
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-docs",
|
||||
"options": Object {
|
||||
"path": "../",
|
||||
},
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-blog",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-content-pages",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-sitemap",
|
||||
"options": undefined,
|
||||
},
|
||||
Object {
|
||||
"name": "@docusaurus/plugin-test",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
"themes": Array [
|
||||
Object {
|
||||
"name": "@docusaurus/theme-classic",
|
||||
"options": undefined,
|
||||
},
|
||||
],
|
||||
}
|
||||
`);
|
||||
Object {
|
||||
"plugins": Array [
|
||||
Array [
|
||||
"@docusaurus/plugin-content-docs",
|
||||
Object {
|
||||
"path": "../",
|
||||
},
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-blog",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-content-pages",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-sitemap",
|
||||
undefined,
|
||||
],
|
||||
Array [
|
||||
"@docusaurus/plugin-test",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
"themes": Array [
|
||||
Array [
|
||||
"@docusaurus/theme-classic",
|
||||
undefined,
|
||||
],
|
||||
],
|
||||
}
|
||||
`);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ export interface Preset {
|
|||
themes?: PluginConfig[];
|
||||
}
|
||||
|
||||
export type PresetConfig = [string, Object] | string;
|
||||
export type PresetConfig = [string, Object | undefined] | string;
|
||||
|
||||
export function loadPresets(
|
||||
context: LoadContext,
|
||||
|
|
@ -34,7 +34,8 @@ export function loadPresets(
|
|||
if (typeof presetItem === 'string') {
|
||||
presetModuleImport = presetItem;
|
||||
} else if (Array.isArray(presetItem)) {
|
||||
[presetModuleImport, presetOptions] = presetItem;
|
||||
presetModuleImport = presetItem[0];
|
||||
presetOptions = presetItem[1] || {};
|
||||
}
|
||||
|
||||
const presetModule = importFresh(presetModuleImport);
|
||||
|
|
|
|||
|
|
@ -18,17 +18,15 @@ Then you add it in your site's `docusaurus.config.js` plugin arrays:
|
|||
```jsx
|
||||
module.exports = {
|
||||
plugins: [
|
||||
{
|
||||
module: '@docusaurus/plugin-content-pages',
|
||||
},
|
||||
{
|
||||
'@docusaurus/plugin-content-pages',
|
||||
[
|
||||
// Plugin with options
|
||||
module: '@docusaurus/plugin-content-blog',
|
||||
options: {
|
||||
'@docusaurus/plugin-content-blog',
|
||||
{
|
||||
include: ['*.md', '*.mdx'],
|
||||
path: 'blog',
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
|
@ -39,11 +37,7 @@ Docusaurus can also load plugins from your local directory, you can do something
|
|||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
plugins: [
|
||||
{
|
||||
module: path.resolve(__dirname, '/path/to/docusaurus-local-plugin'),
|
||||
},
|
||||
],
|
||||
plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
|
||||
};
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue