yan
/
docusaurus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Deploy website 

Deploy website version based on 5966ce9797
This commit is contained in:
Website Deployment Script 2018-01-04 01:04:27 +00:00
parent 5966ce9797
commit 6b8d6ae00f
2 changed files with 23 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/en/commands.html
View File

@ -51,12 +51,23 @@
<h3><a class="anchor" aria-hidden="true" name="docusaurus-publish"></a><a href="#docusaurus-publish" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>docusaurus-publish</code></h3>
<p>Alias: <code>publish-gh-pages</code></p>
<p><a href="/docs/en/commands.html#docusaurus-build">Builds</a>, 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:</p>
<p>The following is generally set manually by the user in the CircleCI <code>config.yml</code> file.</p>
<ul>
<li><code>GIT_USER</code>: The git user to be associated with the deploy commit.</li>
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
</ul>
<p>e.g.,</p>
<pre><code class="hljs css bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
</code></pre>
<p>The following are set by the <a href="https://circleci.com/docs/1.0/environment-variables/">CircleCI environment</a> during the build process.</p>
<ul>
<li><code>CIRCLE_BRANCH</code>: The git branch associated with the commit that triggered the CI run.</li>
<li><code>CI_PULL_REQUEST</code>: Expected to be truthy if the current CI run was triggered by a commit in a pull request.</li>
</ul>
<p>The following should be set by you in <code>siteConfig.js</code> as <code>organizationName</code> and <code>projectName</code>, respectively. If they are not set in your site configuration, they fall back to the <a href="https://circleci.com/docs/1.0/environment-variables/">CircleCI environment</a>.</p>
<ul>
<li><code>CIRCLE_PROJECT_USERNAME</code>: The GitHub username or organization name that hosts the git repo, e.g. &quot;facebook&quot;.</li>
<li><code>CIRCLE_PROJECT_REPONAME</code>: The name of the git repo, e.g. &quot;Docusaurus&quot;.</li>
<li><code>CI_PULL_REQUEST</code>: Expected to be truthy if the current CI run was triggered by a commit in a pull request.</li>
</ul>
<p>You can learn more about configuring automatic deployments with CircleCI in the <a href="/docs/en/publishing.html">Publishing guide</a>.</p>
<hr>

17
docs/en/publishing.html
View File

@ -34,18 +34,20 @@
<ul>
<li><code>GIT_USER</code>: The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username.</li>
</ul>
<p>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.</p>
<p>There are also two optional parameters that are set as environment variables:</p>
<ul>
<li><code>CURRENT_BRANCH</code>: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be <code>master</code>, but it could be any branch (default or otherwise) except for <code>gh-pages</code>.</li>
<li><p><code>USE_SSH</code>: If this is set to <code>true</code>, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set.</p></li>
<li><p><code>CURRENT_BRANCH</code>: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be <code>master</code>, but it could be any branch (default or otherwise) except for <code>gh-pages</code>. If nothing is set for this variable, then the current branch will be used.</p></li>
</ul>
<blockquote>
<p>Docusaurus also supports deploying user or organization sites. Just set your project name to &quot;<em>username</em>.github.io&quot; (where <em>username</em> is your username or organization name on GitHub) and the publish script will automatically deploy your site to the root of the <code>master</code> branch instead.</p>
</blockquote>
<p>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:</p>
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
<pre><code class="hljs"><span class="hljs-attribute">GIT_USER</span>=&lt;GIT_USER&gt; \
<span class="hljs-attribute">CURRENT_BRANCH</span>=master \
yarn <span class="hljs-builtin-name">run</span> publish-gh-pages # <span class="hljs-keyword">or</span> `npm <span class="hljs-builtin-name">run</span> publish-gh-pages`
<pre><code class="hljs css bash">GIT_USER=&lt;GIT_USER&gt; \
CURRENT_BRANCH=master \
USE_SSH=<span class="hljs-literal">true</span> \
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
</code></pre>
<blockquote>
<p>The specified <code>GIT_USER</code> must have push access to the repository specified in the combination of <code>organizationName</code> and <code>projectName</code>.</p>
@ -86,7 +88,10 @@
<p>Make sure to replace <code>&lt;GIT_USER&gt;</code> with the actual username of the GitHub account that will be used to publish the documentation.</p>
<p><strong>DO NOT</strong> place the actual value of <code>$GITHUB_TOKEN</code> in <code>circle.yml</code>. We already configured that as an environment variable back in Step 3.</p>
<blockquote>
<p>Unlike when you run the <code>publish-gh-pages</code> script manually, when the script runs within the Circle environment, the values of <code>ORGANIZATION_NAME</code>, <code>PROJECT_NAME</code>, and <code>CURRENT_BRANCH</code> are already defined as environment variables within CircleCI and will be picked up by the script automatically.</p>
<p>If you want to use SSH for your GitHub repo connection, you can set <code>USE_SSH=true</code>. So the above command would look something like: <code>cd website &amp;&amp; npm install &amp;&amp; GIT_USER=&lt;GIT_USER&gt; USE_SSH=true npm run publish-gh-pages</code>.</p>
</blockquote>
<blockquote>
<p>Unlike when you run the <code>publish-gh-pages</code> script manually, when the script runs within the Circle environment, the value of <code>CURRENT_BRANCH</code> is already defined as an <a href="https://circleci.com/docs/1.0/environment-variables/">environment variable within CircleCI</a> and will be picked up by the script automatically.</p>
</blockquote>
<p>Now, whenever a new commit lands in <code>master</code>, CircleCI will run your suite of tests and, if everything passes, your website will be deployed via the <code>publish-gh-pages</code> script.</p>
<blockquote>