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

refactor(v2): change plugin format within docusaurus.config.js to be like plugins (#1568)

Browse source 
* 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 2019-06-05 21:35:54 -07:00 • committed by GitHub
parent 0226b892bd
commit 6a905dd736
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 221 additions and 242 deletions
Download patch file Download diff file Expand all files Collapse all files

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

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

26
packages/docusaurus/CHANGELOG.md
View file

@ -2,9 +2,31 @@
## 2.0.0-alpha.19 ## 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. - 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 ## V2 Changelog

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

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

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

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

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

@ -29,10 +29,7 @@ export interface Plugin<T> {
getClientModules?(): string[]; getClientModules?(): string[];
} }
export interface PluginConfig { export type PluginConfig = [string, Object | undefined] | string;
module: string;
options?: Object;
}
export interface PluginContentLoadedActions { export interface PluginContentLoadedActions {
addRoute(config: RouteConfig): void; addRoute(config: RouteConfig): void;
@ -50,10 +47,18 @@ export async function loadPlugins({
pluginsRouteConfigs: RouteConfig[]; pluginsRouteConfigs: RouteConfig[];
}> { }> {
// 1. Plugin Lifecycle - Initialization/Constructor // 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. // module is any valid module identifier - npm package or locally-resolved path.
const plugin = importFresh(module); const pluginModule = importFresh(pluginModuleImport);
return plugin(context, options); return pluginModule(context, pluginOptions);
}); });
// 2. Plugin lifecycle - loadContent // 2. Plugin lifecycle - loadContent

10
packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-bar.js
View file

@ -1,14 +1,8 @@
module.exports = function preset(context, opts = {}) { module.exports = function preset(context, opts = {}) {
return { return {
plugins: [ plugins: [
{ ['@docusaurus/plugin-content-docs', opts.docs],
name: '@docusaurus/plugin-content-docs', ['@docusaurus/plugin-content-blog', opts.blog],
options: opts.docs,
},
{
name: '@docusaurus/plugin-content-blog',
options: opts.blog,
},
], ],
}; };
}; };

10
packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-foo.js
View file

@ -1,14 +1,8 @@
module.exports = function preset(context, opts = {}) { module.exports = function preset(context, opts = {}) {
return { return {
plugins: [ plugins: [
{ ['@docusaurus/plugin-content-pages', opts.pages],
name: '@docusaurus/plugin-content-pages', ['@docusaurus/plugin-sitemap', opts.sitemap],
options: opts.pages,
},
{
name: '@docusaurus/plugin-sitemap',
options: opts.sitemap,
},
], ],
}; };
}; };

14
packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-qux.js
View file

@ -1,16 +1,6 @@
module.exports = function preset(context, opts = {}) { module.exports = function preset(context, opts = {}) {
return { return {
themes: [ themes: [['@docusaurus/theme-classic', opts.test]],
{ plugins: [['@docusaurus/plugin-test', opts.test]],
name: '@docusaurus/theme-classic',
options: opts.test,
},
],
plugins: [
{
name: '@docusaurus/plugin-test',
options: opts.test,
},
],
}; };
}; };

308
packages/docusaurus/src/server/presets/__tests__/index.test.ts
View file

