feat(v2): add custom output directory to build (#2417)

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

@@ -63,6 +63,7 @@ export interface StartCLIOptions {
 
 export interface BuildCLIOptions {
   bundleAnalyzer: boolean;
+  outDir: string;
 }
 
 export interface LoadContext {

packages/docusaurus/bin/docusaurus.js

@@ -41,9 +41,14 @@ cli
     '--bundle-analyzer',
     'Visualize size of webpack output files with an interactive zoomable treemap (default = false)',
   )
-  .action((siteDir = '.', {bundleAnalyzer}) => {
+  .option(
+    '--out-dir <dir>',
+    'The full path for the new output directory, relative to the current workspace (default = build).',
+  )
+  .action((siteDir = '.', {bundleAnalyzer, outDir}) => {
     wrapCommand(build)(path.resolve(siteDir), {
       bundleAnalyzer,
+      outDir,
     });
   });
 
@@ -57,8 +62,12 @@ cli
 cli
   .command('deploy [siteDir]')
   .description('Deploy website to GitHub pages')
-  .action((siteDir = '.') => {
-    wrapCommand(deploy)(path.resolve(siteDir));
+  .option(
+    '--out-dir <dir>',
+    'The full path for the new output directory, relative to the current workspace (default = build).',
+  )
+  .action((siteDir = '.', {outDir}) => {
+    wrapCommand(deploy)(path.resolve(siteDir), {outDir});
   });
 
 cli

packages/docusaurus/src/commands/build.ts

@@ -47,12 +47,12 @@ function compile(config: Configuration[]): Promise<any> {
 export async function build(
   siteDir: string,
   cliOptions: Partial<BuildCLIOptions> = {},
-): Promise<void> {
+): Promise<string> {
   process.env.BABEL_ENV = 'production';
   process.env.NODE_ENV = 'production';
   console.log(chalk.blue('Creating an optimized production build...'));
 
-  const props: Props = await load(siteDir);
+  const props: Props = await load(siteDir, cliOptions.outDir);
 
   // Apply user webpack config.
   const {outDir, generatedFilesDir, plugins} = props;
@@ -147,4 +147,5 @@ export async function build(
       relativeDir,
     )}.\n`,
   );
+  return outDir;
 }

packages/docusaurus/src/commands/deploy.ts

@@ -8,15 +8,15 @@
 import fs from 'fs-extra';
 import path from 'path';
 import shell from 'shelljs';
-import {
-  BUILD_DIR_NAME,
-  CONFIG_FILE_NAME,
-  GENERATED_FILES_DIR_NAME,
-} from '../constants';
+import {CONFIG_FILE_NAME, GENERATED_FILES_DIR_NAME} from '../constants';
 import {loadConfig} from '../server/config';
 import {build} from './build';
+import {BuildCLIOptions} from '@docusaurus/types';
 
-export async function deploy(siteDir: string): Promise<void> {
+export async function deploy(
+  siteDir: string,
+  cliOptions: Partial<BuildCLIOptions> = {},
+): Promise<void> {
   console.log('Deploy command invoked ...');
   if (!shell.which('git')) {
     throw new Error('Sorry, this script requires git');
@@ -98,8 +98,8 @@ export async function deploy(siteDir: string): Promise<void> {
   fs.removeSync(tempDir);
 
   // Build static html files, then push to deploymentBranch branch of specified repo.
-  build(siteDir)
-    .then(() => {
+  build(siteDir, cliOptions)
+    .then(outDir => {
       shell.cd(tempDir);
 
       if (
@@ -140,7 +140,7 @@ export async function deploy(siteDir: string): Promise<void> {
 
       shell.cd('../..');
 
-      const fromPath = path.join(BUILD_DIR_NAME);
+      const fromPath = outDir;
       const toPath = path.join(
         GENERATED_FILES_DIR_NAME,
         `${projectName}-${deploymentBranch}`,

packages/docusaurus/src/server/index.ts

@@ -28,13 +28,18 @@ import {
 } from '@docusaurus/types';
 import {loadHtmlTags} from './html-tags';
 
-export function loadContext(siteDir: string): LoadContext {
+export function loadContext(
+  siteDir: string,
+  customOutDir?: string,
+): LoadContext {
   const generatedFilesDir: string = path.resolve(
     siteDir,
     GENERATED_FILES_DIR_NAME,
   );
   const siteConfig: DocusaurusConfig = loadConfig(siteDir);
-  const outDir = path.resolve(siteDir, BUILD_DIR_NAME);
+  const outDir = customOutDir
+    ? path.resolve(customOutDir)
+    : path.resolve(siteDir, BUILD_DIR_NAME);
   const {baseUrl} = siteConfig;
 
   return {
@@ -58,9 +63,12 @@ export function loadPluginConfigs(context: LoadContext): PluginConfig[] {
   ];
 }
 
-export async function load(siteDir: string): Promise<Props> {
+export async function load(
+  siteDir: string,
+  customOutDir?: string,
+): Promise<Props> {
   // Context.
-  const context: LoadContext = loadContext(siteDir);
+  const context: LoadContext = loadContext(siteDir, customOutDir);
   const {generatedFilesDir, siteConfig, outDir, baseUrl} = context;
   const genSiteConfig = generate(
     generatedFilesDir,

website/docs/cli.md

@@ -59,6 +59,7 @@ Compiles your site for production.
 | Options | Default | Description |
 | --- | --- | --- |
 | `--bundle-analyzer` |  | Analyze your bundle with [bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) |
+| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
 
 ### `docusaurus swizzle`
 
@@ -90,3 +91,9 @@ To learn more about swizzling, check [here](#).
 ### `docusaurus deploy`
 
 Deploys your site with [GitHub Pages](https://pages.github.com/).
+
+**options**
+
+| Options | Default | Description |
+| --- | --- | --- |
+| `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |