3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-07-30 15:00:09 +02:00
Code Issues Projects Releases Packages Wiki Activity

Deploy website

Browse source 
Deploy website version based on f58d5ce491
This commit is contained in:
Website Deployment Script 2017-12-04 17:17:43 +00:00
parent f58d5ce491
commit 2fd028c8df
1 changed files with 19 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

33
docs/en/publishing.html
View file

@ -21,31 +21,36 @@
<blockquote>
<p>Even if your repo is private, anything published to a <code>gh-pages</code> branch will be <a href="https://help.github.com/articles/user-organization-and-project-pages/">public</a>.</p>
</blockquote>
<p>Most of the work to publish to GitHub pages is done for you automatically through the <a href="./commands.md#docusaurus-publish"><code>publish-gh-pages</code></a> script. You just need to determine the values for a few parameters required by the script. The required parameters are:</p>
<p>Most of the work to publish to GitHub pages is done for you automatically through the <a href="./commands.md#docusaurus-publish"><code>publish-gh-pages</code></a> script. You just need to determine the values for a few parameters required by the script.</p>
<p>Two of the required parameters are set in the <a href="/docs/en/site-config.html"><code>siteConfig.js</code></a>:</p>
<ul>
<li><code>organizationName</code>: The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the &quot;facebookexperimental&quot; GitHub organization.</li>
<li><code>projectName</code>: The name of the GitHub repository for your project. For example, Docusaurus is hosted at <a href="https://github.com/facebookexperimental/docusaurus">https://github.com/facebookexperimental/docusaurus</a>, so our project name in this case would be &quot;docusaurus&quot;.</li>
</ul>
<blockquote>
<p>While we recommend setting the above in <code>siteConfig.js</code>, you can also use environment variables <code>ORGANIZATION_NAME</code> and <code>PROJECT_NAME</code>.</p>
</blockquote>
<p>One of the required parameters are set as environment variables:</p>
<ul>
<li><code>CIRCLE_PROJECT_USERNAME</code>: The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the &quot;facebookexperimental&quot; GitHub organization.</li>
<li><code>CIRCLE_PROJECT_REPONAME</code>: The name of the GitHub repository for your project. For example, Docusaurus is hosted at <a href="https://github.com/facebookexperimental/docusaurus">https://github.com/facebookexperimental/docusaurus</a>, so our repo name in this case would be &quot;docusaurus&quot;.</li>
<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>
<li><code>CIRCLE_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>
</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>
<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>
</ul>
<blockquote>
<p>We currently require the published documentation to be served from the <code>gh-pages</code> branch in your GitHub repo.</p>
</blockquote>
<blockquote>
<p>The reason we prefix some of these parameters with <code>CIRCLE</code> is because Docusaurus recommends publishing your documentation continuously when changes are committed via <a href="https://circleci.org">CircleCI</a>.</p>
</blockquote>
<p>Once you have the paremeter 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>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">CIRCLE_PROJECT_USERNAME</span>=&lt;CIRCLE_PROJECT_USERNAME&gt; \
<span class="hljs-attribute">CIRCLE_PROJECT_REPONAME</span>=&lt;CIRCLE_PROJECT_REPONAME&gt; \
<span class="hljs-attribute">CIRCLE_BRANCH</span>=master \
<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`
</code></pre>
<blockquote>
<p>The specified <code>GIT_USER</code> must have push access to the repository specified in the combination of <code>CIRCLE_PROJECT_USERNAME</code> and <code>CIRCLE_PROJECT_REPONAME</code>.</p>
<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>
</blockquote>
<p>You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of <a href="https://CIRCLE_PROJECT_USERNAME.github.io/CIRCLE_PROJECT_REPONAME">https://CIRCLE_PROJECT_USERNAME.github.io/CIRCLE_PROJECT_REPONAME</a>, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is <a href="https://docusaurus.io">https://docusaurus.io</a> (it can also be accessed via <a href="https://facebookexperimental.github.io/docusaurus">https://facebookexperimental.github.io/docusaurus</a>), because it is served from the <code>gh-pages</code> branch of the <a href="https://github.com/facebookexperimental/docusaurus">https://github.com/facebookexperimental/docusaurus</a> GitHub repo. We highly encourage reading through the <a href="https://pages.github.com">GitHub Pages documentation</a> to learn more about how this hosting solution works.</p>
<p>You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of <a href="https://organizationName.github.io/projectName">https://organizationName.github.io/projectName</a>, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is <a href="https://docusaurus.io">https://docusaurus.io</a> (it can also be accessed via <a href="https://facebookexperimental.github.io/docusaurus">https://facebookexperimental.github.io/docusaurus</a>), because it is served from the <code>gh-pages</code> branch of the <a href="https://github.com/facebookexperimental/docusaurus">https://github.com/facebookexperimental/docusaurus</a> GitHub repo. We highly encourage reading through the <a href="https://pages.github.com">GitHub Pages documentation</a> to learn more about how this hosting solution works.</p>
<p>You can run the command above any time you update the docs and wish to deploy the changes to your site. Running the script manually may be fine for sites where the documentation rarely changes and it is not too much of an inconvenience to remember to manually deploy changes.</p>
<p>However, you can automate the publishing process with continuous integration (CI).</p>
<h2><a class="anchor" aria-hidden="true" name="automating-deployments-using-continuous-integration"></a><a href="#automating-deployments-using-continuous-integration" 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>Automating Deployments Using Continuous Integration</h2>
@ -85,7 +90,7 @@ deployment:
<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>CIRCLE_PROJECT_USERNAME</code>, <code>CIRCLE_PROJECT_REPONAME</code>, and <code>CIRCLE_BRANCH</code> are already defined as environment variables within CircleCI and will be picked up by the script automatically.</p>
<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>
</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>