@ -15,11 +15,11 @@ describe('loadPresets', () => {
const context = {siteConfig: {}} as LoadContext; const context = {siteConfig: {}} as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [], "plugins": Array [],
"themes": Array [], "themes": Array [],
} }
`); `);
}); });
test('string form', () => { test('string form', () => {
@ -30,20 +30,20 @@ Object {
} as LoadContext; } as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [ "plugins": Array [
Object { Array [
"name": "@docusaurus/plugin-content-docs", "@docusaurus/plugin-content-docs",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-blog", "@docusaurus/plugin-content-blog",
"options": undefined, undefined,
}, ],
], ],
"themes": Array [], "themes": Array [],
} }
`); `);
}); });
test('string form composite', () => { test('string form composite', () => {
@ -57,28 +57,28 @@ Object {
} as LoadContext; } as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [ "plugins": Array [
Object { Array [
"name": "@docusaurus/plugin-content-docs", "@docusaurus/plugin-content-docs",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-blog", "@docusaurus/plugin-content-blog",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-pages", "@docusaurus/plugin-content-pages",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-sitemap", "@docusaurus/plugin-sitemap",
"options": undefined, undefined,
}, ],
], ],
"themes": Array [], "themes": Array [],
} }
`); `);
}); });
test('array form', () => { test('array form', () => {
@ -89,20 +89,20 @@ Object {
} as LoadContext; } as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [ "plugins": Array [
Object { Array [
"name": "@docusaurus/plugin-content-docs", "@docusaurus/plugin-content-docs",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-blog", "@docusaurus/plugin-content-blog",
"options": undefined, undefined,
}, ],
], ],
"themes": Array [], "themes": Array [],
} }
`); `);
}); });
test('array form with options', () => { test('array form with options', () => {
@ -118,22 +118,22 @@ Object {
} as LoadContext; } as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [ "plugins": Array [
Object { Array [
"name": "@docusaurus/plugin-content-docs", "@docusaurus/plugin-content-docs",
"options": Object { Object {
"path": "../", "path": "../",
}, },
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-blog", "@docusaurus/plugin-content-blog",
"options": undefined, undefined,
}, ],
], ],
"themes": Array [], "themes": Array [],
} }
`); `);
}); });
test('array form composite', () => { test('array form composite', () => {
@ -153,32 +153,32 @@ Object {
} as LoadContext; } as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [ "plugins": Array [
Object { Array [
"name": "@docusaurus/plugin-content-docs", "@docusaurus/plugin-content-docs",
"options": Object { Object {
"path": "../", "path": "../",
}, },
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-blog", "@docusaurus/plugin-content-blog",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-pages", "@docusaurus/plugin-content-pages",
"options": Object { Object {
"path": "../", "path": "../",
}, },
}, ],
Object { Array [
"name": "@docusaurus/plugin-sitemap", "@docusaurus/plugin-sitemap",
"options": undefined, undefined,
}, ],
], ],
"themes": Array [], "themes": Array [],
} }
`); `);
}); });
test('mixed form', () => { test('mixed form', () => {
@ -195,30 +195,30 @@ Object {
} as LoadContext; } as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [ "plugins": Array [
Object { Array [
"name": "@docusaurus/plugin-content-docs", "@docusaurus/plugin-content-docs",
"options": Object { Object {
"path": "../", "path": "../",
}, },
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-blog", "@docusaurus/plugin-content-blog",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-pages", "@docusaurus/plugin-content-pages",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-sitemap", "@docusaurus/plugin-sitemap",
"options": undefined, undefined,
}, ],
], ],
"themes": Array [], "themes": Array [],
} }
`); `);
}); });
test('mixed form with themes', () => { test('mixed form with themes', () => {
@ -236,38 +236,38 @@ Object {
} as LoadContext; } as LoadContext;
const presets = loadPresets(context); const presets = loadPresets(context);
expect(presets).toMatchInlineSnapshot(` expect(presets).toMatchInlineSnapshot(`
Object { Object {
"plugins": Array [ "plugins": Array [
Object { Array [
"name": "@docusaurus/plugin-content-docs", "@docusaurus/plugin-content-docs",
"options": Object { Object {
"path": "../", "path": "../",
}, },
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-blog", "@docusaurus/plugin-content-blog",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-content-pages", "@docusaurus/plugin-content-pages",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-sitemap", "@docusaurus/plugin-sitemap",
"options": undefined, undefined,
}, ],
Object { Array [
"name": "@docusaurus/plugin-test", "@docusaurus/plugin-test",
"options": undefined, undefined,
}, ],
], ],
"themes": Array [ "themes": Array [
Object { Array [
"name": "@docusaurus/theme-classic", "@docusaurus/theme-classic",
"options": undefined, undefined,
}, ],
], ],
} }
`); `);
}); });
}); });

5
packages/docusaurus/src/server/presets/index.ts
View file

@ -16,7 +16,7 @@ export interface Preset {
themes?: PluginConfig[]; themes?: PluginConfig[];
} }
export type PresetConfig = [string, Object] | string; export type PresetConfig = [string, Object | undefined] | string;
export function loadPresets( export function loadPresets(
context: LoadContext, context: LoadContext,
@ -34,7 +34,8 @@ export function loadPresets(
if (typeof presetItem === 'string') { if (typeof presetItem === 'string') {
presetModuleImport = presetItem; presetModuleImport = presetItem;
} else if (Array.isArray(presetItem)) { } else if (Array.isArray(presetItem)) {
[presetModuleImport, presetOptions] = presetItem; presetModuleImport = presetItem[0];
presetOptions = presetItem[1] || {};
} }
const presetModule = importFresh(presetModuleImport); const presetModule = importFresh(presetModuleImport);

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

@ -18,17 +18,15 @@ Then you add it in your site's `docusaurus.config.js` plugin arrays:
```jsx ```jsx
module.exports = { module.exports = {
plugins: [ plugins: [
{ '@docusaurus/plugin-content-pages',
module: '@docusaurus/plugin-content-pages', [
},
{
// Plugin with options // Plugin with options
module: '@docusaurus/plugin-content-blog', '@docusaurus/plugin-content-blog',
options: { {
include: ['*.md', '*.mdx'], include: ['*.md', '*.mdx'],
path: 'blog', path: 'blog',
}, },
}, ],
], ],
}; };
``` ```
@ -39,11 +37,7 @@ Docusaurus can also load plugins from your local directory, you can do something
const path = require('path'); const path = require('path');
module.exports = { module.exports = {
plugins: [ plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
{
module: path.resolve(__dirname, '/path/to/docusaurus-local-plugin'),
},
],
}; };
``` ```