feat: allow user to specify deploymentBranch property in docusaurus.config.js (#5841)

* feat: allow user to specify deploymentBranch property in docusaurus.config.js

* docs: remove extra backtick

* docs: fix broken code block

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

@@ -39,6 +39,7 @@ export interface DocusaurusConfig {
   noIndex: boolean;
   organizationName?: string;
   projectName?: string;
+  deploymentBranch?: string;
   githubHost?: string;
   githubPort?: string;
   plugins?: PluginConfig[];

packages/docusaurus/src/commands/deploy.ts

@@ -109,13 +109,18 @@ This behavior can have SEO impacts and create relative link issues.
   // - Site url: https://<organization>.github.io
   const isGitHubPagesOrganizationDeploy =
     projectName.indexOf('.github.io') !== -1;
-  if (isGitHubPagesOrganizationDeploy && !process.env.DEPLOYMENT_BRANCH) {
+  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.
-Try using DEPLOYMENT_BRANCH=main or DEPLOYMENT_BRANCH=master`);
+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 || 'gh-pages';
+  const deploymentBranch =
+    process.env.DEPLOYMENT_BRANCH || siteConfig.deploymentBranch || 'gh-pages';
   console.log(`${chalk.cyan('deploymentBranch:')} ${deploymentBranch}`);
 
   const githubHost =

packages/docusaurus/src/server/configValidation.ts

@@ -143,6 +143,7 @@ export const ConfigSchema = Joi.object({
     .default(DEFAULT_CONFIG.onDuplicateRoutes),
   organizationName: Joi.string().allow(''),
   projectName: Joi.string().allow(''),
+  deploymentBranch: Joi.string().optional(),
   customFields: Joi.object().unknown().default(DEFAULT_CONFIG.customFields),
   githubHost: Joi.string(),
   plugins: Joi.array().items(PluginSchema).default(DEFAULT_CONFIG.plugins),

website/docs/api/docusaurus.config.js.md

@@ -194,6 +194,18 @@ module.exports = {
 };
 ```
 
+### `deploymentBranch` {#deploymentbranch}
+
+- Type: `string`
+
+The name of the branch to deploy the static files to. Used by the deployment command.
+
+```js title="docusaurus.config.js"
+module.exports = {
+  deploymentBranch: 'gh-pages',
+};
+```
+
 ### `githubHost` {#githubhost}
 
 - Type: `string`

website/docs/configuration.md

@@ -29,7 +29,7 @@ They are used in a number of places such as your site's title and headings, brow
 
 ### Deployment configurations {#deployment-configurations}
 
-Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command.
+Deployment configurations such as `projectName`, `organizationName`, and optionally `deploymentBranch` are used when you deploy your site with the `deploy` command.
 
 It is recommended to check the [deployment docs](deployment.mdx) for more information.
 

website/docs/deployment.mdx

@@ -75,6 +75,7 @@ First, modify your `docusaurus.config.js` and add the required params:
 | --- | --- |
 | `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, it is your GitHub username. In the case of Docusaurus, it is "_facebook_" which is the GitHub organization that owns Docusaurus. |
 | `projectName` | The name of the GitHub repository. For example, the repository name for Docusaurus is "docusaurus", so the project name is "docusaurus". |
+| `deploymentBranch` | The name of the branch to deploy the static files to. This defaults to "gh-pages" for non-organization GitHub Pages repos. If the repo name ends in ".github.io", you have to either specify this property or set the environment variable `DEPLOYMENT_BRANCH`. |
 | `url` | URL for your GitHub Page's user/organization page. This is commonly https://_username_.github.io. |
 | `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. |
 
@@ -127,7 +128,7 @@ Optional parameters, also set as environment variables:
 | Name | Description |
 | --- | --- |
 | `USE_SSH` | Set to `true` to use SSH instead of the default HTTPS for the connection to the GitHub repo. |
-| `DEPLOYMENT_BRANCH` | The branch that the website will be deployed to, defaults to `gh-pages`. For GitHub Pages Organization repos (`config.projectName` ending in `github.io`), this env variable is required. |
+| `DEPLOYMENT_BRANCH` | The branch that the website will be deployed to, defaults to `gh-pages`. For GitHub Pages Organization repos (`config.projectName` ending in `github.io`), you need to either set this env variable or specify the `deploymentBranch` param in `docusaurus.config.js`. |
 | `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `main`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. |
 | `GIT_PASS` | Password (or token) of the `git` user (specified by `GIT_USER`). For example, to facilitate non-interactive deployment (e.g. continuous deployment) |