@docusaurus/core 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/lib/commands/build.js

@@ -7,28 +7,32 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
-const copy_webpack_plugin_1 = tslib_1.__importDefault(require("copy-webpack-plugin"));
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const path_1 = tslib_1.__importDefault(require("path"));
-const react_loadable_ssr_addon_v5_slorber_1 = tslib_1.__importDefault(require("react-loadable-ssr-addon-v5-slorber"));
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const copy_webpack_plugin_1 = (0, tslib_1.__importDefault)(require("copy-webpack-plugin"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const react_loadable_ssr_addon_v5_slorber_1 = (0, tslib_1.__importDefault)(require("react-loadable-ssr-addon-v5-slorber"));
 const webpack_bundle_analyzer_1 = require("webpack-bundle-analyzer");
-const webpack_merge_1 = tslib_1.__importDefault(require("webpack-merge"));
-const constants_1 = require("../constants");
+const webpack_merge_1 = (0, tslib_1.__importDefault)(require("webpack-merge"));
 const server_1 = require("../server");
 const brokenLinks_1 = require("../server/brokenLinks");
-const client_1 = tslib_1.__importDefault(require("../webpack/client"));
-const server_2 = tslib_1.__importDefault(require("../webpack/server"));
+const client_1 = (0, tslib_1.__importDefault)(require("../webpack/client"));
+const server_2 = (0, tslib_1.__importDefault)(require("../webpack/server"));
 const utils_1 = require("../webpack/utils");
-const CleanWebpackPlugin_1 = tslib_1.__importDefault(require("../webpack/plugins/CleanWebpackPlugin"));
+const CleanWebpackPlugin_1 = (0, tslib_1.__importDefault)(require("../webpack/plugins/CleanWebpackPlugin"));
 const i18n_1 = require("../server/i18n");
 const utils_2 = require("@docusaurus/utils");
 async function build(siteDir, cliOptions = {}, 
-// TODO what's the purpose of this arg ?
+// When running build, we force terminate the process to prevent async
+// operations from never returning. However, if run as part of docusaurus
+// deploy, we have to let deploy finish.
+// See https://github.com/facebook/docusaurus/pull/2496
 forceTerminate = true) {
+    ['SIGINT', 'SIGTERM'].forEach((sig) => {
+        process.on(sig, () => process.exit());
+    });
     async function tryToBuildLocale({ locale, isLastLocale, }) {
         try {
-            // console.log(chalk.green(`Site successfully built in locale=${locale}`));
             return await buildLocale({
                 siteDir,
                 locale,
@@ -37,60 +41,59 @@ forceTerminate = true) {
                 isLastLocale,
             });
         }
-        catch (e) {
-            console.error(`Unable to build website for locale ${locale}.`);
-            throw e;
+        catch (err) {
+            logger_1.default.error `Unable to build website for locale name=${locale}.`;
+            throw err;
         }
     }
-    const context = await server_1.loadContext(siteDir, {
+    const context = await (0, server_1.loadContext)(siteDir, {
         customOutDir: cliOptions.outDir,
         customConfigFilePath: cliOptions.config,
         locale: cliOptions.locale,
         localizePath: cliOptions.locale ? false : undefined,
     });
-    const i18n = await i18n_1.loadI18n(context.siteConfig, {
+    const i18n = await (0, i18n_1.loadI18n)(context.siteConfig, {
         locale: cliOptions.locale,
     });
     if (cliOptions.locale) {
         return tryToBuildLocale({ locale: cliOptions.locale, isLastLocale: true });
     }
-    else {
-        if (i18n.locales.length > 1) {
-            console.log(chalk_1.default.yellow(`\nSite will be built for all these locales:
-- ${i18n.locales.join('\n- ')}`));
-        }
-        // We need the default locale to always be the 1st in the list
-        // If we build it last, it would "erase" the localized sites built in subfolders
-        const orderedLocales = [
-            i18n.defaultLocale,
-            ...i18n.locales.filter((locale) => locale !== i18n.defaultLocale),
-        ];
-        const results = await utils_2.mapAsyncSequencial(orderedLocales, (locale) => {
-            const isLastLocale = orderedLocales.indexOf(locale) === orderedLocales.length - 1;
-            return tryToBuildLocale({ locale, isLastLocale });
-        });
-        return results[0];
+    if (i18n.locales.length > 1) {
+        logger_1.default.info `Website will be built for all these locales: ${i18n.locales}`;
     }
+    // We need the default locale to always be the 1st in the list. If we build it
+    // last, it would "erase" the localized sites built in sub-folders
+    const orderedLocales = [
+        i18n.defaultLocale,
+        ...i18n.locales.filter((locale) => locale !== i18n.defaultLocale),
+    ];
+    const results = await (0, utils_2.mapAsyncSequential)(orderedLocales, (locale) => {
+        const isLastLocale = orderedLocales.indexOf(locale) === orderedLocales.length - 1;
+        return tryToBuildLocale({ locale, isLastLocale });
+    });
+    return results[0];
 }
 exports.default = build;
 async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLastLocale, }) {
+    var _a;
     process.env.BABEL_ENV = 'production';
     process.env.NODE_ENV = 'production';
-    console.log(chalk_1.default.blue(`\n[${locale}] Creating an optimized production build...`));
-    const props = await server_1.load(siteDir, {
+    logger_1.default.info `name=${`[${locale}]`} Creating an optimized production build...`;
+    const props = await (0, server_1.load)(siteDir, {
         customOutDir: cliOptions.outDir,
         customConfigFilePath: cliOptions.config,
         locale,
         localizePath: cliOptions.locale ? false : undefined,
     });
     // Apply user webpack config.
-    const { outDir, generatedFilesDir, plugins, siteConfig: { baseUrl, onBrokenLinks }, routes, } = props;
+    const { outDir, generatedFilesDir, plugins, siteConfig: { baseUrl, onBrokenLinks, staticDirectories }, routes, } = props;
     const clientManifestPath = path_1.default.join(generatedFilesDir, 'client-manifest.json');
-    let clientConfig = webpack_merge_1.default(client_1.default(props, cliOptions.minify), {
+    let clientConfig = (0, webpack_merge_1.default)(await (0, client_1.default)(props, cliOptions.minify), {
         plugins: [
             // Remove/clean build folders before building bundles.
             new CleanWebpackPlugin_1.default({ verbose: false }),
-            // Visualize size of webpack output files with an interactive zoomable treemap.
+            // Visualize size of webpack output files with an interactive zoomable
+            // tree map.
             cliOptions.bundleAnalyzer && new webpack_bundle_analyzer_1.BundleAnalyzerPlugin(),
             // Generate client manifests file that will be used for server bundle.
             new react_loadable_ssr_addon_v5_slorber_1.default({
@@ -99,23 +102,20 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
         ].filter(Boolean),
     });
     const allCollectedLinks = {};
-    let serverConfig = server_2.default({
+    let serverConfig = await (0, server_2.default)({
         props,
         onLinksCollected: (staticPagePath, links) => {
             allCollectedLinks[staticPagePath] = links;
         },
     });
-    const staticDir = path_1.default.resolve(siteDir, constants_1.STATIC_DIR_NAME);
-    if (await fs_extra_1.default.pathExists(staticDir)) {
-        serverConfig = webpack_merge_1.default(serverConfig, {
+    if (staticDirectories.length > 0) {
+        await Promise.all(staticDirectories.map((dir) => fs_extra_1.default.ensureDir(dir)));
+        serverConfig = (0, webpack_merge_1.default)(serverConfig, {
             plugins: [
                 new copy_webpack_plugin_1.default({
-                    patterns: [
-                        {
-                            from: staticDir,
-                            to: outDir,
-                        },
-                    ],
+                    patterns: staticDirectories
+                        .map((dir) => path_1.default.resolve(siteDir, dir))
+                        .map((dir) => ({ from: dir, to: outDir })),
                 }),
             ],
         });
@@ -125,13 +125,13 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
         var _a, _b;
         const { configureWebpack, configurePostCss } = plugin;
         if (configurePostCss) {
-            clientConfig = utils_1.applyConfigurePostCss(configurePostCss, clientConfig);
+            clientConfig = (0, utils_1.applyConfigurePostCss)(configurePostCss, clientConfig);
         }
         if (configureWebpack) {
-            clientConfig = utils_1.applyConfigureWebpack(configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
-            clientConfig, false, (_a = props.siteConfig.webpack) === null || _a === void 0 ? void 0 : _a.jsLoader);
-            serverConfig = utils_1.applyConfigureWebpack(configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
-            serverConfig, true, (_b = props.siteConfig.webpack) === null || _b === void 0 ? void 0 : _b.jsLoader);
+            clientConfig = (0, utils_1.applyConfigureWebpack)(configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
+            clientConfig, false, (_a = props.siteConfig.webpack) === null || _a === void 0 ? void 0 : _a.jsLoader, plugin.content);
+            serverConfig = (0, utils_1.applyConfigureWebpack)(configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
+            serverConfig, true, (_b = props.siteConfig.webpack) === null || _b === void 0 ? void 0 : _b.jsLoader, plugin.content);
         }
     });
     // Make sure generated client-manifest is cleaned first so we don't reuse
@@ -140,11 +140,9 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
         await fs_extra_1.default.unlink(clientManifestPath);
     }
     // Run webpack to build JS bundle (client) and static html files (server).
-    await utils_1.compile([clientConfig, serverConfig]);
+    await (0, utils_1.compile)([clientConfig, serverConfig]);
     // Remove server.bundle.js because it is not needed.
-    if (serverConfig.output &&
-        serverConfig.output.filename &&
-        typeof serverConfig.output.filename === 'string') {
+    if (typeof ((_a = serverConfig.output) === null || _a === void 0 ? void 0 : _a.filename) === 'string') {
         const serverBundle = path_1.default.join(outDir, serverConfig.output.filename);
         if (await fs_extra_1.default.pathExists(serverBundle)) {
             await fs_extra_1.default.unlink(serverBundle);
@@ -155,18 +153,18 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
         if (!plugin.postBuild) {
             return;
         }
-        await plugin.postBuild(props);
+        await plugin.postBuild({ ...props, content: plugin.content });
     }));
-    await brokenLinks_1.handleBrokenLinks({
+    await (0, brokenLinks_1.handleBrokenLinks)({
         allCollectedLinks,
         routes,
         onBrokenLinks,
         outDir,
         baseUrl,
     });
-    console.log(`${chalk_1.default.green(`Success!`)} Generated static files in ${chalk_1.default.cyan(path_1.default.relative(process.cwd(), outDir))}.`);
+    logger_1.default.success `Generated static files in path=${path_1.default.relative(process.cwd(), outDir)}.`;
     if (isLastLocale) {
-        console.log(`\nUse ${chalk_1.default.greenBright('`npm run serve`')} to test your build locally.\n`);
+        logger_1.default.info `Use code=${'npm run serve'} command to test your build locally.`;
     }
     if (forceTerminate && isLastLocale && !cliOptions.bundleAnalyzer) {
         process.exit(0);

package/lib/commands/clear.d.ts

@@ -1 +1,7 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 export default function clear(siteDir: string): Promise<unknown>;

package/lib/commands/clear.js

@@ -1,32 +1,43 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const path_1 = tslib_1.__importDefault(require("path"));
-const chalk = require("chalk");
-const constants_1 = require("../constants");
-function removePath(fsPath) {
-    return fs_extra_1.default
-        .remove(path_1.default.join(fsPath))
-        .then(() => {
-        console.log(`${chalk.green(`Removing ${fsPath}`)}`);
-    })
-        .catch((err) => {
-        console.error(`Could not remove ${fsPath}`);
-        console.error(err);
-    });
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+async function removePath(entry) {
+    if (!(await fs_extra_1.default.pathExists(entry.path))) {
+        return;
+    }
+    try {
+        await fs_extra_1.default.remove(entry.path);
+        logger_1.default.success `Removed the ${entry.description} at path=${entry.path}.`;
+    }
+    catch (err) {
+        logger_1.default.error `Could not remove the ${entry.description} at path=${entry.path}.`;
+        logger_1.default.error(err);
+    }
 }
 async function clear(siteDir) {
-    return Promise.all([
-        removePath(path_1.default.join(siteDir, constants_1.GENERATED_FILES_DIR_NAME)),
-        removePath(path_1.default.join(siteDir, constants_1.DEFAULT_BUILD_DIR_NAME)),
-        removePath(path_1.default.join(siteDir, 'node_modules', '.cache')),
-    ]);
+    const generatedFolder = {
+        path: path_1.default.join(siteDir, utils_1.GENERATED_FILES_DIR_NAME),
+        description: 'generated folder',
+    };
+    const buildFolder = {
+        path: path_1.default.join(siteDir, utils_1.DEFAULT_BUILD_DIR_NAME),
+        description: 'build output folder',
+    };
+    // In Yarn PnP, cache is stored in `.yarn/.cache` because n_m doesn't exist
+    const cacheFolders = ['node_modules', '.yarn'].map((p) => ({
+        path: path_1.default.join(siteDir, p, '.cache'),
+        description: 'Webpack persistent cache folder',
+    }));
+    return Promise.all([generatedFolder, buildFolder, ...cacheFolders].map(removePath));
 }
 exports.default = clear;

package/lib/commands/commandUtils.d.ts

@@ -1,3 +1,9 @@
-import { HostPortCLIOptions } from '@docusaurus/types';
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { HostPortCLIOptions } from '@docusaurus/types';
 export declare function getCLIOptionHost(hostOption: HostPortCLIOptions['host']): string;
 export declare function getCLIOptionPort(portOption: HostPortCLIOptions['port'], host: string): Promise<number | null>;

package/lib/commands/commandUtils.js

@@ -1,21 +1,21 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCLIOptionPort = exports.getCLIOptionHost = void 0;
-const tslib_1 = require("tslib");
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-const choosePort_1 = tslib_1.__importDefault(require("../choosePort"));
-const constants_1 = require("../constants");
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCLIOptionPort = exports.getCLIOptionHost = void 0;
+const tslib_1 = require("tslib");
+const choosePort_1 = (0, tslib_1.__importDefault)(require("../choosePort"));
+const utils_1 = require("@docusaurus/utils");
 function getCLIOptionHost(hostOption) {
     return hostOption || 'localhost';
 }
 exports.getCLIOptionHost = getCLIOptionHost;
 async function getCLIOptionPort(portOption, host) {
-    const basePort = portOption ? parseInt(portOption, 10) : constants_1.DEFAULT_PORT;
-    return choosePort_1.default(host, basePort);
+    const basePort = portOption ? parseInt(portOption, 10) : utils_1.DEFAULT_PORT;
+    return (0, choosePort_1.default)(host, basePort);
 }
 exports.getCLIOptionPort = getCLIOptionPort;

package/lib/commands/deploy.d.ts

@@ -4,5 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { BuildCLIOptions } from '@docusaurus/types';
+import type { BuildCLIOptions } from '@docusaurus/types';
+export declare function buildSshUrl(githubHost: string, organizationName: string, projectName: string, githubPort?: string): string;
+export declare function buildHttpsUrl(gitCredentials: string, githubHost: string, organizationName: string, projectName: string, githubPort?: string): string;
+export declare function hasSSHProtocol(sourceRepoUrl: string): boolean;
 export default function deploy(siteDir: string, cliOptions?: Partial<BuildCLIOptions>): Promise<void>;

package/lib/commands/deploy.js

@@ -6,15 +6,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSSHProtocol = exports.buildHttpsUrl = exports.buildSshUrl = void 0;
 const tslib_1 = require("tslib");
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const shelljs_1 = tslib_1.__importDefault(require("shelljs"));
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const shelljs_1 = (0, tslib_1.__importDefault)(require("shelljs"));
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
 const server_1 = require("../server");
-const build_1 = tslib_1.__importDefault(require("./build"));
-const path_1 = tslib_1.__importDefault(require("path"));
-const os_1 = tslib_1.__importDefault(require("os"));
-const buildRemoteBranchUrl_1 = require("./buildRemoteBranchUrl");
+const build_1 = (0, tslib_1.__importDefault)(require("./build"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const os_1 = (0, tslib_1.__importDefault)(require("os"));
 // GIT_PASS env variable should not appear in logs
 function obfuscateGitPass(str) {
     const gitPass = process.env.GIT_PASS;
@@ -25,72 +25,126 @@ function obfuscateGitPass(str) {
 function shellExecLog(cmd) {
     try {
         const result = shelljs_1.default.exec(cmd);
-        console.log(`${chalk_1.default.cyan('CMD:')} ${obfuscateGitPass(cmd)} ${chalk_1.default.cyan(`(code=${result.code})`)}`);
+        logger_1.default.info `code=${obfuscateGitPass(cmd)} subdue=${`code: ${result.code}`}`;
         return result;
     }
-    catch (e) {
-        console.log(`${chalk_1.default.red('CMD:')} ${obfuscateGitPass(cmd)}`);
-        throw e;
+    catch (err) {
+        logger_1.default.error `code=${obfuscateGitPass(cmd)}`;
+        throw err;
     }
 }
+function buildSshUrl(githubHost, organizationName, projectName, githubPort) {
+    if (githubPort) {
+        return `ssh://git@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
+    }
+    return `git@${githubHost}:${organizationName}/${projectName}.git`;
+}
+exports.buildSshUrl = buildSshUrl;
+function buildHttpsUrl(gitCredentials, githubHost, organizationName, projectName, githubPort) {
+    if (githubPort) {
+        return `https://${gitCredentials}@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
+    }
+    return `https://${gitCredentials}@${githubHost}/${organizationName}/${projectName}.git`;
+}
+exports.buildHttpsUrl = buildHttpsUrl;
+function hasSSHProtocol(sourceRepoUrl) {
+    try {
+        if (new URL(sourceRepoUrl).protocol === 'ssh:') {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        // Fails when there isn't a protocol
+        return /^(?:[\w-]+@)?[\w.-]+:[\w./_-]+/.test(sourceRepoUrl); // git@github.com:facebook/docusaurus.git
+    }
+}
+exports.hasSSHProtocol = hasSSHProtocol;
 async function deploy(siteDir, cliOptions = {}) {
-    const { outDir, siteConfig, siteConfigPath } = await server_1.loadContext(siteDir, {
+    const { outDir, siteConfig, siteConfigPath } = await (0, server_1.loadContext)(siteDir, {
         customConfigFilePath: cliOptions.config,
         customOutDir: cliOptions.outDir,
     });
-    console.log('Deploy command invoked ...');
+    if (typeof siteConfig.trailingSlash === 'undefined') {
+        logger_1.default.warn(`When deploying to GitHub Pages, it is better to use an explicit "trailingSlash" site config.
+Otherwise, GitHub Pages will add an extra trailing slash to your site urls only on direct-access (not when navigation) with a server redirect.
+This behavior can have SEO impacts and create relative link issues.
+`);
+    }
+    logger_1.default.info('Deploy command invoked...');
     if (!shelljs_1.default.which('git')) {
         throw new Error('Git not installed or on the PATH!');
     }
+    // Source repo is the repo from where the command is invoked
+    const sourceRepoUrl = shelljs_1.default
+        .exec('git config --get remote.origin.url', { silent: true })
+        .stdout.trim();
+    // The source branch; defaults to the currently checked out branch
+    const sourceBranch = process.env.CURRENT_BRANCH ||
+        shelljs_1.default.exec('git rev-parse --abbrev-ref HEAD', { silent: true }).stdout.trim();
     const gitUser = process.env.GIT_USER;
-    if (!gitUser) {
-        throw new Error('Please set the GIT_USER environment variable!');
+    let useSSH = process.env.USE_SSH !== undefined &&
+        process.env.USE_SSH.toLowerCase() === 'true';
+    if (!gitUser && !useSSH) {
+        // If USE_SSH is unspecified: try inferring from repo URL
+        if (process.env.USE_SSH === undefined && hasSSHProtocol(sourceRepoUrl)) {
+            useSSH = true;
+        }
+        else {
+            throw new Error('Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead!');
+        }
     }
-    // The branch that contains the latest docs changes that will be deployed.
-    const currentBranch = process.env.CURRENT_BRANCH ||
-        shelljs_1.default.exec('git rev-parse --abbrev-ref HEAD').stdout.trim();
     const organizationName = process.env.ORGANIZATION_NAME ||
         process.env.CIRCLE_PROJECT_USERNAME ||
         siteConfig.organizationName;
     if (!organizationName) {
-        throw new Error(`Missing project organization name. Did you forget to define 'organizationName' in ${siteConfigPath}? You may also export it via the ORGANIZATION_NAME environment variable.`);
+        throw new Error(`Missing project organization name. Did you forget to define "organizationName" in ${siteConfigPath}? You may also export it via the ORGANIZATION_NAME environment variable.`);
     }
-    console.log(`${chalk_1.default.cyan('organizationName:')} ${organizationName}`);
+    logger_1.default.info `organizationName: name=${organizationName}`;
     const projectName = process.env.PROJECT_NAME ||
         process.env.CIRCLE_PROJECT_REPONAME ||
         siteConfig.projectName;
     if (!projectName) {
-        throw new Error(`Missing project name. Did you forget to define 'projectName' in ${siteConfigPath}? You may also export it via the PROJECT_NAME environment variable.`);
+        throw new Error(`Missing project name. Did you forget to define "projectName" in ${siteConfigPath}? You may also export it via the PROJECT_NAME environment variable.`);
     }
-    console.log(`${chalk_1.default.cyan('projectName:')} ${projectName}`);
+    logger_1.default.info `projectName: name=${projectName}`;
     // We never deploy on pull request.
     const isPullRequest = process.env.CI_PULL_REQUEST || process.env.CIRCLE_PULL_REQUEST;
     if (isPullRequest) {
-        shelljs_1.default.echo('Skipping deploy on a pull request');
+        shelljs_1.default.echo('Skipping deploy on a pull request.');
         shelljs_1.default.exit(0);
     }
-    // github.io indicates organization repos that deploy via master. All others use gh-pages.
-    const deploymentBranch = process.env.DEPLOYMENT_BRANCH ||
-        (projectName.indexOf('.github.io') !== -1 ? 'master' : 'gh-pages');
-    console.log(`${chalk_1.default.cyan('deploymentBranch:')} ${deploymentBranch}`);
+    // github.io indicates organization repos that deploy via default branch.
+    // All others use gh-pages. Organization deploys looks like:
+    // - Git repo: https://github.com/<organization>/<organization>.github.io
+    // - Site url: https://<organization>.github.io
+    const isGitHubPagesOrganizationDeploy = projectName.includes('.github.io');
+    if (isGitHubPagesOrganizationDeploy &&
+        !process.env.DEPLOYMENT_BRANCH &&
+        !siteConfig.deploymentBranch) {
+        throw new Error(`For GitHub pages organization deployments, 'docusaurus deploy' does not assume anymore that 'master' is your default Git branch.
+Please provide the branch name to deploy to as an environment variable, for example DEPLOYMENT_BRANCH=main or DEPLOYMENT_BRANCH=master .
+You can also set the deploymentBranch property in docusaurus.config.js .`);
+    }
+    const deploymentBranch = process.env.DEPLOYMENT_BRANCH || siteConfig.deploymentBranch || 'gh-pages';
+    logger_1.default.info `deploymentBranch: name=${deploymentBranch}`;
     const githubHost = process.env.GITHUB_HOST || siteConfig.githubHost || 'github.com';
     const githubPort = process.env.GITHUB_PORT || siteConfig.githubPort;
-    const gitPass = process.env.GIT_PASS;
-    let gitCredentials = `${gitUser}`;
-    if (gitPass) {
-        gitCredentials = `${gitCredentials}:${gitPass}`;
+    let deploymentRepoURL;
+    if (useSSH) {
+        deploymentRepoURL = buildSshUrl(githubHost, organizationName, projectName, githubPort);
     }
-    const useSSH = process.env.USE_SSH;
-    const remoteBranch = buildRemoteBranchUrl_1.buildUrl(githubHost, githubPort, gitCredentials, organizationName, projectName, useSSH !== undefined && useSSH.toLowerCase() === 'true');
-    console.log(`${chalk_1.default.cyan('Remote branch:')} ${obfuscateGitPass(remoteBranch)}`);
+    else {
+        const gitPass = process.env.GIT_PASS;
+        const gitCredentials = gitPass ? `${gitUser}:${gitPass}` : gitUser;
+        deploymentRepoURL = buildHttpsUrl(gitCredentials, githubHost, organizationName, projectName, githubPort);
+    }
+    logger_1.default.info `Remote repo URL: name=${obfuscateGitPass(deploymentRepoURL)}`;
     // Check if this is a cross-repo publish.
-    const currentRepoUrl = shelljs_1.default
-        .exec('git config --get remote.origin.url')
-        .stdout.trim();
-    const crossRepoPublish = !currentRepoUrl.endsWith(`${organizationName}/${projectName}.git`);
+    const crossRepoPublish = !sourceRepoUrl.endsWith(`${organizationName}/${projectName}.git`);
     // We don't allow deploying to the same branch unless it's a cross publish.
-    if (currentBranch === deploymentBranch && !crossRepoPublish) {
-        throw new Error(`You cannot deploy from this branch (${currentBranch}).` +
+    if (sourceBranch === deploymentBranch && !crossRepoPublish) {
+        throw new Error(`You cannot deploy from this branch (${sourceBranch}).` +
             '\nYou will need to checkout to a different branch!');
     }
     // Save the commit hash that triggers publish-gh-pages before checking
@@ -99,42 +153,32 @@ async function deploy(siteDir, cliOptions = {}) {
     const runDeploy = async (outputDirectory) => {
         const fromPath = outputDirectory;
         const toPath = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), `${projectName}-${deploymentBranch}`));
-        if (shellExecLog(`git clone ${remoteBranch} ${toPath}`).code !== 0) {
-            throw new Error(`Error: git clone failed in ${toPath}`);
-        }
         shelljs_1.default.cd(toPath);
-        // If the default branch is the one we're deploying to, then we'll fail
-        // to create it. This is the case of a cross-repo publish, where we clone
-        // a github.io repo with a default master branch.
-        const defaultBranch = shelljs_1.default
-            .exec('git rev-parse --abbrev-ref HEAD')
-            .stdout.trim();
-        if (defaultBranch !== deploymentBranch) {
-            if (shellExecLog(`git checkout origin/${deploymentBranch}`).code !== 0) {
-                if (shellExecLog(`git checkout --orphan ${deploymentBranch}`).code !== 0) {
-                    throw new Error(`Error: Git checkout ${deploymentBranch} failed`);
-                }
-            }
-            else if (shellExecLog(`git checkout -b ${deploymentBranch}`).code +
-                shellExecLog(`git branch --set-upstream-to=origin/${deploymentBranch}`).code !==
-                0) {
-                throw new Error(`Error: Git checkout ${deploymentBranch} failed`);
-            }
+        // Check out deployment branch when cloning repository, and then remove all
+        // the files in the directory. If the 'clone' command fails, assume that
+        // the deployment branch doesn't exist, and initialize git in an empty
+        // directory, check out a clean deployment branch and add remote.
+        if (shellExecLog(`git clone --depth 1 --branch ${deploymentBranch} ${deploymentRepoURL} "${toPath}"`).code === 0) {
+            shellExecLog('git rm -rf .');
+        }
+        else {
+            shellExecLog('git init');
+            shellExecLog(`git checkout -b ${deploymentBranch}`);
+            shellExecLog(`git remote add origin ${deploymentRepoURL}`);
         }
-        shellExecLog('git rm -rf .');
         try {
             await fs_extra_1.default.copy(fromPath, toPath);
         }
-        catch (error) {
-            throw new Error(`Error: Copying build assets from "${fromPath}" to "${toPath}" failed with error '${error}'`);
+        catch (err) {
+            logger_1.default.error `Copying build assets from path=${fromPath} to path=${toPath} failed.`;
+            throw err;
         }
-        shelljs_1.default.cd(toPath);
         shellExecLog('git add --all');
         const commitMessage = process.env.CUSTOM_COMMIT_MESSAGE ||
             `Deploy website - based on ${currentCommit}`;
         const commitResults = shellExecLog(`git commit -m "${commitMessage}"`);
         if (shellExecLog(`git push --force origin ${deploymentBranch}`).code !== 0) {
-            throw new Error('Error: Git push failed');
+            throw new Error('Running "git push" command failed. Does the GitHub user account you are using have push access to the repository?');
         }
         else if (commitResults.code === 0) {
             // The commit might return a non-zero value when site is up to date.
@@ -148,18 +192,18 @@ async function deploy(siteDir, cliOptions = {}) {
                 // GitHub enterprise hosting.
                 websiteURL = `https://${githubHost}/pages/${organizationName}/${projectName}/`;
             }
-            shelljs_1.default.echo(`Website is live at ${websiteURL}`);
+            shelljs_1.default.echo(`Website is live at "${websiteURL}".`);
             shelljs_1.default.exit(0);
         }
     };
     if (!cliOptions.skipBuild) {
-        // Build static html files, then push to deploymentBranch branch of specified repo.
+        // Build site, then push to deploymentBranch branch of specified repo.
         try {
-            await runDeploy(await build_1.default(siteDir, cliOptions, false));
+            await runDeploy(await (0, build_1.default)(siteDir, cliOptions, false));
         }
-        catch (buildError) {
-            console.error(buildError);
-            process.exit(1);
+        catch (err) {
+            logger_1.default.error('Deployment of the build output failed.');
+            throw err;
         }
     }
     else {

package/lib/commands/external.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Command } from 'commander';
-export default function externalCommand(cli: Command, siteDir: string): Promise<void>;
+import type { CommanderStatic } from 'commander';
+export default function externalCommand(cli: CommanderStatic, siteDir: string): Promise<void>;

package/lib/commands/external.js

@@ -8,11 +8,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const server_1 = require("../server");
-const init_1 = tslib_1.__importDefault(require("../server/plugins/init"));
+const init_1 = (0, tslib_1.__importDefault)(require("../server/plugins/init"));
 async function externalCommand(cli, siteDir) {
-    const context = await server_1.loadContext(siteDir);
-    const pluginConfigs = server_1.loadPluginConfigs(context);
-    const plugins = init_1.default({ pluginConfigs, context });
+    const context = await (0, server_1.loadContext)(siteDir);
+    const pluginConfigs = await (0, server_1.loadPluginConfigs)(context);
+    const plugins = await (0, init_1.default)({ pluginConfigs, context });
     // Plugin Lifecycle - extendCli.
     plugins.forEach((plugin) => {
         const { extendCli } = plugin;