From 6a905dd736aedbd9f7398594c1c80b1331cd3276 Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Wed, 5 Jun 2019 21:35:54 -0700 Subject: [PATCH] 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 --- .../docusaurus-preset-classic/src/index.js | 29 +- packages/docusaurus/CHANGELOG.md | 26 +- .../custom-site/docusaurus.config.js | 12 +- .../simple-site/docusaurus.config.js | 12 +- .../docusaurus/src/server/plugins/index.ts | 19 +- .../__tests__/__fixtures__/preset-bar.js | 10 +- .../__tests__/__fixtures__/preset-foo.js | 10 +- .../__tests__/__fixtures__/preset-qux.js | 14 +- .../server/presets/__tests__/index.test.ts | 308 +++++++++--------- .../docusaurus/src/server/presets/index.ts | 5 +- website/docs/plugins-api.md | 18 +- 11 files changed, 221 insertions(+), 242 deletions(-) diff --git a/packages/docusaurus-preset-classic/src/index.js b/packages/docusaurus-preset-classic/src/index.js index 46d9f5249e..c57a13b4a7 100644 --- a/packages/docusaurus-preset-classic/src/index.js +++ b/packages/docusaurus-preset-classic/src/index.js @@ -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], ], }; }; diff --git a/packages/docusaurus/CHANGELOG.md b/packages/docusaurus/CHANGELOG.md index c2c4dae5e5..29bc30caba 100644 --- a/packages/docusaurus/CHANGELOG.md +++ b/packages/docusaurus/CHANGELOG.md @@ -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 diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js b/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js index 424e97fda1..8aa30a0b1b 100644 --- a/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js +++ b/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js @@ -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', ], }; diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js index e1f80488be..b8c5697691 100644 --- a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js +++ b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js @@ -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', ], }; diff --git a/packages/docusaurus/src/server/plugins/index.ts b/packages/docusaurus/src/server/plugins/index.ts index b54febd9ad..7364e66022 100644 --- a/packages/docusaurus/src/server/plugins/index.ts +++ b/packages/docusaurus/src/server/plugins/index.ts @@ -29,10 +29,7 @@ export interface Plugin { 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[] = pluginConfigs.map(({module, options}) => { + const plugins: Plugin[] = 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 diff --git a/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-bar.js b/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-bar.js index 347bd339fa..b9b8527505 100644 --- a/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-bar.js +++ b/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-bar.js @@ -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], ], }; }; diff --git a/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-foo.js b/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-foo.js index c3968042b3..9475a381f3 100644 --- a/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-foo.js +++ b/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-foo.js @@ -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], ], }; }; diff --git a/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-qux.js b/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-qux.js index 27ef476447..273776f0ed 100644 --- a/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-qux.js +++ b/packages/docusaurus/src/server/presets/__tests__/__fixtures__/preset-qux.js @@ -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]], }; }; diff --git a/packages/docusaurus/src/server/presets/__tests__/index.test.ts b/packages/docusaurus/src/server/presets/__tests__/index.test.ts index 40d79d2b89..68820e17aa 100644 --- a/packages/docusaurus/src/server/presets/__tests__/index.test.ts +++ b/packages/docusaurus/src/server/presets/__tests__/index.test.ts @@ -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, + ], + ], + } + `); }); }); diff --git a/packages/docusaurus/src/server/presets/index.ts b/packages/docusaurus/src/server/presets/index.ts index a2318b42c5..ac4c7ebc64 100644 --- a/packages/docusaurus/src/server/presets/index.ts +++ b/packages/docusaurus/src/server/presets/index.ts @@ -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); diff --git a/website/docs/plugins-api.md b/website/docs/plugins-api.md index 2fd1b79234..ef373da4f7 100644 --- a/website/docs/plugins-api.md +++ b/website/docs/plugins-api.md @@ -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')], }; ```