feat: add --config & --generated-files-dir option to CLI

packages/docusaurus-types/src/index.d.ts

@@ -131,21 +131,36 @@ export type HostPortCLIOptions = {
   port?: string;
 };
 
-export type StartCLIOptions = HostPortCLIOptions & {
-  hotOnly: boolean;
-  open: boolean;
-  poll: boolean | number;
-  locale?: string;
+export type ConfigOptions = {
+  config: string;
 };
 
-export type ServeCLIOptions = HostPortCLIOptions & {
-  build: boolean;
-  dir: string;
-};
+export type StartCLIOptions = HostPortCLIOptions &
+  ConfigOptions & {
+    hotOnly: boolean;
+    open: boolean;
+    poll: boolean | number;
+    locale?: string;
+  };
 
-export type BuildOptions = {
+export type ServeCLIOptions = HostPortCLIOptions &
+  ConfigOptions & {
+    dir: string;
+  } & (
+    | {
+        build: true;
+        // We only need generatedFilesDir when `build` is true
+        generatedFilesDir: string;
+      }
+    | {
+        build: false;
+      }
+  );
+
+export type BuildOptions = ConfigOptions & {
   bundleAnalyzer: boolean;
   outDir: string;
+  generatedFilesDir: string;
   minify: boolean;
   skipBuild: boolean;
 };

packages/docusaurus/bin/docusaurus.js

@@ -109,6 +109,14 @@ cli
     '--out-dir <dir>',
     'The full path for the new output directory, relative to the current workspace (default: build).',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
+  .option(
+    '--generated-files-dir <dir>',
+    'Path to temporary `.docusaurus` folder, default to `[siteDir]/.docusaurus`.',
+  )
   .option(
     '-l, --locale <locale>',
     'Build the site in a specified locale. Build all known locales otherwise.',
@@ -117,14 +125,21 @@ cli
     '--no-minify',
     'Build website without minimizing JS bundles (default: false)',
   )
-  .action((siteDir = '.', {bundleAnalyzer, outDir, locale, minify}) => {
-    wrapCommand(build)(path.resolve(siteDir), {
-      bundleAnalyzer,
-      outDir,
-      locale,
-      minify,
-    });
-  });
+  .action(
+    (
+      siteDir = '.',
+      {bundleAnalyzer, config, generatedFilesDir, outDir, locale, minify},
+    ) => {
+      wrapCommand(build)(path.resolve(siteDir), {
+        bundleAnalyzer,
+        outDir,
+        config,
+        generatedFilesDir,
+        locale,
+        minify,
+      });
+    },
+  );
 
 cli
   .command('swizzle [themeName] [componentName] [siteDir]')
@@ -155,12 +170,25 @@ cli
     '--out-dir <dir>',
     'The full path for the new output directory, relative to the current workspace (default: build).',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
+  .option(
+    '--generated-files-dir <dir>',
+    'Path to temporary `.docusaurus` folder, default to `[siteDir]/.docusaurus`. This is only relevant when `--build` passed in.',
+  )
   .option(
     '--skip-build',
     'Skip building website before deploy it (default: false)',
   )
-  .action((siteDir = '.', {outDir, skipBuild}) => {
-    wrapCommand(deploy)(path.resolve(siteDir), {outDir, skipBuild});
+  .action((siteDir = '.', {outDir, skipBuild, config, generatedFilesDir}) => {
+    wrapCommand(deploy)(path.resolve(siteDir), {
+      outDir,
+      config,
+      generatedFilesDir,
+      skipBuild,
+    });
   });
 
 cli
@@ -173,21 +201,28 @@ cli
     '--hot-only',
     'Do not fallback to page refresh if hot reload fails (default: false)',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
   .option('--no-open', 'Do not open page in the browser (default: false)')
   .option(
     '--poll [interval]',
     'Use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds.',
   )
-  .action((siteDir = '.', {port, host, locale, hotOnly, open, poll}) => {
-    wrapCommand(start)(path.resolve(siteDir), {
-      port,
-      host,
-      locale,
-      hotOnly,
-      open,
-      poll,
-    });
-  });
+  .action(
+    (siteDir = '.', {port, host, locale, config, hotOnly, open, poll}) => {
+      wrapCommand(start)(path.resolve(siteDir), {
+        port,
+        host,
+        locale,
+        config,
+        hotOnly,
+        open,
+        poll,
+      });
+    },
+  );
 
 cli
   .command('serve [siteDir]')
@@ -196,6 +231,14 @@ cli
     '--dir <dir>',
     'The full path for the new output directory, relative to the current workspace (default: build).',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
+  .option(
+    '--generated-files-dir <dir>',
+    'Path to temporary `.docusaurus` folder, default to `[siteDir]/.docusaurus`. This is only relevant when `--build` passed in.',
+  )
   .option('-p, --port <port>', 'use specified port (default: 3000)')
   .option('--build', 'Build website before serving (default: false)')
   .option('-h, --host <host>', 'use specified host (default: localhost')
@@ -207,12 +250,16 @@ cli
         port = 3000,
         host = 'localhost',
         build: buildSite = false,
+        config,
+        generatedFilesDir,
       },
     ) => {
       wrapCommand(serve)(path.resolve(siteDir), {
         dir,
         port,
         build: buildSite,
+        config,
+        generatedFilesDir,
         host,
       });
     },
@@ -236,18 +283,23 @@ cli
     '--override',
     'By default, we only append missing translation messages to existing translation files. This option allows to override existing translation messages. Make sure to commit or backup your existing translations, as they may be overridden.',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
   .option(
     '--messagePrefix <messagePrefix>',
     'Allows to init new written messages with a given prefix. This might help you to highlight untranslated message to make them stand out in the UI.',
   )
   .action(
     (
       siteDir = '.',
-      {locale = undefined, override = false, messagePrefix = ''},
+      {locale = undefined, override = false, messagePrefix = '', config},
     ) => {
       wrapCommand(writeTranslations)(path.resolve(siteDir), {
         locale,
         override,
+        config,
         messagePrefix,
       });
     },

packages/docusaurus/src/commands/build.ts

@@ -14,7 +14,7 @@ import {Configuration, Plugin} from 'webpack';
 import {BundleAnalyzerPlugin} from 'webpack-bundle-analyzer';
 import merge from 'webpack-merge';
 import {STATIC_DIR_NAME} from '../constants';
-import {load} from '../server';
+import {load, loadContext} from '../server';
 import {handleBrokenLinks} from '../server/brokenLinks';
 
 import {BuildCLIOptions, Props} from '@docusaurus/types';
@@ -28,7 +28,6 @@ import {
 import CleanWebpackPlugin from '../webpack/plugins/CleanWebpackPlugin';
 import {loadI18n} from '../server/i18n';
 import {mapAsyncSequencial} from '@docusaurus/utils';
-import loadConfig from '../server/config';
 
 export default async function build(
   siteDir: string,
@@ -59,8 +58,14 @@ export default async function build(
       throw e;
     }
   }
-
-  const i18n = await loadI18n(loadConfig(siteDir), {
+  const context = await loadContext(siteDir, {
+    customOutDir: cliOptions.outDir,
+    customGeneratedFilesDir: cliOptions.generatedFilesDir,
+    customConfigFilePath: cliOptions.config,
+    locale: cliOptions.locale,
+    localizePath: cliOptions.locale ? false : undefined,
+  });
+  const i18n = await loadI18n(context.siteConfig, {
     locale: cliOptions.locale,
   });
   if (cliOptions.locale) {
@@ -112,6 +117,8 @@ async function buildLocale({
 
   const props: Props = await load(siteDir, {
     customOutDir: cliOptions.outDir,
+    customConfigFilePath: cliOptions.config,
+    customGeneratedFilesDir: cliOptions.generatedFilesDir,
     locale,
     localizePath: cliOptions.locale ? false : undefined,
   });

packages/docusaurus/src/commands/deploy.ts

@@ -9,9 +9,8 @@ import fs from 'fs-extra';
 import path from 'path';
 import shell from 'shelljs';
 import chalk from 'chalk';
-import {CONFIG_FILE_NAME, GENERATED_FILES_DIR_NAME} from '../constants';
+import {CONFIG_FILE_NAME} from '../constants';
 import {loadContext} from '../server';
-import loadConfig from '../server/config';
 import build from './build';
 import {BuildCLIOptions} from '@docusaurus/types';
 
@@ -42,10 +41,11 @@ export default async function deploy(
   siteDir: string,
   cliOptions: Partial<BuildCLIOptions> = {},
 ): Promise<void> {
-  const {outDir} = await loadContext(siteDir, {
+  const {outDir, generatedFilesDir, siteConfig} = await loadContext(siteDir, {
+    customConfigFilePath: cliOptions.config,
+    customGeneratedFilesDir: cliOptions.generatedFilesDir,
     customOutDir: cliOptions.outDir,
   });
-  const tempDir = path.join(siteDir, GENERATED_FILES_DIR_NAME);
 
   console.log('Deploy command invoked ...');
   if (!shell.which('git')) {
@@ -62,7 +62,6 @@ export default async function deploy(
     process.env.CURRENT_BRANCH ||
     shell.exec('git rev-parse --abbrev-ref HEAD').stdout.trim();
 
-  const siteConfig = loadConfig(siteDir);
   const organizationName =
     process.env.ORGANIZATION_NAME ||
     process.env.CIRCLE_PROJECT_USERNAME ||
@@ -142,9 +141,9 @@ export default async function deploy(
   const currentCommit = shellExecLog('git rev-parse HEAD').stdout.trim();
 
   const runDeploy = (outputDirectory) => {
-    if (shell.cd(tempDir).code !== 0) {
+    if (shell.cd(generatedFilesDir).code !== 0) {
       throw new Error(
-        `Temp dir ${GENERATED_FILES_DIR_NAME} does not exists. Run build website first.`,
+        `Temp dir ${generatedFilesDir} does not exists. Run build website first.`,
       );
     }
 
@@ -188,7 +187,7 @@ export default async function deploy(
 
     const fromPath = outputDirectory;
     const toPath = path.join(
-      GENERATED_FILES_DIR_NAME,
+      generatedFilesDir,
       `${projectName}-${deploymentBranch}`,
     );
 
@@ -229,7 +228,7 @@ export default async function deploy(
 
   if (!cliOptions.skipBuild) {
     // Clear Docusaurus 2 cache dir for deploy consistency.
-    fs.removeSync(tempDir);
+    fs.removeSync(generatedFilesDir);
 
     // Build static html files, then push to deploymentBranch branch of specified repo.
     build(siteDir, cliOptions, false)

packages/docusaurus/src/commands/serve.ts

@@ -19,11 +19,15 @@ export default async function serve(
   siteDir: string,
   cliOptions: ServeCLIOptions,
 ): Promise<void> {
-  let dir = path.join(siteDir, cliOptions.dir);
+  let dir = path.isAbsolute(cliOptions.dir)
+    ? cliOptions.dir
+    : path.join(siteDir, cliOptions.dir);
   if (cliOptions.build) {
     dir = await build(
       siteDir,
       {
+        generatedFilesDir: cliOptions.generatedFilesDir,
+        config: cliOptions.config,
         outDir: dir,
       },
       false,

packages/docusaurus/src/commands/start.ts

@@ -42,6 +42,7 @@ export default async function start(
 
   function loadSite() {
     return load(siteDir, {
+      customConfigFilePath: cliOptions.config,
       locale: cliOptions.locale,
       localizePath: undefined, // should this be configurable?
     });

packages/docusaurus/src/commands/writeTranslations.ts

@@ -4,6 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import {ConfigOptions} from '@docusaurus/types';
 import {loadContext, loadPluginConfigs} from '../server';
 import initPlugins, {InitPlugin} from '../server/plugins/init';
 
@@ -47,9 +48,12 @@ async function writePluginTranslationFiles({
 
 export default async function writeTranslations(
   siteDir: string,
-  options: WriteTranslationsOptions & {locale?: string},
+  options: WriteTranslationsOptions & ConfigOptions & {locale?: string},
 ): Promise<void> {
-  const context = await loadContext(siteDir, {locale: options.locale});
+  const context = await loadContext(siteDir, {
+    customConfigFilePath: options.config,
+    locale: options.locale,
+  });
   const pluginConfigs = loadPluginConfigs(context);
   const plugins = initPlugins({
     pluginConfigs,

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

@@ -6,8 +6,6 @@ exports[`loadConfig website with incomplete siteConfig 1`] = `
 "
 `;
 
-exports[`loadConfig website with no siteConfig 1`] = `"docusaurus.config.js not found at packages/docusaurus/src/server/__tests__/__fixtures__/nonExisting/docusaurus.config.js"`;
-
 exports[`loadConfig website with useless field (wrong field) in siteConfig 1`] = `
 "\\"favicon\\" is required
 These field(s) [\\"useLessField\\",] are not recognized in docusaurus.config.js.