chore(v2): improve typing

packages/docusaurus/src/commands/start.ts

@@ -58,7 +58,7 @@ export async function start(
     return filepath;
   };
 
-  const pluginPaths = _.compact(
+  const pluginPaths: string[] = _.compact(
     _.flatten<string | undefined>(
       plugins.map(plugin => plugin.getPathsToWatch && plugin.getPathsToWatch()),
     ),

packages/docusaurus/src/server/__tests__/__fixtures__/wrong-site/docusaurus.config.js

@@ -12,8 +12,9 @@ module.exports = {
   projectName: 'hello',
   baseUrl: '/',
   useLessField: 'what',
-  superman: 'lol',
-  admin: 'endi',
-  customFields: ['admin', 'superman'],
+  customFields: {
+    admin: 'endi',
+    superman: 'lol',
+  },
   url: 'https://docusaurus.io',
 };

packages/docusaurus/src/server/__tests__/config.test.ts

@@ -20,11 +20,14 @@ describe('loadConfig', () => {
       `
       Object {
         "baseUrl": "/",
+        "customFields": Object {},
         "favicon": "img/docusaurus.ico",
         "organizationName": "endiliey",
         "plugins": Any<Array>,
         "projectName": "hello",
         "tagline": "Hello World",
+        "themeConfig": Object {},
+        "themes": Array [],
         "title": "Hello",
         "url": "https://docusaurus.io",
       }

packages/docusaurus/src/server/config.ts

@@ -12,6 +12,7 @@ import _ from 'lodash';
 import importFresh from 'import-fresh';
 import path from 'path';
 import {CONFIG_FILE_NAME} from '../constants';
+import {PresetConfig} from './presets';
 
 export interface DocusaurusConfig {
   baseUrl: string;
@@ -21,14 +22,16 @@ export interface DocusaurusConfig {
   url: string;
   organizationName?: string;
   projectName?: string;
-  customFields?: string[];
   githubHost?: string;
   plugins?: PluginConfig[];
-  presets?: any[];
+  themes?: PluginConfig[];
+  presets?: PresetConfig[];
   themeConfig?: {
     [key: string]: any;
   };
-  [key: string]: any;
+  customFields?: {
+    [key: string]: any;
+  };
 }
 
 const REQUIRED_FIELDS = ['baseUrl', 'favicon', 'tagline', 'title', 'url'];
@@ -39,14 +42,25 @@ const OPTIONAL_FIELDS = [
   'customFields',
   'githubHost',
   'plugins',
+  'themes',
   'presets',
   'themeConfig',
 ];
 
 const DEFAULT_CONFIG: {
-  [key: string]: any;
+  plugins: PluginConfig[];
+  themes: PluginConfig[];
+  customFields: {
+    [key: string]: any;
+  };
+  themeConfig: {
+    [key: string]: any;
+  };
 } = {
   plugins: [],
+  themes: [],
+  customFields: {},
+  themeConfig: {},
 };
 
 function formatFields(fields: string[]): string {
@@ -74,16 +88,8 @@ export function loadConfig(siteDir: string): DocusaurusConfig {
   // Merge default config with loaded config.
   const config: DocusaurusConfig = {...DEFAULT_CONFIG, ...loadedConfig};
 
-  // User's own array of custom fields/
-  // e.g: if they want to include some.field so they can access it later from `props.siteConfig`.
-  const {customFields = []} = config;
-
   // Don't allow unrecognized fields.
-  const allowedFields = [
-    ...REQUIRED_FIELDS,
-    ...OPTIONAL_FIELDS,
-    ...customFields,
-  ];
+  const allowedFields = [...REQUIRED_FIELDS, ...OPTIONAL_FIELDS];
   const unrecognizedFields = Object.keys(config).filter(
     field => !allowedFields.includes(field),
   );

packages/docusaurus/src/server/index.ts

@@ -134,7 +134,7 @@ ${Object.keys(registry)
     genRoutes,
   ]);
 
-  const props = {
+  const props: Props = {
     siteConfig,
     siteDir,
     outDir,

packages/docusaurus/src/server/presets/index.ts

@@ -16,15 +16,17 @@ export interface Preset {
   themes?: PluginConfig[];
 }
 
+export type PresetConfig = [string, Object] | string;
+
 export function loadPresets(
   context: LoadContext,
 ): {
   plugins: PluginConfig[];
   themes: PluginConfig[];
 } {
-  const presets: any[] = context.siteConfig.presets || [];
-  const plugins: (PluginConfig[] | undefined)[] = [];
-  const themes: (PluginConfig[] | undefined)[] = [];
+  const presets: PresetConfig[] = context.siteConfig.presets || [];
+  const unflatPlugins: (PluginConfig[])[] = [];
+  const unflatThemes: (PluginConfig[])[] = [];
 
   presets.forEach(presetItem => {
     let presetModuleImport;
@@ -38,12 +40,12 @@ export function loadPresets(
     const presetModule = importFresh(presetModuleImport);
     const preset: Preset = presetModule(context, presetOptions);
 
-    plugins.push(preset.plugins);
-    themes.push(preset.themes);
+    preset.plugins && unflatPlugins.push(preset.plugins);
+    preset.themes && unflatThemes.push(preset.themes);
   });
 
   return {
-    plugins: _.compact(_.flatten<PluginConfig | undefined>(plugins)),
-    themes: _.compact(_.flatten<PluginConfig | undefined>(themes)),
+    plugins: _.compact(_.flatten<PluginConfig>(unflatPlugins)),
+    themes: _.compact(_.flatten<PluginConfig>(unflatThemes)),
   };
 }

website/docs/configuration.md

@@ -59,20 +59,19 @@ You may also check the doc for [Deployment](deployment.md) for more information
 
 ### Custom configurations
 
-You may have your own custom fields. And `docusaurus.config.js` will be aware of the fields and guard your configuration from unknown fields.
+Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`
 
 - [customFields](docusaurus.config.js.md#customFields)
 
-To add a custom field, add the field name to `customFields`. Then, you may use the field for your customization data:
+Example:
 
 ```js
 // docusaurus.config.js
 module.exports = {
-  customFields: ['seo'],
-  seo: {
-    image: '',
-    keywords: [],
-  },
+  customFields: {
+    'image': '',
+    'keywords': []
+  }
 };
 ```
 

website/docs/docusaurus.config.js.md

@@ -203,21 +203,23 @@ module.exports = {
 };
 ```
 
-### `customFields` and other custom fields
+### `customFields`
 
-Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, add the field name to `customFields`, then add the field to the module.
+Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`
 
-- Type: `string[]`
+- Type: `Object`
 
-```js
+```jsx
 // docusaurus.config.js
 module.exports = {
-  customFields: ['seo'],
-  seo: // ... the actual custom field
+  customFields: {
+    admin: 'endi',
+    superman: 'lol'
+  },
 };
 ```
 
-Attempting to add custom fields without indicating in `customFields` will lead to error in build time:
+Attempting to add unknown field in the config will lead to error in build time:
 
 ```bash
 Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js