From 13d07eff138b9838cb0fbb7125290825424bdd7a Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Mon, 8 Nov 2021 14:15:28 +0800 Subject: [PATCH] docs: refer to deployed branch as deployment rather than target (#5903) --- website/docs/deployment.mdx | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index bb4cb9cdef..962d6052b3 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -82,9 +82,9 @@ Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.githu ### Overview {#github-pages-overview} -Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"target"**, respectively. +Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as **"source"** and **"deployment"**, respectively. -Each GitHub repository is associated with a GitHub Pages service. If the target repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the target repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`. +Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called `my-org/my-project` (where `my-org` is the organization name or username), the deployed site will appear at `https://my-org.github.io/my-project/`. Specially, if the deployment repository is called `my-org/my-org.github.io` (the _organization GitHub Pages repo_), the site will appear at `https://my-org.github.io/`. :::info @@ -94,9 +94,9 @@ You may refer to GitHub Pages' documentation [User, Organization, and Project Pa ::: -GitHub Pages picks up deploy-ready files (the output from `docusaurus build`) from the default branch (`master` / `main`, usually) or the `gh-pages` branch, and either from the root or the `/docs` folder. You can configure that through `Settings > Pages` in your repository. This branch will be called the "target branch". +GitHub Pages picks up deploy-ready files (the output from `docusaurus build`) from the default branch (`master` / `main`, usually) or the `gh-pages` branch, and either from the root or the `/docs` folder. You can configure that through `Settings > Pages` in your repository. This branch will be called the "deployment branch". -We provide a `docusaurus deploy` command that helps you deploy your site from the source branch to the target branch in one command: clone, build, and commit. +We provide a `docusaurus deploy` command that helps you deploy your site from the source branch to the deployment branch in one command: clone, build, and commit. ### `docusaurus.config.js` settings {#docusaurusconfigjs-settings} @@ -104,9 +104,9 @@ First, modify your `docusaurus.config.js` and add the following params: | Name | Description | | --- | --- | -| `organizationName` | The GitHub user or organization that owns the target repository. | -| `projectName` | The name of the target repository. | -| `deploymentBranch` | The name of target branch. Defaults to `'gh-pages'` for non-organization GitHub Pages repos (`projectName` not ending in `.github.io`). Otherwise, this needs to be explicit as a config field or environment variable. | +| `organizationName` | The GitHub user or organization that owns the deployment repository. | +| `projectName` | The name of the deployment repository. | +| `deploymentBranch` | The name of deployment branch. Defaults to `'gh-pages'` for non-organization GitHub Pages repos (`projectName` not ending in `.github.io`). Otherwise, this needs to be explicit as a config field or environment variable. | These fields also have their environment variable counterparts, which have a higher priority: `ORGANIZATION_NAME`, `PROJECT_NAME`, and `DEPLOYMENT_BRANCH`. @@ -142,7 +142,7 @@ Specify the Git user as an environment variable. | Name | Description | | --- | --- | -| `GIT_USER` | The username for a GitHub account that **has push access to the target repo**. For your own repositories, this will usually be your GitHub username. | +| `GIT_USER` | The username for a GitHub account that **has push access to the deployment repo**. For your own repositories, this will usually be your GitHub username. | Optional parameters, also set as environment variables: @@ -201,17 +201,17 @@ Alternatively, you can use SSH (`USE_SSH=true`) to login. [GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository. -The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), under a folder called `website/`, and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _target branch_ is `gh-pages`). +The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), under a folder called `website/`, and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _deployment branch_ is `gh-pages`). Our goal is that: 1. When a new pull request is made to `main` and updates `website/`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`. 2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new built output will be served on the GitHub Pages site. This job will be called `deploy`. -Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your target branch (`gh-pages`), choose the relevant tab below: +Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment branch (`gh-pages`), choose the relevant tab below: -- Source repo and target repo are the **same** repository. -- The target repo is a **remote** repository, different from the source. +- Source repo and deployment repo are the **same** repository. +- The deployment repo is a **remote** repository, different from the source. ````mdx-code-block