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

Deploy website

Browse source 
Deploy website version based on 6f3505d10f
This commit is contained in:
Website Deployment Script 2017-12-08 23:47:52 +00:00
parent 6f3505d10f
commit 5c770ee501
2 changed files with 17 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

10
.circle/config.yml
View file

@ -1,10 +0,0 @@
# Circle CI 2.0 Config File
# This config file will prevent tests from being run on the gh-pages branch.
version: 2
jobs:
build:
machine: true
branches:
ignore: gh-pages
steps:
-run: echo "Skipping tests on gh-pages branch"

20
docs/en/publishing.html
View file

@ -30,7 +30,7 @@
<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>
<p>One of the required parameters is set as a environment variable:</p>
<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>
@ -39,7 +39,7 @@
<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>
<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>
@ -50,7 +50,7 @@
<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>
</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://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://facebook.github.io/docusaurus">https://facebook.github.io/docusaurus</a>), because it is served from the <code>gh-pages</code> branch of the <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/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 https://<em>username</em>.github.io/<em>projectName</em>, 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://facebook.github.io/docusaurus">https://facebook.github.io/docusaurus</a>), because it is served from the <code>gh-pages</code> branch of the <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/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>
@ -96,6 +96,20 @@ deployment:
<blockquote>
<p>If you would rather use a deploy key instead of a personal access token, you can by starting with the Circle CI <a href="https://circleci.com/docs/1.0/adding-read-write-deployment-key/">instructions</a> for adding a read/write deploy key.</p>
</blockquote>
<h4><a class="anchor" aria-hidden="true" name="tips-tricks"></a><a href="#tips-tricks" 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>Tips &amp; Tricks</h4>
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a new file, <code>.circleci/config.yml</code>, in your <code>gh-pages</code> branch with the following contents:</p>
<pre><code class="hljs css yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
<span class="hljs-attr">jobs:</span>
<span class="hljs-attr"> build:</span>
<span class="hljs-attr"> machine:</span> <span class="hljs-literal">true</span>
<span class="hljs-attr"> branches:</span>
<span class="hljs-attr"> ignore:</span> <span class="hljs-string">gh-pages</span>
<span class="hljs-attr"> steps:</span>
<span class="hljs-attr"> -run:</span> <span class="hljs-string">echo</span> <span class="hljs-string">"Skipping tests on gh-pages branch"</span>
</code></pre>
<p>Once you commit and push this file to your remote <code>gh-pages</code> branch on GitHub, Circle will skip running tests on the <code>gh-pages</code> branch.</p>
</span></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="site-creation.html">← Creating your site</a><a class="docs-next button" href="custom-pages.html">Custom Pages →</a></div></div></div></div><footer class="nav-footer" id="footer"><section class="sitemap"><a href="/" class="nav-home"><img src="/img/docusaurus_monochrome.svg" alt="Docusaurus" width="66" height="58"/></a><div><h5>Docs</h5><a href="
/docs/installation.html">Getting Started</a></div><div><h5>Community</h5><a href="/en/users.html">User Showcase</a></div><div><h5>More</h5><a href="https://github.com/facebook/docusaurus">GitHub</a><a class="github-button" href="https://github.com/facebook/docusaurus" data-icon="octicon-star" data-show-count="true" aria-label="Star this project on GitHub">Star</a></div></section><a href="https://code.facebook.com/projects/" target="_blank" class="fbOpenSource"><img src="/img/oss_logo.png" alt="Facebook Open Source" width="170" height="45"/></a><section class="copyright"><span>Copyright © 2017 Facebook Inc.</span></section></footer></div><script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js"></script><script>
var search = docsearch({