diff --git a/docs/en/commands.html b/docs/en/commands.html index f9a6461b25..024eb17fd4 100644 --- a/docs/en/commands.html +++ b/docs/en/commands.html @@ -51,12 +51,23 @@

docusaurus-publish

Alias: publish-gh-pages

Builds, then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined:

+

The following is generally set manually by the user in the CircleCI config.yml file.

+

e.g.,

+
GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
+
+

The following are set by the CircleCI environment during the build process.

+ +

The following should be set by you in siteConfig.js as organizationName and projectName, respectively. If they are not set in your site configuration, they fall back to the CircleCI environment.

+

You can learn more about configuring automatic deployments with CircleCI in the Publishing guide.

diff --git a/docs/en/publishing.html b/docs/en/publishing.html index e2a3c15934..50a8f6f1a1 100644 --- a/docs/en/publishing.html +++ b/docs/en/publishing.html @@ -34,18 +34,20 @@ -

There is also an optional parameter that is set as an environment variable. If nothing is set for this variable, then the current branch will be used.

+

There are also two optional parameters that are set as environment variables:

Docusaurus also supports deploying user or organization sites. Just set your project name to "username.github.io" (where username is your username or organization name on GitHub) and the publish script will automatically deploy your site to the root of the master branch instead.

Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:

To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

-
GIT_USER=<GIT_USER> \
-  CURRENT_BRANCH=master \
-  yarn run publish-gh-pages # or `npm run publish-gh-pages`
+
GIT_USER=<GIT_USER> \
+  CURRENT_BRANCH=master \
+  USE_SSH=true \
+  yarn run publish-gh-pages # or `npm run publish-gh-pages`
 

 

 
The specified GIT_USER must have push access to the repository specified in the combination of organizationName and projectName.

@@ -86,7 +88,10 @@
 
Make sure to replace <GIT_USER> with the actual username of the GitHub account that will be used to publish the documentation.

 
DO NOT place the actual value of $GITHUB_TOKEN in circle.yml. We already configured that as an environment variable back in Step 3.

 

-
Unlike when you run the publish-gh-pages script manually, when the script runs within the Circle environment, the values of ORGANIZATION_NAME, PROJECT_NAME, and CURRENT_BRANCH are already defined as environment variables within CircleCI and will be picked up by the script automatically.

+
If you want to use SSH for your GitHub repo connection, you can set USE_SSH=true. So the above command would look something like: cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages.

+

+

+
Unlike when you run the publish-gh-pages script manually, when the script runs within the Circle environment, the value of CURRENT_BRANCH is already defined as an environment variable within CircleCI and will be picked up by the script automatically.

 

 
Now, whenever a new commit lands in master, CircleCI will run your suite of tests and, if everything passes, your website will be deployed via the publish-gh-pages script.